Синхронизация папок с помощью EWS в ExchangeSynchronize folders by using EWS in Exchange

Узнайте, как использовать управляемый API EWS или EWS для получения списка папок или списка папок, которые были изменены, чтобы синхронизировать клиент.Find out how to use the EWS Managed API or EWS to get a list of folders, or a list of folders that have changed, in order to synchronize your client.

Служба EWS в Exchange использует синхронизацию элементов и синхронизацию папок для синхронизации содержимого почтовых ящиков между клиентом и сервером.EWS in Exchange uses item synchronization and folder synchronization to sync mailbox content between the client and server. Синхронизация папок получает исходный список папок из корневой папки, а затем получает изменения, внесенные в эти папки, а также создает новые папки.Folder synchronization gets the initial list of folders from a root folder and then, over time, gets changes that were made to those folders and gets new folders as well.

Если вы выполняете синхронизацию папок с помощью управляемого API EWS, сначала необходимо получить исходный список папок в корневой папке с помощью метода ExchangeService. SyncFolderHierarchy .If you're performing folder synchronization by using the EWS Managed API, you first get the initial list of folders in the root folder by using the ExchangeService.SyncFolderHierarchy method. Затем необходимо обновить значение параметра ксинкстате во время последующих вызовов, чтобы получить список новых и измененных папок.You then update the value of the cSyncState parameter during subsequent calls to get the list of new and changed folders.

Чтобы выполнить синхронизацию папок с помощью EWS, запросите исходный список папок в корневой папке с помощью операции SyncFolderHierarchy , выполните синтаксический анализ ответа, а затем в некоторый момент в будущем получите изменения папок в корнеи проанализируйте ответ.To perform folder synchronization by using EWS, you request the initial list of folders in the root folder by using the SyncFolderHierarchy operation, parse the response, and then at some point in the future get the changes to the folders in the root, and parse the response. После получения клиентом списка начальной или измененной папки он выполняет локальное обновление.After the client receives the list of initial or changed folders, it makes updates locally. Как и когда вы извлечете изменения в будущем, зависит от шаблона проекта синхронизации , используемого приложением.How and when you retrieve changes in the future depends on the synchronization design pattern your application is using.

Получение списка всех папок или измененных папок с помощью управляемого API EWSGet the list of all folders or changed folders by using the EWS Managed API

В приведенном ниже примере кода показано, как получить исходный список папок в корневой папке, а затем получить список изменений в папках корневой папки, произошедших с момента предыдущей синхронизации.The following code example shows how to get an initial list of folders in a root folder and then get a list of changes to folders in the root folder that have occurred since the previous synchronization. Во время начального вызова метода ExchangeService. SyncFolderHierarchy задайте для параметра ксинкстате значение null.During the initial call to the ExchangeService.SyncFolderHierarchy method, set the cSyncState value to null. После выполнения метода сохраните значение ксинкстате локально, чтобы использовать его в следующем вызове метода SyncFolderHierarchy .When the method completes, save the cSyncState value locally to use in the next SyncFolderHierarchy method call. При первом вызове и последующих вызовах папки извлекаются в пакетах десяти, с помощью последовательных вызовов метода SyncFolderHierarchy , пока не будут сохранены другие изменения.In both the initial call and the subsequent calls, the folders are retrieved in batches of ten, by using successive calls to the SyncFolderHierarchy method, until no more changes remain. В этом примере параметру Property присваивается значение идонли для уменьшения числа вызовов к базе данных Exchange, что является наилучшим вариантом синхронизации.This example sets the propertySet parameter to IdOnly to reduce calls to the Exchange database, which is a synchronization best practice. В этом примере предполагается, что Служба является допустимой привязкой объекта ExchangeService и ксинкстате представляет состояние синхронизации, возвращенное предыдущим вызовом в SyncFolderHierarchy.In this example, we assume that service is a valid ExchangeService object binding and that cSyncState represents the sync state that was returned by a prior call to SyncFolderHierarchy.

// Get a list of all folders in the mailbox by calling SyncFolderHierarchy.
// The folderId parameter must be set to the root folder to synchronize. 
// The propertySet parameter is set to IdOnly to reduce calls to the Exchange database
// because any additional properties result in additional calls to the Exchange database. 
// The syncState parameter is set to cSyncState, which should be null in the initial call, 
// and should be set to the sync state returned by the previous SyncFolderHierarchy call 
// in subsequent calls.
ChangeCollection<FolderChange> fcc = service.SyncFolderHierarchy(new FolderId(WellKnownFolderName.Root), PropertySet.IdOnly, cSyncState);
// If the count of changes is zero, there are no changes to synchronize.
if (fcc.Count == 0)
{
    Console.WriteLine("There are no folders to synchronize.");
}
// Otherwise, write all the changes included in the response 
// to the console. 
// For the initial synchronization, all the changes will be of type
// ChangeType.Create.
else
{
    foreach (FolderChange fc in fcc)
    {
        Console.WriteLine("ChangeType: " + fc.ChangeType.ToString());
        Console.WriteLine("FolderId: " + fc.FolderId);
        Console.WriteLine("===========");
    }
}
// Save the sync state for use in future SyncFolderItems requests.
// The sync state is used by the server to determine what changes to report
// to the client.
string fSyncState = fcc.SyncState;

После получения списка новых или измененных папок на сервере Создайте или обновите папки на клиенте.After you retrieve the list of new or changed folders on the server, create or update the folders on the client.

Получение исходного списка папок с помощью EWSGet the initial list of folders by using EWS

В следующем примере показан XML-запрос для получения исходной иерархии папок с помощью операции SyncFolderHierarchy .The following example shows an XML request to get the initial folder hierarchy by using the SyncFolderHierarchy operation. Это также запрос XML, который управляемый API EWS отправляет при получении списка исходных папок с помощью метода SyncFolderHierarchy.This is also the XML request that the EWS Managed API sends when retrieving the list of initial folders by using the SyncFolderHierarchy method. Элемент синкстате операции SyncFolderHierarchy не включается, так как это начальная синхронизация.The SyncState element of the SyncFolderHierarchy operation is not included because this is the initial synchronization. В этом примере для элемента басешапе задается значение идонли для уменьшения числа вызовов к базе данных Exchange, что является наилучшим вариантом синхронизации.This example sets the BaseShape element to IdOnly to reduce calls to the Exchange database, which is a synchronization best practice.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
                    xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
                    xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2013" />
  </soap:Header>
  <soap:Body>
    <m:SyncFolderHierarchy>
      <m:FolderShape>
        <t:BaseShape>IdOnly</t:BaseShape>
      </m:FolderShape>
      <m:SyncFolderId>
        <t:DistinguishedFolderId Id="root" />
      </m:SyncFolderId>
    </m:SyncFolderHierarchy>
  </soap:Body>
</soap:Envelope>

В следующем примере показан ответ XML, возвращенный сервером после обработки запроса операции SyncFolderHierarchy .The following example shows the XML response that is returned by the server after it processes the SyncFolderHierarchy operation request. Исходный ответ содержит элементы CREATE для всех папок, так как во время начальной синхронизации все папки считаются новыми.The initial response includes Create elements for all folders because all folders are considered new during an initial synchronization. Значения некоторых атрибутов и элементов были сокращены для удобочитаемости, а некоторые блоки элементов создания были удалены для краткости.The values of some attributes and elements have been shortened for readability, and some Create element blocks were removed for brevity.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ServerVersionInfo MajorVersion="15"
                         MinorVersion="0"
                         MajorBuildNumber="785"
                         MinorBuildNumber="6"
                         Version="V2_6"
                         xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns="https://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <m:SyncFolderHierarchyResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
                                   xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:SyncFolderHierarchyResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:SyncState>H4sIAA==</m:SyncState>
          <m:IncludesLastFolderInRange>true</m:IncludesLastFolderInRange>
          <m:Changes>
            <t:Create>
              <t:Folder>
                <t:FolderId Id="AAMkADM="
                            ChangeKey="AQAAABYA"/>
              </t:Folder>
            </t:Create>
            <t:Create>
              <t:Folder>
                <t:FolderId Id="AAMkADMzM="
                            ChangeKey="AQAAABY"/>
              </t:Folder>
            </t:Create>
            <t:Create>
              <t:Folder>
                <t:FolderId Id="AAMkAD/AAA="
                            ChangeKey="AQAAABYA"/>
              </t:Folder>
            </t:Create>
            <t:Create>
              <t:Folder>
                <t:FolderId Id="AAMkADBh="
                            ChangeKey="AQAAABYA"/>
              </t:Folder>
            </t:Create>
            ...
          </m:Changes>
        </m:SyncFolderHierarchyResponseMessage>
      </m:ResponseMessages>
    </m:SyncFolderHierarchyResponse>
  </s:Body>
</s:Envelope>

После получения списка новых папок на сервере Создайте папки на клиенте.After you retrieve the list of new folders on the server, create the folders on the client.

Получение изменений с момента последней синхронизации с помощью EWSGet the changes since the last sync by using EWS

В следующем примере показан XML-запрос для получения списка изменений в папках корневой папки с помощью операции SyncFolderHierarchy .The following example shows the XML request to get the list of changes to folders in the root folder by using the SyncFolderHierarchy operation. Это также запрос XML, который отправляет управляемый API EWS при получении списка изменений в корневой папке.This is also the XML request that the EWS Managed API sends when retrieving the list of changes to the root folder. В этом примере для элемента синкстате задается значение, возвращенное в предыдущем ответе.This example sets the SyncState element value to the value returned in the previous response. Для демонстрационных целей в этом примере для элемента басешапе задается значение аллпропертиес вместо идонли для отображения возвращаемых дополнительных свойств.And for demonstration purposes, this example sets the BaseShape element to AllProperties instead of IdOnly to show the additional properties returned. Задание элемента басешапе равным идонли является наилучшим методом синхронизации.Setting the BaseShape element to IdOnly is a synchronization best practice. Значение синкстате было сокращено для удобочитаемости.The value of SyncState has been shortened for readability.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
                    xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
                    xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2013" />
  </soap:Header>
  <soap:Body>
    <m:SyncFolderHierarchy>
      <m:FolderShape>
        <t:BaseShape>AllProperties</t:BaseShape>
      </m:FolderShape>
      <m:SyncFolderId>
        <t:DistinguishedFolderId Id="root" />
      </m:SyncFolderId>
      <m:SyncState>H4sIAA==</m:SyncState>
    </m:SyncFolderHierarchy>
  </soap:Body>
</soap:Envelope>

В следующем примере показан ответ XML, возвращенный сервером после обработки запроса операции SyncFolderHierarchy от клиента.The following example shows the XML response that is returned by the server after it processes the SyncFolderHierarchy operation request from the client. Этот ответ указывает на то, что одна папка была обновлена, была создана одна папка и удалена одна папка с момента предыдущей синхронизации.This response indicates that one folder was updated, one folder was created, and one folder was deleted since the prior synchronization. Значение элемента синкстате , атрибуты ID и атрибуты чанжекэй были сокращены для удобочитаемости.The value of the SyncState element, Id attributes, and ChangeKey attributes have been shortened for readability.

Помните, что запрос включал в себя аллпропертиесбасешапе.Remember that the request included the AllPropertiesBaseShape. Это только для демонстрационных целей.This is just for demonstration purposes. Рекомендуется присвоить элементу басешапе значение идонли в рабочей среде.We recommend that you set the BaseShape element to IdOnly in production.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
<h:ServerVersionInfo MajorVersion="15" MinorVersion="0" MajorBuildNumber="745" MinorBuildNumber="21" Version="V2_3" 
           xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types" 
           xmlns="https://schemas.microsoft.com/exchange/services/2006/types" 
           xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <m:SyncFolderHierarchyResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
            xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:SyncFolderHierarchyResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:SyncState>H4sIAAA</m:SyncState>
          <m:IncludesLastFolderInRange>true</m:IncludesLastFolderInRange>
          <m:Changes>
            <t:Update>
              <t:Folder>
                <t:FolderId Id="AAMkADM=" ChangeKey="AQAAABY" />
                <t:ParentFolderId Id="AQMkADMzADI1==" ChangeKey="AQAAAA==" />
                <t:FolderClass>IPF.Note</t:FolderClass>
                <t:DisplayName>Meeting Notes</t:DisplayName>
                <t:TotalCount>3</t:TotalCount>
                <t:ChildFolderCount>0</t:ChildFolderCount>
                <t:EffectiveRights>
                  <t:CreateAssociated>true</t:CreateAssociated>
                  <t:CreateContents>true</t:CreateContents>
                  <t:CreateHierarchy>true</t:CreateHierarchy>
                  <t:Delete>true</t:Delete>
                  <t:Modify>true</t:Modify>
                  <t:Read>true</t:Read>
                  <t:ViewPrivateItems>true</t:ViewPrivateItems>
                </t:EffectiveRights>
                <t:UnreadCount>0</t:UnreadCount>
              </t:Folder>
            </t:Update>
            <t:Create>
              <t:Folder>
                <t:FolderId Id="AAMkADMzM=" ChangeKey="AQAAABYAA" />
                <t:ParentFolderId Id="AQMkO67A==" ChangeKey="AQAAAA==" />
                <t:FolderClass>IPF.Note</t:FolderClass>
                <t:DisplayName>Schedules</t:DisplayName>
                <t:TotalCount>0</t:TotalCount>
                <t:ChildFolderCount>0</t:ChildFolderCount>
                <t:EffectiveRights>
                  <t:CreateAssociated>true</t:CreateAssociated>
                  <t:CreateContents>true</t:CreateContents>
                  <t:CreateHierarchy>true</t:CreateHierarchy>
                  <t:Delete>true</t:Delete>
                  <t:Modify>true</t:Modify>
                  <t:Read>true</t:Read>
                  <t:ViewPrivateItems>true</t:ViewPrivateItems>
                </t:EffectiveRights>
                <t:UnreadCount>0</t:UnreadCount>
              </t:Folder>
            </t:Create>
            <t:Delete>
              <t:FolderId Id="AAMkAD/AAA=" ChangeKey="AQAAAA==" />
            </t:Delete>
          </m:Changes>
        </m:SyncFolderHierarchyResponseMessage>
      </m:ResponseMessages>
    </m:SyncFolderHierarchyResponse>
  </s:Body>
</s:Envelope>

Обновление клиентаUpdate the client

Если вы используете управляемый API EWS, после получения списка новых или измененных папок используйте метод Folder. Load для получения свойств новых или измененных элементов, сравнения свойств с локальными значениями, а также для обновления или создания папок на клиенте.If you're using the EWS Managed API, after you get the list of new or changed folders, use the Folder.Load method to get properties on the new or changed items, compare the properties to the local values, and update or create the folders on the client.

Если вы используете EWS, используйте операцию " операция с папкой " для получения свойств новых или измененных папок и обновления или создания папок на клиенте.If you're using EWS, use the GetFolder operation to get properties on the new or changed folders and update or create the folders on the client.

См. такжеSee also