Partager via

Enumerate

  • Article

The Enumeration Endpoint implements the Enumerate operation defined in the WS-Enumeration specification. The Enumerate operation enumerates a set of objects retrieved by a query.

Parameters

Action Header

For more information, see WS-Enumeration specification.

Filter Element

When a client initiates a query, the client invokes the Enumerate method and passes in a WS-Enumeration filter that identifies the objects to retrieve. For the implementation of the WS-Enumeration provided by the FIM Service, filters are formed using a subset of the XPath language. For more information, see FIM XPath Filter Dialect.

LocalePreferences Element

As an extension to WS-Enumeration, a client can request a collection of localized objects. The <LocalePreferences> element contains one or more <LocalePreference> elements. Each <LocalePreference> element specifies a <Locale> element and precedence for that locale in case multiple localized versions of the object property have been stored in the FIM Service database. For each property corresponding to one of the requested objects, only the property value corresponding to the locale with highest precedence is returned. The <PreferenceValue> element is a positive integer that specifies the precedence of the preferred locale, with 0 indicating the highest precedence. Specifying a locale preference is optional; if it is not defined, the default locale for each object property is returned.

<xs:schema
  elementFormDefault='qualified'
  targetNamespace='https://schemas.microsoft.com/2006/11/ResourceManagement'
  xmlns:xs='http://www.w3.org/2001/XMLSchema'
  xmlns:rm='https://schemas.microsoft.com/2006/11/ResourceManagement'>
  <xs:complexType
    name='LocalePreferenceType'>
    <xs:sequence>
      <xs:element
        name='Locale'
        minOccurs='1'
        maxOccurs='1'
        nillable='false'
        type='xs:string'/>
      <xs:element
        name='PreferenceValue'
        minOccurs='1'
        maxOccurs='1'
        nillable='false'
        type='xs:integer'/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType
    name='LocalePreferencesType'>
    <xs:sequence>
      <xs:element
        name='LocalePreference'
        minOccurs='1'
        maxOccurs='unbounded'
        nillable='false'
        type='rm:LocalePreferenceType'/>
    </xs:sequence>
  </xs:complexType>
  <xs:element
    name='LocalePreferences'
    nillable='false'
    type='rm:LocalePreferencesType ' />
</xs:schema>

MaxElements Element

As an extension to WS-Enumeration, a client can request the maximum number of elements to be returned in the Enumeration Response. This element complies with the WS-Enumeration specification for the Pull method MaxElements parameter. This parameter is optional.

MaxCharacters Element

As an extension to WS-Enumeration, a client can request the maximum number of characters to be returned in the Enumeration Response. This element complies with the WS-Enumeration specification for the Pull method MaxCharacters parameter. This parameter is optional.

MaxTime Element

As an extension to WS-Enumeration, a client can request the maximum time allowed to generate the first batch of records to be returned in the Enumeration Response. This element complies with the WS-Enumeration specification for the Pull method MaxTime parameter. This parameter is optional.

Selection Element

As an extension to WS-Enumeration, a client can request that enumeration results include only specific attributes. Multiple selection elements can appear as children of the Enumerate element to select multiple attributes. If omitted, the server sorts results in an undefined way. If an attribute does not have a value for a requested attribute, the attribute is omitted for that particular result.

The following XML defines the schema for the Selection element:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement" 
targetNamespace="https://schemas.microsoft.com/2006/11/ResourceManagement"> 
  <xs:element name="Selection" type="xs:string"/> 
</xs:schema>

Sorting Element

As an extension to WS-Enumeration, a client can request that enumeration results be sorted by one attribute. If omitted, the server sorts results in an undefined way.

The following XML defines the schema for the Sorting element:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement" 
targetNamespace="https://schemas.microsoft.com/2006/11/ResourceManagement"> 
  <xs:element name="Sorting"> 
    <xs:complexType> 
      <xs:sequence> 
         <xs:element name="SortingAttribute" minOccurs="0" maxOccurs="1"> 
          <xs:complexType> 
          <xs:simpleContent> 
           <xs:extension base="xs:string"> 
            <xs:attribute name="Ascending" type="xs:string"/> 
          </xs:extension> 
         </xs:simpleContent> 
       </xs:complexType> 
      </xs:element> 
      </xs:sequence> 
      <xs:attribute name="Dialect" type="xs:string"/> 
    </xs:complexType> 
  </xs:element> 
</xs:schema>

Return Value

Action Header

For more information, see WS-Enumeration specification.

Enumeration Context Element

As specified in the WS-Enumeration specification, responses to successful invocations of the Enumerate operation will incorporate an <EnumerationContext> element. The structure of the <EnumerationContext> element is left to implementers of the WS-Enumeration specification to determine. The following XML Schema describes the structure of the enumeration context elements provided in response to successful invocations of the FIM Service endpoint's Enumerate operation.

Note

Clients should not modify the contents of the enumeration context.

The following XML defines the schema for the Enumerate element:

<?xml version="1.0" encoding="utf-8"?> 
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:wsen="https://schemas.xmlsoap.org/ws/2004/09/enumeration" 
xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement" 
targetNamespace="https://schemas.microsoft.com/2006/11/ResourceManagement"> 
  <xs:complexType name="EnumerationContextType"> 
    <xs:sequence> 
      <xs:element name="CurrentIndex" type="xs:string"/> 
      <xs:element name="EnumerationDirection" type="xs:string"/> 
      <xs:element name="Expires" type="xs:string"/>
      <xs:element name="Filter" type="xs:string"/> 
      <xs:element name="LocalePreferences" type="xs:string"/> 
      <xs:element name="Selection" type="xs:string"/> 
      <xs:element name="Sorting" type="xs:string"/> 
      <xs:element name="Count" type="xs:string"/> 
    </xs:sequence> 
  </xs:complexType> 
</xs:schema>

The following table describes the elements of this structure.

Element Description

EnumerationContext

An opaque complex type used to maintain context for pulls.

Expires Element

Responses to successful invocations of the Enumerate operation will incorporate the <Expires> element defined in the WS-Enumeration specification. This element gives the expiration time of the enumeration context. The expiration time is always calculated by the server so enumeration contexts do not expire.

EnumerationDetail Element

Also included in the response to any successful invocation of the Enumerate operation will be an <EnumerationDetail> element that provides a count of the number of objects matching the WS-Enumeration filter included in the original Enumerate request. The following code sample shows the structure of the <EnumerationDetail> element.

<?xml version='1.0' encoding='utf-8'?>
<xs:schema
  elementFormDefault='qualified'
  targetNamespace='https://schemas.microsoft.com/2006/11/ResourceManagement'
  xmlns:xs='http://www.w3.org/2001/XMLSchema'
  xmlns:rm='https://schemas.microsoft.com/2006/11/ResourceManagement'>
  <xs:complexType
    name='EnumerationDetailType'>
    <xs:sequence>
      <xs:element
        name='Count'
        minOccurs='0'
        maxOccurs='1'
        nillable='false'
        type='xs:integer'/>
    </xs:sequence>
  </xs:complexType>
  <xs:element
    name='EnumerationDetail'
    nillable='true'
    type='rm:EnumerationDetailType' />
</xs:schema>

The following table describes the elements of this schema.

Element Description

Count

A count of the number of objects that match the WS-Enumeration filter included in the Enumeration request.

EnumerationDetailType

A wrapper.

The following code example shows an EnumerationResponse message incorporating an <EnumerationDetail> element.

<s:Envelope 
  xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
  xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/08/addressing' 
  xmlns:wsen=' https://schemas.xmlsoap.org/ws/2004/09/enumeration' 
  xmlns:rm='https://schemas.microsoft.com/2006/11/ResourceManagement' >
  <s:Header>
    ...
    <wsa:Action>      
      https://schemas.xmlsoap.org/ws/2004/09/enumeration/EnumerateResponse
    </wsa:Action>
    ...
    <rm:ResourceManagement s:mustUnderstand=“true"/>
  </s:Header>
  <s:Body>
    <wsen:EnumerateResponse>
      <wsen:EnumerationContext> 
        <rm:Count>1</rm:Count> 
        <rm:CurrentIndex>0</rm:CurrentIndex> 
        <rm:EnumerationDirection>Forwards</rm:EnumerationDirection> 
        <rm:Expires>12/31/9999 11:59:59 PM</rm:Expires> 
        <rm:Filter>/ma-data</rm:Filter> 
        <rm:LocalePreferences xsi:nil="true" /> 
        <rm:Selection xsi:nil="true" /> 
        <rm:Sorting xsi:nil="true" /> 
      </wsen:EnumerationContext>       ...
      <rm:EnumerationDetail>
        <rm:Count>100</rm:Count>
      </rm:EnumerationDetail>
    </wsen:EnumerateResponse>
  </s:Body>
</s:Envelope>

Examples

Example Enumerate Message

The following code example shows an Enumerate message.

<?xml version="1.0" encoding="utf-8"?> 
<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing" 
    xmlns:wsen="https://schemas.xmlsoap.org/ws/2004/09/enumeration" 
    xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement"> 
  <s:Header> 
    <wsa:ReplyTo> 
      <wsa:Address> 
        http://www.fabrikam.com/sender 
      </wsa:Address> 
    </wsa:ReplyTo> 
    <wsa:To> 
      http://www.fabrikam.com:5725/IdentityManagementService/Enumeration 
    </wsa:To>
    <wsa:Action> 
      https://schemas.xmlsoap.org/ws/2004/09/enumeration/Enumerate 
    </wsa:Action> 
    <wsa:MessageID> 
      uuid:00000000-0000-0000-C000-000000000046 
    </wsa:MessageID> 
  </s:Header> 
  <s:Body> 
    <Enumerate xmlns="https://schemas.xmlsoap.org/ws/2004/09/enumeration" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
      <Filter Dialect="https://schemas.microsoft.com/2006/11/XPathFilterDialect">/ma-
data</Filter> 
      <LocalePreferences xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement"> 
        <LocalePreference> 
          <Locale>en-US</Locale> 
          <PreferenceValue>0</PreferenceValue> 
        </LocalePreference> 
      </LocalePreferences> 
      <MaxElements>20</MaxElements> 
      <MaxCharacters>3668672</MaxCharacters> 
      <Sorting Dialect="https://schemas.microsoft.com/2006/11/XPathFilterDialect" 
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement"> 
        <SortingAttribute Ascending="true">DisplayName</SortingAttribute> 
      </Sorting> 
      <Selection 
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">DisplayName</Selection> 
      <Selection 
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">CreatedTime</Selection> 
      <Selection 
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">Creator</Selection> 
      <Selection 
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">ObjectType</Selection> 
      <Selection 
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">ObjectID</Selection> 
      <Time xsi:nil="true"></Time> 
    </Enumerate> 
  </s:Body> 
</s:Envelope>

Example Enumerate Response

The following code example shows a response to a successful invocation of the Enumerate operation.

<s:Envelope xmlns:s=http://www.w3.org/2003/05/soap-envelope 
   xmlns:wsa="http://www.w3.org/2005/08/addressing"  
   xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance 
   xmlns:wsen="https://schemas.xmlsoap.org/ws/2004/09/enumeration 
   xmlns:xsd=http://www.w3.org/2001/XMLSchema 
   xmlns:wsc="https://schemas.microsoft.com/ws/2006/05/context" 
   xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement"> 
  <s:Header> 
    <wsa:Action s:mustUnderstand="1"> 
      https://schemas.xmlsoap.org/ws/2004/09/enumeration/EnumerateResponse 
    </wsa:Action> 
    <wsa:RelatesTo>urn:uuid:e3a74cd4-d623-47d6-b33b-0dd733808b66</wsa:RelatesTo> 
 </s:Header> 
  <s:Body u:Id="_2"> 
    <wsen:EnumerateResponse> 
      <wsen:Expires>12/31/9999 11:59:59 PM</wsen:Expires> 
      <wsen:EnumerationContext> 
        <rm:Count>1</rm:Count> 
        <rm:CurrentIndex>0</rm:CurrentIndex> 
        <rm:EnumerationDirection>Forwards</rm:EnumerationDirection> 
        <rm:Expires>12/31/9999 11:59:59 PM</rm:Expires> 
        <rm:Filter>/ma-data</rm:Filter> 
        <rm:LocalePreferences xsi:nil="true" /> 
        <rm:Selection> 
           <rm:string>DisplayName</string> 
           <rm:string>ObjectType</string> 
           <rm:string>ObjectId</string> 
           <rm:string>CreatedTime</string> 
           <rm:string>Creator</string> 
        </rm:Selection> 
        <rm:Sorting 
Dialect="https://schemas.microsoft.com/2006/11/ResourceManagement/Dialect/IdentityAttributeTyp
e-20080602"> 
           <rm:SortingAttribute Ascending="true">DisplayName</rm:SortingAttribute> 
        </rm:Sorting> 
      </wsen:EnumerationContext> 
      <rm:EnumerationDetail> 
        <rm:Count>1</rm:Count> 
      </rm:EnumerationDetail> 
    </wsen:EnumerateResponse> 
    <wsen:Items> 
       <rm:ma-data>                     
         <rm:ObjectType>ma-data</rm:ObjectType> 
         <rm:ObjectID> 
           urn:uuid:fa14aafd-d74b-4833-bd94-94c96ee1b278 
         </rm:ObjectID> 
         <rm:DisplayName>AD Management Agent</rm:DisplayName> 
         <rm:CreatedTime>2009-01-20T23:28:40.207</rm:CreatedTime> 
         <rm:Creator> 
           urn:uuid:23dbfb6c-557f-48d1-ac38-6d570ddbe189 
         </rm:Creator> 
       </rm:ma-data> 
    </wsen:Items> 
  </s:Body> 
</s:Envelope>

See Also

Concepts

Web Services Overview