Справка по API REST расширений данных Office 365

Область применения: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Примечание

Эта документация охватывает бета-версию API расширений данных Office 365 в предварительной версии. Функции в предварительной версии до завершения ознакомительного периода могут быть изменены, что может привести к неработоспособности кода, написанного с их использованием. Поэтому в своем производственном коде вы должны использовать только производственную версию API. Если она доступна, предпочтительной в настоящее время является версия 2.0.

API REST расширений данных Office 365 позволяет приложениям динамически хранить пользовательские данные в сообщениях, событиях или контактах учетной записи пользователя. Учетная запись может быть учетной записью Office 365 или Майкрософт (Hotmail.com, Live.com, MSN.com, Outlook.com и Passport.com).

Примечание

Для упрощения этой справки в остальной части этой статьи при упоминании Outlook.com также подразумеваются и эти домены учетной записи Майкрософт.

Не интересуетесь бета-версией API? В оглавлении слева, перейдите к разделу Справка по API REST Office 365 и выберите нужную версию.

Обзор

Расширение данных в API REST Outlook представляет собой открытый тип OData v4, содержащий свойства, которые можно указать во время выполнения. Вы можете использовать API расширений данных для расширения экземпляра типа сущности, уже определенного в модели данных сущности (EDM) — сообщения, события или контакта — путем динамического указания пользовательских свойств и значений в полезных данных JSON. Это делает определение таких типов сущностей более гибким и помогает экономить время на определении новых типов сущностей специально для этой цели.

Свойство ExtensionName — единственное свойство, определенное для всех расширений. Чтобы обеспечить уникальность имен расширений, можно использовать формат обратных DNS, который зависит от принадлежащего вам домена, например Com.Contoso.Contact. Не указывайте домен Microsoft в имени расширения.

Поскольку расширение является открытым типом, можно указать дополнительные данные, специфичные для экземпляра объекта. Например, вы можете создать расширение для отдельных деловых контактов, которое отслеживает пользовательские данные, такие как название компании и начальный реферер, и указать данные в полезных данных JSON по примеру ниже:

POST https://outlook.office.com/api/beta/me/contacts('{contact_id}')/extensions
{
   @odata.type: "Microsoft.OutlookServices.OpenTypeExtension",  
   "ExtensionName": "Com.Contoso.Customer",
   "CompanyName": "Alpine Skis",
   "InitialReferrer":  "Robin McCall"
}

Вы можете использовать API расширений данных для выполнения операций CRUD для нового или существующего ресурса. Подробнее см. в разделе поддерживаемые операции.

Дополнительные сведения об открытом типе OData см. в документации OData v4 по адресу OData.org.

Использование API REST расширений данных

Расширения данных или расширенные свойства?

Расширения данных — рекомендуемое решение для большинства случаев, предусматривающих хранение пользовательских данных и доступ к ним. Однако если вам нужно получить доступ к пользовательским данным для свойств MAPI Outlook, которые еще не указаны в метаданных API REST Outlook, используйте расширенные свойства и соответствующий REST API. Вы можете проверить, какие свойства предоставляются с помощью метаданных, на странице https://outlook.office.com/api/{version}/$metadata, заменив {version} на нужную версию (v2.0, beta и т. д.).

Проверка подлинности

Как и для других API REST Outlook, для каждого запроса к API расширения данных необходимо включать допустимый маркер доступа. Для получения маркера доступа необходимо зарегистрироваться, идентифицировать свою программу и получить соответствующее разрешение.

Вы можете изучить дополнительные сведения о некоторых оптимизированных параметрах регистрации и авторизации. Об этом следует помнить при выполнении конкретных действий в API расширений данных.

Поддерживаемые ресурсы REST

Вы можете создавать расширения для экземпляров следующих ресурсов в конечной точке REST Outlook:

• Message
• Event
• Contact

Версия API

Статус этого API был повышен с предварительной до общедоступной версии (GA). Он поддерживается в версиях 2.0 и beta:

https://outlook.office.com/api/v2.0/

https://outlook.office.com/api/beta/

Параметры URL-адреса

В примерах этой статьи в параметрах URL-адресов запроса REST используются следующие заполнители ИД. Необходимо указать ИД экземпляра ресурса, для которого нужно создать расширение.

Параметр	Тип	Описание
Параметры URL-адреса
contact_id	string	ИД контакта.
event_id	string	ИД события.
message_id	string	ИД сообщения.

Дополнительные сведения, общие для всех подразделов API REST Outlook и API REST расширений данных Office 365, см. в разделе Использование API REST Outlook.

Операции расширения

• Создание расширения в существующем элементе
• Создание расширения в новом элементе
• Возврат расширения
• Возврат элемента с включением расширения
• Поиск и возврат элементов с включением расширения
• Добавление или изменение данных в расширении
• Удаление расширения

Создание расширения в существующем элементе

Создание расширения и добавление пользовательских свойств для указанного экземпляра ресурса. Ресурсом может быть сообщение, событие календаря или контакт в Office 365 или Outlook.com. Данные в полезной нагрузке JSON могут относиться к элементарным типам или массивам элементарных типов.

Создание расширения для каждого из поддерживаемых ресурсов:

POST https://outlook.office.com/api/beta/me/messages('{message_id}')/extensions
POST https://outlook.office.com/api/beta/me/events('{event_id}')/extensions
POST https://outlook.office.com/api/beta/me/contacts('{contact_id}')/extensions

Минимальная требуемая область

Одна из следующих областей для чтения и записи, соответствующих целевому ресурсу:

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Параметр	Тип	Описание
Параметры текста сообщения
ExtensionName	string	Уникальный текстовый идентификатор расширения. Обязательный.

Пример запроса

В этом примере создается расширение для указанного сообщения. Текст запроса для расширения включает:

• Тип Microsoft.OutlookServices.OpenTypeExtension, который определяется как открытый тип OData в метаданных API REST Outlook.
• Имя расширения "Com.Contoso.Referral".
• Дополнительные данные, которые необходимо сохранить в качестве пользовательских свойств в полезных данных JSON: CompanyName, DealValue и ExpirationDate (содержат простые типы), а также TopModels и TopSalespersons (содержат массивы простых типов).

POST https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions

Content-Type: application/json

{ 
  "@odata.type" : "Microsoft.OutlookServices.OpenTypeExtension", 
  "ExtensionName" : "Com.Contoso.Referral", 
  "CompanyName" : "Wingtip Toys",
  "DealValue@odata.type": "#Int64", 
  "DealValue" : 500050, 
  "ExpirationDate" : "2015-12-03T10:00:00.000Z",
  "TopModels": [
     3001,
     4002,
     5003
  ],
  "TopSalespersons": [
     "Dana Swope",
     "Fanny Downs",
     "Randi Welch"
  ]
} 

Пример отклика

При успешном выполнении ответ содержит код отклика HTTP 201 Created.

Текст ответа для нового расширения включает следующее:

• Свойство по умолчанию ExtensionName.
• Свойство id с полным именем Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral.
• Сохраняемые пользовательские данные.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue@odata.type": "#Int64",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "TopModels@odata.type": "#Collection(Int32)",
    "TopModels": [
      3001,
      4002,
      5003
    ],
    "TopSalespersons@odata.type": "#Collection(String)",
    "TopSalespersons": [
      "Dana Swope",
      "Fanny Downs",
      "Randi Welch"
    ]
}

Создание расширения в новом элементе

Создание одного или нескольких расширений при создании нового экземпляра ресурса в одном вызове POST, а также добавление пользовательских свойств в расширение. Ресурсом может быть сообщение, событие календаря или контакт в Office 365 или Outlook.com. Данные в полезной нагрузке JSON могут относиться к элементарным типам или массивам элементарных типов.

Чтобы создать расширение для каждого из поддерживаемых ресурсов, нужно сделать вызов POST, как при создании этого ресурса, и включить расширение в текст запроса POST.

POST https://outlook.office.com/api/beta/me/messages
POST https://outlook.office.com/api/beta/me/events
POST https://outlook.office.com/api/beta/me/contacts

Минимальная требуемая область

Одна из следующих областей для чтения и записи, соответствующих целевому ресурсу:

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Параметр	Тип	Описание
Параметры текста сообщения
ExtensionName	string	Уникальный текстовый идентификатор расширения. Обязательный.

Пример запроса

В этом примере показано создание сообщения и расширения в одном вызове. Текст запроса включает следующее:

• Свойства Subject, Body и ToRecipients, характерные для нового сообщения.
• Данные для расширения:
  • Тип Microsoft.OutlookServices.OpenTypeExtension, который определяется как открытый тип OData в метаданных API REST Outlook.
  • Имя расширения "Com.Contoso.Referral".
  • Дополнительные данные, которые необходимо сохранить в качестве пользовательских свойств в полезных данных JSON: CompanyName, ExpirationDate и DealValue (содержат простые типы), а также TopModels и TopSalespersons (содержат массивы простых типов).

POST https://outlook.office.com/api/beta/me/messages

Content-Type: application/json

{
  "Subject": "Annual review",
  "Body": {
    "ContentType": "HTML",
    "Content": "You should be proud!"
  },
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com"
      }
    }
  ],
  "Extensions": [
    {
      "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

Пример отклика

При успешном выполнении ответ содержит код отклика HTTP 201 Created.

Текст ответа включает свойства нового сообщения и следующие данные для нового расширения:

• Свойство id с полным именем Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral.
• Стандартное свойство extensionName, указанное в запросе.
• Пользовательские данные из запроса, сохраненные в виде настраиваемых свойств.

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
  "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')",
  "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj\"",
  "Id": "AAMkAGEbs88AAB84uLuAAA=",
  "CreatedDateTime": "2015-10-30T03:03:43Z",
  "LastModifiedDateTime": "2015-10-30T03:03:43Z",
  "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj",
  "Categories": [ ],
  "ReceivedDateTime": "2015-10-30T03:03:43Z",
  "SentDateTime": "2015-10-30T03:03:43Z",
  "HasAttachments": false,
  "Subject": "Annual review",
  "Body": {
    "ContentType": "HTML",
    "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r
\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nYou should be proud!\r\n</body>\r
\n</html>\r\n"
  },
  "BodyPreview": "You should be proud!",
  "Importance": "Normal",
  "ParentFolderId": "AQMkAGEwAAAIBDwAAAA==",
  "Sender": null,
  "From": null,
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com",
        "Name": "John Doe"
      }
    }
  ],
  "CcRecipients": [ ],
  "BccRecipients": [ ],
  "ReplyTo": [ ],
  "ConversationId": "AAQkAGEFGugh3SVdMzzc=",
  "IsDeliveryReceiptRequested": false,
  "IsReadReceiptRequested": false,
  "IsRead": true,
  "IsDraft": true,
  "WebLink": "https://outlook.office.com/owa/?
ItemID=AAMkAGEbs88AAB84uLuAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
  "MentionedMe": null,
  "Mentioned": [ ],
  "InferenceClassification": "Focused",
  "Extensions@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages
('AAMkAGEbs88AAB84uLuAAA%3D')/Extensions",
  "Extensions": [
    {
      "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
      "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
      "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels@odata.type": "#Collection(Int32)",
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons@odata.type": "#Collection(String)",
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

Возврат расширения

Получение расширения по имени или идентификатору в указанном экземпляре ресурса. Ресурсом может быть сообщение, событие календаря или контакт в Office 365 или Outlook.com.

При получении расширения по имени или по идентификатору возвращается тот же самый текст ответа.

GET https://outlook.office.com/api/beta/me/messages('{message_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/beta/me/events('{event_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')/extensions('{extensionId}')

Минимальная требуемая область

Одна из следующих областей чтения, соответствующих целевому ресурсу:

• https://outlook.office.com/mail.read
• https://outlook.office.com/calendars.read
• https://outlook.office.com/contacts.read
• wl.imap
• wl.calendars
• wl.contacts_calendars
• wl.basic

Параметр	Тип	Описание
Параметр URL-адреса
extensionId	string	Это может быть имя расширения, которое является текстовым идентификатором, уникальным среди всех расширений в экземплярах ресурса, или полное имя, которое объединяет тип расширения и уникальный текстовый идентификатор. Полное имя возвращается в свойстве id при создании расширения. Обязательный.

Пример запроса

Первый пример ссылается на расширение по его имени и получает расширение в указанном сообщении.

GET https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

Второй пример ссылается на расширение по его идентификатору (полное имя) и получает расширение в указанном сообщении.

GET https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Пример отклика

При успешном выполнении ответ содержит код отклика HTTP 200 OK.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00Z"
}

Возврат элемента с включением расширения

Возврат экземпляра ресурса с расширением, которое задается фильтром по Id. Ресурсом может быть сообщение, событие календаря или контакт в Office 365 или Outlook.com.

Вы можете отфильтровать Id по имени расширения или полному имени, а затем получить экземпляр с расширением, как показано ниже. Убедитесь, что для символов пробела в строке фильтра используется кодирование URL.

GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/beta/me/events('{event_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

Минимальная требуемая область

Одна из следующих областей чтения, соответствующих целевому ресурсу:

• https://outlook.office.com/mail.read
• https://outlook.office.com/calendars.read
• https://outlook.office.com/contacts.read
• wl.imap
• wl.calendars
• wl.contacts_calendars
• wl.basic

Параметр	Тип	Описание
Параметр URL-адреса
extensionId	string	Это может быть имя расширения, которое является текстовым идентификатором, уникальным среди всех расширений в экземплярах ресурса, или полное имя, которое объединяет тип расширения и уникальный текстовый идентификатор. Полное имя возвращается в свойстве id при создании расширения. Обязательный.

Пример запроса

В следующем примере указанное сообщение возвращается и расширяется включением расширения из фильтра. Фильтр возвращает расширение, Id которого совпадает с полным именем.

Для удобства в запросе, представленном ниже, в URL-адресе кодируется зарезервированный знак — пробел.

GET https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')?$expand=Extensions($filter=Id%20eq%20'Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Пример отклика

При успешном выполнении ответ содержит код отклика HTTP 200 OK.

Текст отклика включает все свойства указанного сообщения и расширения, возвращенного фильтром.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
    "Id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
    "Categories": [
    ],
    "CreateDateTime": "2015-06-19T02:03:31Z",
    "LastModifiedDateTime": "2015-08-13T02:28:00Z",
    "Subject": "Attached is the requested info",
    "BodyPreview": "See the images attached.",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "Importance": "Normal",
    "HasAttachments": true,
    "ParentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
    "From": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "Sender": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "ToRecipients": [
        {
            "EmailAddress": {
                "Address": "wendy@contoso.com",
                "Name": "Wendy Molina"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
    "ReceivedDateTime": "2015-06-19T02:05:04Z",
    "SentDateTime": "2015-06-19T02:04:59Z",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsDraft": false,
    "IsRead": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "Extensions@odata.context": "https://outlook.office.com/api/beta/$metadata#Users('desmond40contoso.com')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions", 
    "Extensions": [ 
      { 
        "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
        "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
        "ExtensionName": "Com.Contoso.Referral",
        "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
        "CompanyName": "Wingtip Toys",
        "DealValue": 500050,
        "ExpirationDate": "2015-12-03T10:00:00Z"
      }
     ]
}

Поиск и возврат элементов с включением расширения

Вы можете найти экземпляры ресурса, которые содержат расширение, соответствующее фильтру. Кроме того, в том же запросе вы можете получить экземпляры с включением расширения. Запросы в этом разделе находят такие экземпляры, расширяют и включают расширение в ответ.

Ресурсом может быть сообщение, событие календаря или контакт в Office 365 или Outlook.com.

Вы можете отфильтровать Id по имени расширения или полному имени, а затем получить экземпляр с расширением, как показано ниже. Убедитесь, что для символов пробела в строке фильтра используется кодирование URL.

GET https://outlook.office.com/api/beta/me/messages?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/beta/me/events?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/beta/me/contacts?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

Минимальная требуемая область

Одна из следующих областей чтения, соответствующих целевому ресурсу:

• https://outlook.office.com/mail.read
• https://outlook.office.com/calendars.read
• https://outlook.office.com/contacts.read
• wl.imap
• wl.calendars
• wl.contacts_calendars
• wl.basic

Параметр	Тип	Описание
Параметр URL-адреса
extensionId	string	Это может быть имя расширения, которое является текстовым идентификатором, уникальным среди всех расширений в экземплярах ресурса, или полное имя, которое объединяет тип расширения и уникальный текстовый идентификатор. Полное имя возвращается в свойстве id при создании расширения. Обязательный.

Пример запроса

В следующем примере выполняется поиск по всем сообщениям в почтовом ящике пользователя, который выполнил вход, для нахождения сообщений, содержащих расширение в соответствии с фильтром, и включения этого расширения. Фильтр возвращает расширения, которые содержатId, соответствующий имени расширения Com.Contoso.Referral.

Для удобства в запросе, представленном ниже, в URL-адресе кодируется зарезервированный знак — пробел.

GET https://outlook.office.com/api/beta/me/messages?$filter=Extensions/any(f:f/Id%20eq%20'Com.Contoso.Referral')&$expand=Extensions($filter=Id%20eq%20'Com.Contoso.Referral')

Пример отклика

При успешном выполнении ответ содержит код отклика HTTP 200 OK.

Текст отклика включает все сообщения, которые содержат соответствующее расширение, и все свойства этих сообщений. В этом примере ответ содержит два сообщения.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages",
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.EventMessage",
            "@odata.id": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')",
            "@odata.etag": "W/\"DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn\"",
            "Id": "AAMkADIyDREAAA=",
            "CreatedDateTime": "2016-01-06T02:20:17Z",
            "LastModifiedDateTime": "2016-01-13T02:13:54Z",
            "ChangeKey": "DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:18Z",
            "SentDateTime": "2016-01-06T02:20:18Z",
            "HasAttachments": false,
            "InternetMessageId": "<BY1PR19MB0023E92E0B43F5E268406F0DF5F40@BY1PR19MB0023.namprd19.prod.outlook.com>",
            "Subject": "Accepted: Latin American Product Manual Group",
            "Body": {
                "ContentType": "Text",
                "Content": ""
            },
            "BodyPreview": "",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAAEJAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyWejUoYAg=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": true,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyDREAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "MeetingMessageType": "MeetingAccepted",
            "StartDateTime": {
                "DateTime": "2015-01-05T19:00:00.0000000",
                "TimeZone": "UTC"
            },
            "EndDateTime": {
                "DateTime": "2015-01-05T20:30:00.0000000",
                "TimeZone": "UTC"
            },
            "Location": {
                "DisplayName": "Mt. Adams"
            },
            "Type": "SeriesMaster",
            "Recurrence": {
                "Pattern": {
                    "Type": "RelativeMonthly",
                    "Interval": 2,
                    "Month": 0,
                    "DayOfMonth": 0,
                    "DaysOfWeek": [
                        "Monday"
                    ],
                    "FirstDayOfWeek": "Sunday",
                    "Index": "First"
                },
                "Range": {
                    "Type": "NoEnd",
                    "StartDate": "2015-01-05",
                    "EndDate": "0001-01-01",
                    "RecurrenceTimeZone": "tzone://Microsoft/Utc",
                    "NumberOfOccurrences": 0
                }
            },
            "IsOutOfDate": false,
            "Extensions@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkADIyDREAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500300,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ],
            "Event@odata.associationLink": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')/$ref",
            "Event@odata.navigationLink": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')"
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')",
            "@odata.etag": "W/\"CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq\"",
            "Id": "AAMkADIyAHVAAA=",
            "CreatedDateTime": "2016-01-06T02:20:02Z",
            "LastModifiedDateTime": "2016-01-13T02:24:50Z",
            "ChangeKey": "CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:02Z",
            "SentDateTime": "2016-01-06T02:20:01Z",
            "HasAttachments": false,
            "InternetMessageId": "<CY1PR19MB0032531C620A46068FDDD45DE3F40@CY1PR19MB0032.namprd19.prod.outlook.com>",
            "Subject": "International Launch Planning for XT2000",
            "Body": {
                "ContentType": "HTML",
                "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nWe will be ready to ship XT 2000 on 10/1, how's the International launch plan going?<br>\r\n<div style=\"display:inline-block\">\r\n<table border=\"0\" cellspacing=\"0\" style=\"background-color:#F4F4F4\">\r\n<tbody>\r\n<tr>\r\n<td style=\"padding:20px; font-size:12px; color:#666666\">You're receiving this message because you're a subscribed member of the Engineering group.<br>\r\n<a href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=conversations&amp;source=EscalatedMessage\">View group conversations</a> |\r\n<a href=\"https://adatumltd.sharepoint.com/_layouts/groupstatus.aspx?id=dbcbe107-6244-40ba-b0f1-1c46ad35435d&amp;target=documents\">\r\nView group files</a> | <a id=\"BD5134C6-8D33-4ABA-A0C4-08581FDF89DB\" href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=unsubscribe&amp;source=EscalatedMessage\">\r\nUnsubscribe</a></td>\r\n</tr>\r\n</tbody>\r\n</table>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "BodyPreview": "We will be ready to ship XT 2000 on 10/1, how's the International launch plan going?\r\nYou're receiving this message because you're a subscribed member of the Engineering group.\r\nView group conversations | View group files | Unsubscribe",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAEMAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "Engineering",
                    "Address": "engineering@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "Garret Vargas",
                    "Address": "GarretV@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyLESZnSPc=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": false,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyAHVAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "Extensions@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkADIyAHVAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/beta/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500050,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ]
        }
    ]
} 

Добавление или изменение данных в расширении

Обновление расширения с использованием свойств из текста запроса:

• Если свойство в тексте запроса совпадает с именем существующего свойства в расширении, то данные в расширении будут обновлены.
• В противном случае это свойство и его данные будут добавлены в расширение.

Расширение содержится в ресурсе, которым может быть сообщение, событие календаря или контакт в Office 365 или Outlook.com. На него можно ссылаться по имени или идентификатору — будет возвращен одинаковый ответ. Данные в полезной нагрузке JSON могут относиться к элементарным типам или массивам элементарных типов.

PATCH https://outlook.office.com/api/beta/me/messages('{message_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/beta/me/events('{event_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/beta/me/contacts('{contact_id}')/extensions('{extensionId}')

Минимальная требуемая область

Одна из следующих областей для чтения и записи, соответствующих целевому ресурсу:

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Параметр	Тип	Описание
Параметр URL-адреса
extensionId	string	Это может быть имя расширения, которое является текстовым идентификатором, уникальным среди всех расширений в экземплярах ресурса, или полное имя, которое объединяет тип расширения и уникальный текстовый идентификатор. Полное имя возвращается в свойстве id при создании расширения. Обязательный.
Параметры текста сообщения
ExtensionName	string	Уникальный текстовый идентификатор расширения. Обязательный.

Пример запроса

В каждом из двух примеров в этом разделе используется расширение из примера получения расширения, приведенного выше. В первом случае ссылка на расширение осуществляется по имени, во втором — по идентификатору. Тексты запросов и ответов совпадают.

В каждом примере расширение выше обновляется путем:

• изменив значение параметра CompanyName с Wingtip Toys на Wingtip Toys (USA)
• изменив значение параметра DealValue с 500050 на 500100; 500100
• добавив новые данные в качестве пользовательского свойства Updated

В этом примере ссылка на расширение осуществляется по его имени:

PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
} 

В этом примере ссылка на расширение осуществляется по его идентификатору (полному имени):

PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
} 

Пример отклика

Ответ об успешном выполнении характеризуется наличием кода HTTP 200 OK, а обновленное расширение возвращается в тексте ответа.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": 500100,
    "ExpirationDate": "2015-12-03T10:00:00Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

Удаление расширения

Удаление расширения из указанного экземпляра ресурса. Ресурсом может быть сообщение, событие календаря или контакт в Office 365 или Outlook.com.

Удаление расширения в экземпляре каждого из поддерживаемых ресурсов:

DELETE https://outlook.office.com/api/beta/me/messages('{message_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/beta/me/events('{event_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/beta/me/contacts('{contact_id}')/extensions('{extension_name}')

Минимальная требуемая область

Одна из следующих областей для чтения и записи, соответствующих целевому ресурсу:

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Параметр	Тип	Описание
Параметры URL-адреса
extension_name	string	Уникальный текстовый идентификатор расширения. Обязательный.

Пример запроса

Следующий пример ссылается на расширение по его имени и удаляет расширение в указанном сообщении.

DELETE https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

Пример отклика

При успешном выполнении ответ содержит код отклика HTTP 204 No Content.

Сущности расширения

Расширение

Тип: Microsoft.OutlookServices.Entity

Абстрактная сущность с базовым типом Entity.

OpenTypeExtension

Тип: Microsoft.OutlookServices.Extension

Абстрактный, открытый тип OData v4, который поддерживает динамическое определение свойств и данных в полезных данных JSON для обновления экземпляра типа сущности.

Свойство	Тип	Описание	Запись	Фильтрация?
ExtensionName	string	Уникальное имя расширения. Используйте систему обратного доменного имени принадлежащего вам домена, например, Com.Contoso.Contact.	Да	Нет

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

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

• Начало работы с API REST Почта, Календарь и Контакты.
• Хотите увидеть примеры? Вот они.

Или узнайте больше об использовании платформы Office 365 здесь:

• API REST Outlook для центра разработок Outlook
• Обзор разработки на платформе Office 365
• Проверка подлинности приложений и авторизация ресурсов в Office 365
• Вручную зарегистрируйте приложение с помощью Azure AD, чтобы оно могло получить доступ к API Office 365
• Справка для REST API Почты
• Справка по REST API для Календаря
• Справка для API REST Контактов
• REST API для Задач (предварительная версия)
• Справка для ресурсов: API REST Почты, Календаря, Контактов и Задач