Поделиться через

Работа с папками с помощью EWS в Exchange

  • Статья

Узнайте, как создавать, получать, редактировать и удалять папки с помощью управляемого API EWS или служб EWS в Exchange.

EWS в Exchange использует папки для структурирования и организации почтовых ящиков. Вы можете создавать, получать, редактировать и удалять папки с помощью управляемого API EWS или служб EWS. Каждый из методов или операций, перечисленных в следующей таблице, выполняется над объектом Folder, типом Folder или одним из производных классов или типов папок.

Таблица 1. Методы и операции для создания, получения, обновления и удаления папок

Задача Метод управляемого API EWS Операция EWS
Создание папки Folder.Save CreateFolder
Создание иерархии папок Недоступно CreateFolderPath
Получение папки Folder.Bind GetFolder
Получение иерархии папок Folder.FindFolders FindFolder
Обновление папки Folder.Update UpdateFolder
Удаление папки Folder.Delete DeleteFolder

Создание папки с помощью управляемого API EWS

В следующем примере кода показано, как использовать класс Folder для создания общей папки с DisplayName "Настраиваемая папка" и значением свойства FolderClass для IPF.Note. Метод Folder.Save сохраняет папку в качестве дочерней в папке "Входящие".

В этих примерах предполагается, что служба является действительным объектом ExchangeService, и что пользователь прошел проверку подлинности на сервере Exchange server.

// Create a custom folder.
Folder folder = new Folder(service);
folder.DisplayName = "Custom Folder";
folder.FolderClass = "IPF.Note";
// Save the folder as a child folder of the Inbox.
folder.Save(WellKnownFolderName.Inbox);

Чтобы создать папку другого типа, например CalendarFolder, ContactsFolder, SearchFolder или TasksFolder, создайте новый экземпляр определенного класса (вместо универсального класса Folder) и не устанавливайте свойство FolderClass. Например, в следующем примере кода показано, как создать TasksFolder.

// Create a custom Tasks folder.
TasksFolder folder = new TasksFolder(service);
folder.DisplayName = "Custom Tasks";
// Save the folder as a child folder in the Inbox folder.
// This method call results in a CreateFolder call to EWS.
folder.Save(WellKnownFolderName.Inbox);

Если вы пытаетесь создать экземпляр определенного класса и также установить свойство FolderClass, отобразится ошибка ErrorNoFolderClassOverride.

Обратите внимание, что вы не можете пакетно создать несколько папок в одном вызове метода с помощью управляемого API EWS.

Создание папки с помощью EWS

С помощью EWS можно создать одну или несколько папок.

Чтобы создать одну папку, отправьте сообщение запроса операции CreateFolder. Запрос операции CreateFolder указывает, что родительская папка — это папка "Входящие", DisplayName — "Настраиваемая папка", а значение элемента FolderClass — IPF.Note.

Управляемое API EWS также отправляет запрос XML при создании новой папки и вызове метода Folder.Save.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
  </soap:Header>
  <soap:Body>
    <m:CreateFolder>
      <m:ParentFolderId>
        <t:DistinguishedFolderId Id="inbox" />
      </m:ParentFolderId>
      <m:Folders>
        <t:Folder>
          <t:FolderClass>IPF.Note</t:FolderClass>
          <t:DisplayName>Custom Folder</t:DisplayName>
        </t:Folder>
      </m:Folders>
    </m:CreateFolder>
  </soap:Body>
</soap:Envelope>

В ответ на запрос CreateFolder сервер отправляет сообщение CreateFolderResponse, включающее параметр ResponseCode со значением NoError, которое указывает, что сообщение было успешно создано, и свойство FolderId созданного сообщения.

Чтобы создать несколько папок, включите несколько элементов Folder в сообщение запроса операции CreateFolder. Все новые папки должны быть в одной родительской папке.

Создание иерархии папок с помощью EWS

Иерархию папок можно создать одним вызовом с помощью операции EWS CreateFolderPath. Такая функциональность недоступна в управляемом API EWS. Вместо этого, если вы используете управляемый API EWS, вы можете создавать папки по одной, как показано в ст. Создание папки с помощью EWS.

Примечание.

Управляемый API EWS не реализует эту функцию.

Получение папки с помощью управляемого API EWS

В следующем примере кода показано, как использовать метод Folder.Bind для получения папки "Входящие". Рекомендуем возвращать только те свойства, которые требуются для вашего приложения. В этом примере свойства, которые возвращаются, включают только свойство Id путем создания объекта PropertySet и применения значения IdOnly к свойству BasePropertySet.

В этом примере предполагается, что служба является действительным объектом ExchangeService, и что пользователь прошел проверку подлинности на сервере Exchange server.

// As a best practice, limit the properties returned to only those that are required.
// In this scenario, you only need the FolderId.
PropertySet propSet = new PropertySet(BasePropertySet.IdOnly);
// Bind to an existing folder and get only the properties specified in the PropertySet.
// This method call results in a GetFolder call to EWS.
Folder rootfolder = Folder.Bind(service, WellKnownFolderName.Inbox, propSet);

Если вам нужно вернуть дополнительные свойства, добавьте свойства из класса FolderSchema в PropertySet или используйте один из перегруженных методов Bind, который возвращает все свойства первого класса.

Обратите внимание, что невозможно получить несколько папок одновременно с помощью управляемого API EWS. Необходимо вызвать метод Bind для каждой папки отдельно.

Получение папки с помощью EWS

С помощью EWS можно получить одну или несколько папок.

Чтобы получить одну папку, отправьте сообщение запроса операции GetFolder на сервер. В следующем примере для BaseShape задан о значение IdOnly, поэтому от указанной папки возвращается только FolderId. Элемент FolderIds указывает, что извлекаемая папка — это папка "Входящие".

Управляемое API EWS также отправляет запрос XML при привязке к папке с помощью метода Folder.Bind.

Чтобы получить несколько папок, включите несколько элементов FolderIds в сообщение запроса операции GetFolder.

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

В следующем примере XML показано сообщение GetFolderResponse, отправленное с сервера клиенту в ответ на запрос операции GetFolder. Оно содержит только значение FolderId папки "Входящие". Для удобства значения некоторых атрибутов и элементов были сокращены.

<?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="800"
                         MinorBuildNumber="16"
                         Version="V2_6"
                         xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns="http://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:GetFolderResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
                         xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:GetFolderResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:Folders>
            <t:Folder>
              <t:FolderId Id="AAAENAAA=" ChangeKey="AQAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAEkbCr"/>
            </t:Folder>
          </m:Folders>
        </m:GetFolderResponseMessage>
      </m:ResponseMessages>
    </m:GetFolderResponse>
  </s:Body>
</s:Envelope>

Получение иерархии папок с помощью управляемого API EWS

Следующий пример кода показывает, как извлечь вложенные папки для указанной корневой папки. Вложенные папки в этом примере извлекаются из папки MsgFolderRoot, которая является корнем поддерева IPM (где хранятся папки и элементы вашего почтового ящика).

В этом примере создается объект класса FolderView, чтобы ограничить результаты ответа метода Folder.FindFolders. Этот сценарий ограничивает возвращаемые свойства следующими значениями: Id, DisplayName, и расширенное свойство, указывающее, является ли папка скрытой. Для FolderView.Traversal установите значение "Deep" для выполнения рекурсивного поиска, чтобы сервер извлекал вложенные папки. Установите для корневой папки значение MsgFolderRoot, чтобы сервер возвращал все папки пользователя (сервер не возвращает системные папки в поддереве Non-IPM).

В этом примере предполагается, что служба является действительным объектом ExchangeService, и что пользователь прошел проверку подлинности на сервере Exchange server.

// Create a new folder view, and pass in the maximum number of folders to return.
FolderView view = new FolderView(folderViewSize);
// Create an extended property definition for the PR_ATTR_HIDDEN property,
// so that your results will indicate whether the folder is a hidden folder.
ExtendedPropertyDefinition isHiddenProp = new ExtendedPropertyDefinition(0x10f4, MapiPropertyType.Boolean);
// As a best practice, limit the properties returned to only those required.
// In this case, return the folder ID, DisplayName, and the value of the isHiddenProp
// extended property.
view.PropertySet = new PropertySet(BasePropertySet.IdOnly, FolderSchema.DisplayName, isHiddenProp);
// Indicate a Traversal value of Deep, so that all subfolders are retrieved.
view.Traversal = FolderTraversal.Deep;
// Call FindFolders to retrieve the folder hierarchy, starting with the MsgFolderRoot folder.
// This method call results in a FindFolder call to EWS.
FindFoldersResults findFolderResults = service.FindFolders(WellKnownFolderName.MsgFolderRoot, view);

Получение иерархии папок с помощью EWS

В следующих примерах XML показано, как использовать операцию FindFolder для получения иерархии папок с помощью EWS. В этом примере извлекается папка msgfolderroot, которая является корнем поддерева IPM, и всех его вложенных папок. Для атрибута Traversal задано значение Deep, чтобы сервер выполнял рекурсивный поиск в иерархии папок и возвращал только папки и вложенные папки под указанным корнем в ответе. В этом примере для элемента BaseShape задано значение IdOnly, чтобы сервер возвращал только элемент FolderId. Чтобы сделать выходные данные более понятными, включите элемент DisplayName в результаты, добавив его в элемент AdditionalProperties в запросе, и значение ExtendedFieldURI для свойства PR_ATTR_HIDDEN, чтобы видеть, являются ли папки скрытыми.

Управляемое API EWS также отправляет запрос XML при вызове метода FindFolders.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
  </soap:Header>
  <soap:Body>
    <m:FindFolder Traversal="Deep">
      <m:FolderShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
          <t:FieldURI FieldURI="folder:DisplayName" />
          <t:ExtendedFieldURI PropertyTag="4340"
                              PropertyType="Boolean" />
        </t:AdditionalProperties>
      </m:FolderShape>
      <m:IndexedPageFolderView MaxEntriesReturned="100"
                               Offset="0"
                               BasePoint="Beginning" />
      <m:ParentFolderIds>
        <t:DistinguishedFolderId Id="msgfolderroot" />
      </m:ParentFolderIds>
    </m:FindFolder>
  </soap:Body>
</soap:Envelope>

В следующем примере XML показано сообщение FindFolderResponse, отправленное с сервера клиенту в ответ на запрос операции FindFolder. Оно содержит только FolderId, DisplayNameи значение расширенного свойства PR_ATTR_HIDDEN для всех вложенных папок в папке msgrootfolder. Если для элемента Value установлено значение "true", папка должна быть скрыта в представлении клиента.

Управляемое API EWS также отправляет ответ XML при получении нескольких папок с помощью метода FindFolder. Значения некоторых атрибутов и элементов были сокращены для удобства чтения, а некоторые папки не включены для краткости.

<?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="815"
                         MinorBuildNumber="6"
                         Version="V2_7"
                         xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns="http://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:FindFolderResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
                          xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:FindFolderResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:RootFolder IndexedPagingOffset="16"
                        TotalItemsInView="16"
                        IncludesLastItemInRange="true">
            <t:Folders>
              <t:CalendarFolder>
                <t:FolderId Id="AAAEOAAA="
                            ChangeKey="AgAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAA3"/>
                <t:DisplayName>Calendar</t:DisplayName>
                <t:ExtendedProperty>
                  <t:ExtendedFieldURI PropertyTag="0x10f4"
                                      PropertyType="Boolean"/>
                  <t:Value>false</t:Value>
                </t:ExtendedProperty>
              </t:CalendarFolder>
              <t:ContactsFolder>
                <t:FolderId Id="AAAEPAAA="
                            ChangeKey="AwAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAA4"/>
                <t:DisplayName>Contacts</t:DisplayName>
                <t:ExtendedProperty>
                  <t:ExtendedFieldURI PropertyTag="0x10f4"
                                      PropertyType="Boolean"/>
                  <t:Value>false</t:Value>
                </t:ExtendedProperty>
              </t:ContactsFolder>
              <t:ContactsFolder>
                <t:FolderId Id="AAAUKAAA="
                            ChangeKey="AwAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAS5"/>
                <t:DisplayName>Recipient Cache</t:DisplayName>
                <t:ExtendedProperty>
                  <t:ExtendedFieldURI PropertyTag="0x10f4"
                                      PropertyType="Boolean"/>
                  <t:Value>true</t:Value>
                </t:ExtendedProperty>
              </t:ContactsFolder>
              <t:Folder>
                <t:FolderId Id="AAAUJAAA="
                            ChangeKey="AQAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAASx"/>
                <t:DisplayName>Conversation Action Settings</t:DisplayName>
                <t:ExtendedProperty>
                  <t:ExtendedFieldURI PropertyTag="0x10f4"
                                      PropertyType="Boolean"/>
                  <t:Value>true</t:Value>
                </t:ExtendedProperty>
              </t:Folder>
…
            </t:Folders>
          </m:RootFolder>
        </m:FindFolderResponseMessage>
      </m:ResponseMessages>
    </m:FindFolderResponse>
  </s:Body>
</s:Envelope>

Обновление папки с помощью управляемого API EWS

В следующем примере кода показано, как обновить отображаемое имя папки с помощью управляемого API EWS.

Сначала создайте PropertySet, чтобы ограничить количество свойств, которые сервер возвращает в ответе Folder.Bind. Рекомендуется использовать IdOnlyBasePropertySet для уменьшения количества вызовов к базе данных Exchange. Затем используйте метод Bind для привязки к папке для обновления. Затем обновите свойство DisplayName и используйте метод Folder.Update, чтобы сохранить изменения.

В этом примере предполагается, что служба является действительным объектом ExchangeService, и что пользователь прошел проверку подлинности на сервере Exchange server. Локальная переменная folderId — это идентификатор обновляемой папки.

// As a best practice, only include the ID value in the PropertySet.
PropertySet propertySet = new PropertySet(BasePropertySet.IdOnly);
// Bind to an existing folder and get the FolderId.
// This method call results in a GetFolder call to EWS.
Folder folder = Folder.Bind(service, folderId, propertySet);
// Update the display name of the folder.
folder.DisplayName = "Updated folder name";
// Save the updates.
// This method call results in an UpdateFolder call to EWS.
folder.Update();

Обновление папки с помощью EWS

В следующем примере XML показано, как обновить отображаемое имя папки с помощью EWS.

Сначала отправьте сообщение запроса операции GetFolder, чтобы получить папку для обновления, как показано в ст. Получение иерархии папок с помощью EWS.

Затем отправьте сообщение запроса операции UpdateFolder на сервер для обновления папки. Запрос операции UpdateFolder обновляет DisplayName до значения "Обновленная пользовательская папка".

Управляемое API EWS также отправляет запрос XML при обновлении папки с помощью метода Folder.Update. Для удобства значения некоторых атрибутов и элементов были сокращены.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
  </soap:Header>
  <soap:Body>
    <m:UpdateFolder>
      <m:FolderChanges>
        <t:FolderChange>
          <t:FolderId Id="OrV9ZAAA=" ChangeKey="AQAAABYAAABVzRdyy/cHS4XTC9itCRdUAAAOrXWb" />
          <t:Updates>
            <t:SetFolderField>
              <t:FieldURI FieldURI="folder:DisplayName" />
              <t:Folder>
                <t:DisplayName>Updated Custom Folder</t:DisplayName>
              </t:Folder>
            </t:SetFolderField>
          </t:Updates>
        </t:FolderChange>
      </m:FolderChanges>
    </m:UpdateFolder>
  </soap:Body>
</soap:Envelope>

Сервер отвечает на запрос UpdateFolder сообщением UpdateFolderResponse, которое содержит значение ResponseCodeNoError и значение FolderId папки, обновленной с помощью обновленного значения атрибута ChangeKey.

Удаление папки с помощью управляемого API EWS

В этой статье приводится базовый пример удаления папки с помощью управляемого API EWS. Дополнительные сведения об удалении папок см. в ст. Удаление папки с помощью управляемого API EWS.

Чтобы удалить папку с помощью управляемого API EWS, сначала используйте метод Folder.Bind, чтобы привязать объект службы к папке для удаления. Затем используйте метод Folder.Delete для удаления папки с помощью режима удаления HardDelete.

В этом примере предполагается, что служба является действительным объектом ExchangeService, и что пользователь прошел проверку подлинности на сервере Exchange server. Локальная переменная folderId — это идентификатор удаляемой папки.

// Bind to an existing folder and get all its properties.
// This method call results in a GetFolder call to EWS.
Folder folder = Folder.Bind(service, folderId);
// HardDelete the folder.
// This method call results in a DeleteFolder call to EWS.
folder.Delete(DeleteMode.HardDelete);

Удаление папки с помощью EWS

В этой статье приводится базовый пример XML для удаления папки с помощью EWS. Дополнительные сведения об удалении папок см. в ст. Удаление папки с помощью управляемого API EWS.

Чтобы удалить папку с помощью EWS, сначала отправьте сообщение запроса операции GetFolder, чтобы получить папку для обновления, как показано в ст. Получение папки с помощью EWS.

Затем отправьте сообщение запроса операции DeleteFolder на сервер для удаления папки. Запрос операции DeleteFolder указывает, что элемент DeleteType имеет значение HardDelete и содержит FolderId удаляемой папки.

Управляемое API EWS также отправляет запрос XML при удалении папки с помощью метода Folder.Delete. Для удобства значения некоторых атрибутов и элементов были сокращены.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" 
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
  </soap:Header>
  <soap:Body>
    <m:DeleteFolder DeleteType="HardDelete">
      <m:FolderIds>
        <t:FolderId Id="OrV9ZAAA=" ChangeKey="AQAAABYAAABVzRdyy/cHS4XTC9itCRdUAAAOrXWf" />
      </m:FolderIds>
    </m:DeleteFolder>
  </soap:Body>
</soap:Envelope>

В ответ на запрос DeleteFolder сервер отправляет сообщение DeleteFolderResponse, включающее параметр ResponseCode со значением NoError, которое указывает, что папка успешно удалена.

Дальнейшие действия

После получения папок на сервере или внесения в них изменений может потребоваться синхронизировать иерархию папок или подписаться на уведомления об изменениях папок на сервере.

См. также