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.
Copy Code | |
---|---|
<xs:schema elementFormDefault='qualified' targetNamespace='http://schemas.microsoft.com/2006/11/ResourceManagement' xmlns:xs='http://www.w3.org/2001/XMLSchema' xmlns:rm='http://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:
Copy Code | |
---|---|
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:rm="http://schemas.microsoft.com/2006/11/ResourceManagement" targetNamespace="http://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:
Copy Code | |
---|---|
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:rm="http://schemas.microsoft.com/2006/11/ResourceManagement" targetNamespace="http://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:
Copy Code | |
---|---|
<?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:wsen="http://schemas.xmlsoap.org/ws/2004/09/enumeration" xmlns:rm="http://schemas.microsoft.com/2006/11/ResourceManagement" targetNamespace="http://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.
Copy Code | |
---|---|
<?xml version='1.0' encoding='utf-8'?> <xs:schema elementFormDefault='qualified' targetNamespace='http://schemas.microsoft.com/2006/11/ResourceManagement' xmlns:xs='http://www.w3.org/2001/XMLSchema' xmlns:rm='http://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.
Copy Code | |
---|---|
<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing' xmlns:wsen=' http://schemas.xmlsoap.org/ws/2004/09/enumeration' xmlns:rm='http://schemas.microsoft.com/2006/11/ResourceManagement' > <s:Header> ... <wsa:Action> http://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.
Copy Code | |
---|---|
<?xml version="1.0" encoding="utf-8"?> <s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsen="http://schemas.xmlsoap.org/ws/2004/09/enumeration" xmlns:rm="http://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> http://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="http://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="http://schemas.microsoft.com/2006/11/XPathFilterDialect">/ma- data</Filter> <LocalePreferences xmlns="http://schemas.microsoft.com/2006/11/ResourceManagement"> <LocalePreference> <Locale>en-US</Locale> <PreferenceValue>0</PreferenceValue> </LocalePreference> </LocalePreferences> <MaxElements>20</MaxElements> <MaxCharacters>3668672</MaxCharacters> <Sorting Dialect="http://schemas.microsoft.com/2006/11/XPathFilterDialect" xmlns="http://schemas.microsoft.com/2006/11/ResourceManagement"> <SortingAttribute Ascending="true">DisplayName</SortingAttribute> </Sorting> <Selection xmlns="http://schemas.microsoft.com/2006/11/ResourceManagement">DisplayName</Selection> <Selection xmlns="http://schemas.microsoft.com/2006/11/ResourceManagement">CreatedTime</Selection> <Selection xmlns="http://schemas.microsoft.com/2006/11/ResourceManagement">Creator</Selection> <Selection xmlns="http://schemas.microsoft.com/2006/11/ResourceManagement">ObjectType</Selection> <Selection xmlns="http://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.
Copy Code | |
---|---|
<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="http://schemas.xmlsoap.org/ws/2004/09/enumeration xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:wsc="http://schemas.microsoft.com/ws/2006/05/context" xmlns:rm="http://schemas.microsoft.com/2006/11/ResourceManagement"> <s:Header> <wsa:Action s:mustUnderstand="1"> http://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="http://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> |