Artikel
06/14/2014

Customizing Get and Find Responses in Exchange Web Services

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Topic Last Modified: 2008-06-24

By John Gibbon, Senior Software Development Engineer

The retrieval methods in Exchange Web Services provide a mechanism for the client to specify exactly which properties to return, instead of returning a static set of properties. By using response shapes, clients can request only the properties that are required for an operation. This reduces the work that is performed by the store and the bytes that are sent over the wire.

Retrieving Objects in Exchange Web Services

Before we delve into response shapes, let’s first review the two primary ways to retrieve objects by using Exchange Web Services: the Get methods and Find methods. These include the following:

Whereas Get methods retrieve individual items or folders based on the item or folder ID, Find methods return groups of items or folders based on filtering and grouping parameters. Generally, Find methods are more efficient than Get methods for returning groups of objects; however, it is important to be aware that Find methods do not return the same set of properties that Get methods return. For example, large properties, such as Body, and properties that require an Active Directory directory service lookup, such as ToRecipients, are not returned by the FindItem method. See Mark Taylor’s article Finding the Message Body for a detailed comparison of properties that are returned by FindItem and GetItem.

Response Shape

Both Find methods and Get methods provide a mechanism for specifying the properties to return, that is, the “shape” of the response that will be received from the server, as follows:

GetItem and FindItem use ItemShape to identify the properties requested.
GetFolder and FindFolder use FolderShape to identify the properties requested.

Listing 1 shows the general structure of an item response shape.

Listing 1 ItemShape

<ItemShape>
  <BaseShape />
  <IncludeMimeContent />
  <BodyType />
  <AdditionalProperties />
</ItemShape>

Listing 2 shows the general structure of a folder response shape.

Listing 2 FolderShape

<FolderShape>
  <BaseShape />
  <AdditionalProperties />
</FolderShape>

ItemShape and FolderShape Common Elements

As you can see, ItemShape and FolderShape include two common elements, BaseShape and AdditionalProperties. The client uses these elements to specify which properties the server should return.

Exchange Web Services defines three base sets of properties that you can select from by setting the value of BaseShape within the request. BaseShape may be set to one of the following values:

IdOnly Returns only the ID of the object requested.
DefaultProperties Returns the most common properties of an object, based on the type of object requested. (This means that the default set of properties returned for a contact differs from the default set of properties returned for a message.)
AllProperties Returns all properties of an object that appear in the schema.

AdditionalProperties allows you to request specific properties that you want to be returned in addition to those included with BaseShape. For performance reasons, you should minimize the use of the AllProperties and DefaultProperties BaseShapes. Where you can, use the IdOnly BaseShape and specify other properties under AdditionalProperties.

Optional ItemShape Elements

ItemShape includes the following two optional elements that are not found in FolderShape:

IncludeMimeContent Indicates whether to return the MIME content for an object (true or false).
BodyType Indicates the format of the message body to be returned (Best, Html, or Text).

Using ItemShape in a GetItem Request

Although most developers do not hand-code the XML for a Web service method call, it is useful to understand the XML that is generated by the proxy. Listing 3 shows a GetItem request that contains ItemShape.

Listing 3 GetItem request that uses ItemShape

<GetItem >
  <ItemShape>
    <t:BaseShape>IdOnly</t:BaseShape>
    <t:AdditionalProperties>
      <t:FieldURI FieldURI="item:Subject"/>
      <t:FieldURI FieldURI="item:IsDraft"/>
    </t:AdditionalProperties>
  </ItemShape>
  <ItemIds> 
    <t:ItemId Id="AAAcABRN0Zjag..." ChangeKey="BXAAANYX..." />
  </ItemIds> 
</GetItem >

In this example, the ItemShape element only includes BaseShape and AdditionalProperties child elements. The IncludeMimeContent and BodyType elements are optional and are not specified. The response to this request will include the following three properties:

ItemId (specified in BaseShape).
Subject (specified in AdditionalProperties).
IsDraft (specified in AdditionalProperties).

As you can see, properties under AdditionalProperties are identified by field URI. The field URIs for the most common properties are contained in the schema. For properties that are not listed in the schema, use the ExtendedFieldURI. For more information about the AdditionalProperties element, see AdditionalProperties.

Listing 4 shows an example of proxy code that specifies the ItemShape element that is shown in Listing 3.

Listing 4 GetItem request that uses ItemShape (proxy code)

GetItemType request = new GetItemType();

// Set the response shape.
request.ItemShape = new ItemResponseShapeType();
// Set BaseShape to IdOnly.
request.ItemShape.BaseShape = DefaultShapeNamesType.IdOnly;

// Include subject and isDraft properties in AdditionalProperties.
PathToUnindexedFieldType subject = new PathToUnindexedFieldType();
subject.FieldURI = UnindexedFieldURIType.itemSubject; 

PathToUnindexedFieldType isDraft = new PathToUnindexedFieldType();
isDraft.FieldURI = UnindexedFieldURIType.itemIsDraft;

BasePathToElementType[] AdditionalProperties = new BasePathToElementType[] { subject, isDraft };
request.ItemShape.AdditionalProperties = additionalProperties;

// Set up the array of item IDs to retrieve (only one item in this example).
ItemIdType itemId = new ItemIdType();
itemId.Id = id;

request.ItemIds = new BaseItemIdType[1];
request.ItemIds[0] = itemId;

// Call the GetItem EWS method and pass in the request that was just created.
GetItemResponseType response = this.service.GetItem(request);

GetItem Response

Finally, here’s the response that was received from the server. As expected, it returns three properties of the item: ItemId, Subject, and IsDraft.

Listing 5 GetItem response

<GetItemResponse xmlns:m=".../messages"
                 xmlns:t=".../types"
                 xmlns=".../messages">
  <m:ResponseMessages>
    <m:GetItemResponseMessage ResponseClass="Success">
      <m:ResponseCode>No Error</m:ResponseCode>
      <m:Items>
        <t:Message>
          <t:ItemId Id=" AAAcABRN0Zjag..." ChangeKey=" BXAAANYX..." />
          <t: Subject>This is the e-mail subject</t:Subject>
          <t:IsDraft>false</t:IsDraft>
        </t:Message>
      </m:Items>
    </m:GetItemResponseMessage>
  </m:ResponseMessages>
</GetItemResponse>

Additional Resources

For more information about how to customize Get and Find responses in Exchange Web Services, see the following resources:

Dela via