Get

  • Article

The FIM Service Resource Endpoint implements the WS-Transfer: Identity Management Operations for Directory Access Extensions specification (WS-Transfer IMO) version of the Get operation.

Because the object to which a Get request refers is identified by a reference property that refers specifically to the object, the Get operation will only support identifying a specific object, not querying for an object. Indeed, if the operation is to be compliant with WS-Transfer and WS-Transfer IMO, it cannot support querying. Queries for objects should be directed to the Enumeration Endpoint of the FIM Service.

The default endpoint address for Get is https://Localhost:5725/ResourceManagementService/Resource.

One optional element can be included as sub-elements of the <ResourceReference> element. The <Locale> value specifies the localized representation of the object. If only one version of the object exists in the FIM Service database, the <ResourceReference> element will not contain the <Time> or <Locale> sub-elements.

Parameters

Action Header

Refer to the WS-Transfer: Identity Management Operations for Directory Access Extensions specification.

Reference Property Header

According to the WS-Transfer specification and, by implication, the WS-Transfer Extensions for Identity Management Operations specification, specific resources are identified by WS-Addressing reference properties. The WS-Addressing specification states that when a resource identified by a reference property is referred to in a request, the reference properties are just copied into the header of the request message. A sample Get message from the WS-Transfer specification is reproduced in the following example. A particular customer is identified using reference properties, shown in bold, in the header of the message.

ResourceReference Schema

<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'
  elementFormDefault='qualified'>
<xs:element
  name='ResourceReferenceProperty'
  type='rm:ReferenceType'/>
</xs:schema>

ResourceReference Schema Elements

Element Description

ResourceReferenceProperty

A globally-unique identifier for the created object. The identifier is of type Reference (see Schema Data Types).

ResourceReference Locale Schema

<?xml version='1.0' encoding='utf-8' ?>
<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'
  elementFormDefault='qualified'>
<xs:element
    name='Locale'
    type='xsd:string'/>
</xs:schema>

ResourceReference Locale Schema Elements

Element Description

Locale

A value indicating a specific locale for the object. This element is optional; if no time is present, the invariant object is represented.

ResourceReference Examples

ReferenceProperty Example Description

<wsa:ReferenceProperties> <rm:ResourceReferenceProperty> 03CED96B-BE01-4C18-95A5-FCD2FAA09C25 </rm:ResourceReferenceProperty> </wsa:ReferenceProperties>

The object whose Object ID is 03CED96B-BE01-4C18-95A5-FCD2FAA09C25.

<wsa:ReferenceProperties> <rm:ResourceReferenceProperty> 03CED96B-BE01-4C18-95A5-FCD2FAA09C25 </rm:ResourceReferenceProperty> <rm:Locale> en-UK </rm:Locale> </wsa:ReferenceProperties>

The object whose Object ID is 03CED96B-BE01-4C18-95A5-FCD2FAA09C25 presented in a United Kindom representation.

Type and Value Element

Get requests to the Resource endpoint of the FIM Servicemust identify the elements to be retrieved or updated. Those elements must be identified in compliance with the WS-Transfer IMO specification, and they must be identified using the Identity Attribute Type 1.0 dialect defined in the Identity Attribute Type 1.0 dialect specification.

Return Values

Action Header

Refer to the WS-Transfer IMO specification.

Resource Transfer Header

Refer to the WS-Transfer IMO specification.

GetResponse Element

Refer to the WS-Transfer IMO specification.

Examples

Sample Invocation of the Get 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:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:da="https://schemas.microsoft.com/2006/11/IdentityManagement/DirectoryAccess"      
xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement"> 
  <s:Header> 
    <wsa:Action>https://schemas.xmlsoap.org/ws/2004/09/transfer/Get</wsa:Action> 
    <da:IdentityManagementOperation s:mustUnderstand="1"  /> 
    <rm:ResourceReferenceProperty> 
      urn:uuid:fa14aafd-d74b-4833-bd94-94c96ee1b278 
    </rm:ResourceReferenceProperty> 
      <wsa:MessageID> 
          urn:uuid:928f9abe-875d-4bc1-bb5f-d1be16c035c3 
      </wsa:MessageID> 
      <wsa:ReplyTo> 
         <wsa:Address>http://www.w3.org/2005/08/addressing/anonymous</wsa:Address> 
      </wsa:ReplyTo> 
    <wsa:To> 
      http://www.fabrikam.com:5725/IdentityManagementService/Resource 
    </wsa:To> 
  </s:Header> 
  <s:Body> 
    <da:BaseObjectSearchRequest Dialect=" 
https://schemas.microsoft.com/2006/11/ResourceManagement/Dialect/IdentityAttributeType-
20080602">
       <da:AttributeType>ObjectType</da:AttributeType> 
      <da:AttributeType>DisplayName</da:AttributeType> 
    </da:BaseObjectSearchRequest > 
  </s:Body> 
</s:Envelope>

Note that because the object to which a Get request refers is identified by a reference property that refers specifically to the object, the Get operation will only support identifying a specific object, not querying for an object.

Sample response to an invocation of the Get operation

<s:Envelope 
   xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
   xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing" 
   xmlns:wsc="https://schemas.microsoft.com/ws/2006/05/context"   xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement" >xmlns:da="https://schemas.microsoft.com/2006/11/IdentityManagementService/DirectoryAccess">
  <s:Header>
    <wsa:To>
      http://www.woodgrovebank.com/sender
    </wsa:To>
    <wsa:Action>
      https://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse
    </wsa:Action>
    <wsa:MessageID>
      uuid:0000010e-0000-0000-C000-000000000048
    </wsa:MessageID>
    <wsa:RelatesTo>
      uuid:00000000-0000-0000-C000-000000000048
    </wsa:RelatesTo>
  </s:Header>
  <s:Body>
    <da:BaseObjectSearchResponse>
      <da:PartialAttribute>
        <rm:DisplayName>Identity Management Team</rm:DisplayName>
      </da:PartialAttribute>
      <da:PartialAttribute>
          <rm:ExplicitMember>
            22222222-2222-2222-2222-222222222222
          </rm:ExplicitMember>
          <rm:ExplicitMember>
            33333333-3333-3333-3333-333333333333
          </rm:ExplicitMember>
      </da:PartialAttribute>
    </da:BaseObjectSearchResponse>
  </s:Body>
</s:Envelope>

Sample invocation of the Get operation to retrieve fragments of the XML representation of a Group identified using the Identity Attribute Type 1.0 dialect

A sample invocation of the Get operation of the FIM Service Resource endpoint is shown in the following sample. The text in bold indicates what is specific to the FIM Service implementation of the WS-Transfer specification: the address of the service, the use of the ResourceReferenceProperty element as the reference property, and the names and values for object properties.

<s:Envelope 
  xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
  xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing" 
  xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement">
  xmlns:da="https://schemas.microsoft.com/2006/11/IdentityManagementService/DirectoryAccess">
  <s:Header>
    <wsa:ReplyTo>
      <wsa:Address>
         http://www.woodgrovebank.com/sender
      </wsa:Address>
    </wsa:ReplyTo>
    <wsa:To> 
           http://www.woodgrovebank.com:5725/IdentityManagementService/Resource
    </wsa:To>
    <rm:ResourceReferenceProperty>
      03CED96B-BE01-4C18-95A5-FCD2FAA09C25
    </rm:ResourceReferenceProperty>
    <wsa:Action>
      https://schemas.xmlsoap.org/ws/2004/09/transfer/Get
    </wsa:Action>
    <wsa:MessageID>
      uuid:00000000-0000-0000-C000-000000000046
    </wsa:MessageID>
    <rm:ResourceManagement s:mustUnderstand=“true"/>
  </s:Header>
  <s:Body>
    <da:BaseObjectSearchRequest-Dialect="https://schemas.microsoft.com/2006/11/ResourceManagement/Dialect/IdentityAttributeType-20080602">
      <da:AttributeType>
        DisplayName
      </da:AttributeType>
      <da:AttributeType>
        ExplicitMember
      </da:AttributeType>
    </da:BaseObjectSearchRequest>
  </s:Body>
</s:Envelope>

A sample response to the preceding Get request is shown in the next sample.

See Also

Concepts

Resource Endpoint
Enumeration Endpoint