Compartilhar via

  • Artigo

UpdateItem Operation

Topic Last Modified: 2009-07-17

The UpdateItem operation is used to modify the properties of an existing item in the Exchange store.

Remarks

You can perform three basic update actions on an item. The following table lists the actions that you can perform.

Action Description

Append

Adds data to an existing property. This action preserves the current data. Append does not apply to all properties.

Set

Replaces data for a property if the property contains data, or creates the property and sets its value if the property does not exist. The set action is only applicable to writable properties.

Delete

Removes a property from an item. This differs from setting a property to an empty value. When this action is finished, the property does not exist for the item. Delete is only applicable to writable properties.

An UpdateItem call can be used to modify one or more items, and one or more properties on each item. The ItemChanges element contains all the modifications that are to be performed as part of this call. The ItemChange element, a child of the ItemChanges element, represents the modifications to be performed on a single item. The ItemChange element contains a set of update actions that can be performed on a single item. These changes are contained in the Updates (Item) element. The ItemId element identifies the item to update. To update more than one property on an item, a SetItemField, AppendToItemField, or DeleteItemField must be provided for each property that requires the update.

Note

Update actions are applied in the order in which they are specified.

For each change, you have to specify the path of the property to change and a representation of that item with its new value. The delete action is slightly different in that only the path of the property that should be deleted is required. For set and append actions, the path that is specified must refer to the same property that is being set in the item representation. If these differ, an error will be returned.

The UpdateItem operation can set the value of the Start and End elements of an Exchange store item. In an UpdateItem request, the start time can be set without also setting the end time. This can cause an error if the start time is later than the end time. Be aware that client applications must adjust the end time when the start time is changed in order to preserve the duration.

When a single calendar item is updated to become a recurring master calendar item, the MeetingTimeZone element must be set by the UpdateItem operation in order to preserve the calendar item’s original time zone.

SetItemField Request Example

Description

The following example of an UpdateItem request shows how to set the sensitivity property on an item.

Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AutoResolve" 
                xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <ItemChanges>
        <t:ItemChange>
          <t:ItemId Id="AAAtAEFkb..." ChangeKey="CQAAABYAAAB..."/>
          <t:Updates>
            <t:SetItemField>
              <t:FieldURI FieldURI="item:Sensitivity"/>
              <t:Message>
                <t:Sensitivity>Normal</t:Sensitivity>
              </t:Message>
            </t:SetItemField>
          </t:Updates>
        </t:ItemChange>
      </ItemChanges>
    </UpdateItem>
  </soap:Body>
</soap:Envelope>

Comments

The item identifier and change key have been shortened to preserve readability.

SetItemField Request Elements

The following elements are used in the request:

AppendToItemField Request Example

Description

The following example of an UpdateItem request shows how to append text to the body property on an item.

Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AutoResolve" 
                xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <ItemChanges>
        <t:ItemChange>
          <t:ItemId Id="AAAtAEFkbW..." ChangeKey="CQAAABYA..."/>
          <t:Updates>
            <t:AppendToItemField>
              <t:FieldURI FieldURI="item:Body"/>
              <t:Message>
                <t:Body BodyType="Text">Some additional text to append</t:Body>
              </t:Message>
            </t:AppendToItemField>
          </t:Updates>
        </t:ItemChange>
      </ItemChanges>
    </UpdateItem>
  </soap:Body>
</soap:Envelope>

Comments

The following properties support the append action:

  • message:ReplyTo
  • item:Body
  • All the recipient and attendee collection properties

The item identifier and change key have been shortened to preserve readability.

AppendToItemField Request Elements

The following elements are used in the request:

DeleteItemField Request Example

Description

The following example of an UpdateItem request shows how to delete a property on an item.

Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AutoResolve" 
                xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <ItemChanges>
        <t:ItemChange>
          <t:ItemId Id="AAAtAEFkbWluaXN0cm..." ChangeKey="CQAAABYAA..."/>
          <t:Updates>
            <t:DeleteItemField>
              <t:FieldURI FieldURI="item:Body"/>
            </t:DeleteItemField>
          </t:Updates>
        </t:ItemChange>
      </ItemChanges>
    </UpdateItem>
  </soap:Body>
</soap:Envelope>

Comments

The item identifier and change key have been shortened to preserve readability.

DeleteItemField Request Elements

The following elements are used in the request:

Successful Response Example

Description

The following example shows a successful response to an UpdateItem request.

Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="664" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"/>
  </soap:Header>
  <soap:Body>
    <UpdateItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                        xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
      xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <m:ResponseMessages>
        <m:UpdateItemResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:Items>
            <t:Message>
              <t:ItemId Id="AAAtAEFkbW..." ChangeKey="CQAAABYAAA..."/>
            </t:Message>
          </m:Items>
        </m:UpdateItemResponseMessage>
      </m:ResponseMessages>
    </UpdateItemResponse>
  </soap:Body>
</soap:Envelope>

Comments

The item identifier and change key have been shortened to preserve readability.

Successful Response Elements

The following elements are used in the response: