Создание openTypeExtension

  • Статья

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Предостережение

Существующие приложения, использующие эту функцию с baseTask или baseTaskList , должны быть обновлены, так как набор API задач, основанный на этих ресурсах, устарел с 31 мая 2022 г. Этот набор API прекратит возвращать данные 31 августа 2022 г. Используйте набор API, основанный на todoTask.

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

В таблице раздела Разрешения перечислены ресурсы, поддерживающие открытые расширения.

Примечание. Если вы создаете открытые расширения для ресурсов Outlook, см. раздел Рекомендации, касающиеся Outlook в статье Тип ресурса openTypeExtension.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet
✅ ✅ ✅ ✅

Разрешения

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

Поддерживаемый ресурс Делегированное (рабочая или учебная учетная запись) Делегированное (личная учетная запись Майкрософт) Для приложений
device Directory.AccessAsUser.All Не поддерживается Device.ReadWrite.All
event Calendars.ReadWrite Calendars.ReadWrite Calendars.ReadWrite
group Group.ReadWrite.All Не поддерживается Group.ReadWrite.All
event для групп Group.ReadWrite.All Не поддерживается Не поддерживается
post для групп Group.ReadWrite.All Не поддерживается Group.ReadWrite.All
message Mail.ReadWrite Mail.ReadWrite Mail.ReadWrite
organization Organization.ReadWrite.All Не поддерживается Organization.ReadWrite.All
contact (личный контакт) Contacts.ReadWrite Contacts.ReadWrite Contacts.ReadWrite
todoTask Tasks.ReadWrite Tasks.ReadWrite Не поддерживается
todoTaskList Tasks.ReadWrite Tasks.ReadWrite Не поддерживается
user User.ReadWrite User.ReadWrite User.ReadWrite.All
baseTask (не рекомендуется) Tasks.ReadWrite Tasks.ReadWrite Не поддерживается
baseTaskList (не рекомендуется) Tasks.ReadWrite Tasks.ReadWrite Не поддерживается

HTTP-запрос

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

Используйте такой же запрос REST, как для создания экземпляра.

POST /users/{userId|userPrincipalName}/events
POST /users/{userId|userPrincipalName}/messages
POST /groups/{userId}/events
POST /groups/{userId}/threads/{threadId}/posts/{postId}/reply
POST /users/{userId|userPrincipalName}/contacts
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks
POST /users/{userId|userPrincipalName}/todo/lists
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks
POST /users/{userId|userPrincipalName}/tasks/lists

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

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

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

Идентифицируйте экземпляр ресурса в запросе и выполните операцию POST для свойства навигации extensions.

POST /administrativeunits/{administrativeUnitId}/extensions
POST /devices/{deviceId}/extensions
POST /users/{userId|userPrincipalName}/events/{eventId}/extensions
POST /groups/{groupId}/extensions
POST /groups/{groupId}/events/{eventId}/extensions
POST /groups/{groupId}/threads/{threadId}/posts/{postId}/extensions
POST /users/{userId|userPrincipalName}/messages/{messageId}/extensions
POST /organization/{organizationId}/extensions
POST /users/{userId|userPrincipalName}/contacts/{contactId}/extensions
POST /users/{userId|userPrincipalName}/extensions
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks/{taskId}/extensions
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/extensions
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks/{taskId}/extensions
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/extensions

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

В разделе Текст запроса показано, как включить расширение в текст запроса.

Заголовки запросов

Имя Значение
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type application/json

Текст запроса

Предоставьте текст JSON объекта openTypeExtension со следующими обязательными парами "имя-значение" и любыми дополнительными пользовательскими данными. Полезные данные JSON могут относиться к простому типу или представлять собой массив элементов простого типа.

Имя Значение
@odata.type microsoft.graph.openTypeExtension
extensionName Уникальная строка

При создании расширения в новом экземпляре ресурса предоставьте не только объект openTypeExtension, но и представление JSON соответствующих свойств для создания этого экземпляра ресурса.

Ответ

Код ответа

В зависимости от операции можно использовать код ответа 201 Created или 202 Accepted.

При создании расширения с использованием такой же операции, как для создания экземпляра ресурса, операция возвращает такой же код ответа, что и при создании экземпляра ресурса без расширения. Изучите соответствующие статьи о создании экземпляров, перечисленные выше.

Текст отклика

Сценарий Ресурс Текст отклика
Создание расширения с явным созданием нового экземпляра ресурса contact, event, message Включает новый экземпляр, дополненный объектом openTypeExtension.
Создание расширения с неявным созданием экземпляра ресурса post Ответ содержит только код ответа без текста.
Создание расширения в существующем экземпляре ресурса Все поддерживаемые ресурсы Включает объект openTypeExtension.

Пример

Запрос 1

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

  • Свойства subject, body и toRecipients, характерные для нового сообщения.

  • Данные для расширения:

    • Тип microsoft.graph.openTypeExtension.
    • Имя расширения "Com.Contoso.Referral".
    • Дополнительные данные, хранящиеся в виде трех настраиваемых свойств в полезных данных JSON: companyName, expirationDate и dealValue.
POST https://graph.microsoft.com/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.graph.openTypeExtension",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

Отклик 1

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

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

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Me/messages/$entity",
  "@odata.id": "https://graph.microsoft.com/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",
  "inferenceClassification": "Focused",
  "extensions": [
    {
      "@odata.type": "#microsoft.graph.openTypeExtension",
      "@odata.id": "https://graph.microsoft.com/beta/users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
      "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

Запрос 2

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

  • Тип microsoft.graph.openTypeExtension.
  • Имя расширения "Com.Contoso.Referral".
  • Дополнительные данные, хранящиеся в виде 3 настраиваемых свойств в полезных данных JSON: companyName, dealValue и expirationDate.
POST https://graph.microsoft.com/beta/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions
Content-Type: application/json

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Referral",
  "companyName" : "Wingtip Toys",
  "dealValue" : 500050,
  "expirationDate" : "2015-12-03T10:00:00.000Z"
}

Отклик 2

Ниже представлен отклик для второго примера. Текст отклика включает следующие данные для нового расширения:

  • Свойство по умолчанию extensionName.
  • Свойство id с полным именем microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • Сохраняемые пользовательские данные.
HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/beta/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
    "extensionName": "Com.Contoso.Referral",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
    "companyName": "Wingtip Toys",
    "dealValue": 500050,
    "expirationDate": "2015-12-03T10:00:00.000Z"
}

Запрос 3

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

  • Тип microsoft.graph.openTypeExtension.
  • Имя расширения "Com.Contoso.Deal".
  • Дополнительные данные, хранящиеся в виде 3 настраиваемых свойств в полезных данных JSON: companyName, dealValue и expirationDate.
POST https://graph.microsoft.com/beta/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions
Content-type: application/json

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Deal",
  "companyName" : "Alpine Skis",
  "dealValue" : 1010100,
  "expirationDate" : "2015-07-03T13:04:00.000Z"
}

Отклик 3

Ниже представлен отклик из третьего примера.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('f5480dfd-7d77-4d0b-ba2e-3391953cc74a')/events('AAMkADVl7IsAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Deal",
    "extensionName": "Com.Contoso.Deal",
    "companyName": "Alpine Skis",
    "dealValue": 1010100,
    "expirationDate": "2015-07-03T13:04:00Z"
}

Запрос 4

В четвертом примере показано создание расширения в новой записи группы с помощью одного вызова действия reply для существующей записи группы. Действие reply создает запись и внедряет в нее новое расширение. Текст запроса включает свойство post, которое, в свою очередь, содержит свойство body новой записи и следующие данные для нового расширения:

  • Тип microsoft.graph.openTypeExtension.
  • Имя расширения "Com.Contoso.HR".
  • Дополнительные данные, хранящиеся в виде 3 настраиваемых свойств в полезных данных JSON: companyName, expirationDate и массив строк topPicks.
POST https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAAC1heiSAAA=/reply
Content-type: application/json

{
  "post": {
    "body": {
      "contentType": "html",
      "content": "<html><body><div><div><div><div>When and where? </div></div></div></div></body></html>"
    },
  "extensions": [
    {
      "@odata.type": "microsoft.graph.openTypeExtension",
      "extensionName": "Com.Contoso.HR",
      "companyName": "Contoso",
      "expirationDate": "2015-07-03T13:04:00.000Z",
      "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
      ]
    }
  ]
  }
}

Отклик 4

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

HTTP/1.1 202 Accepted
Content-type: text/plain
Content-Length: 0

Запрос 5

В пятом примере показано создание расширения в новой записи группы с помощью той же операции POST, которая создает беседу. Операция POST создает беседу, цепочку и запись, а также внедряет в эту запись новое расширение. Текст отклика включает свойства Topic и Threads, а также дочерний объект post для новой беседы. Объект post, в свою очередь, содержит свойство body новой записи и следующие данные расширения:

  • Тип microsoft.graph.openTypeExtension.
  • Имя расширения "Com.Contoso.HR".
  • Дополнительные данные, хранящиеся в виде 3 настраиваемых свойств в полезных данных JSON: companyName, expirationDate и массив строк topPicks.
POST https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/conversations
Content-type: application/json

{
  "Topic": "Does anyone have a second?",
  "Threads": [
    {
      "Posts": [
        {
          "Body": {
            "ContentType": "HTML",
            "Content": "This is urgent!"
          },
          "Extensions": [
            {
              "@odata.type": "microsoft.graph.openTypeExtension",
              "extensionName": "Com.Contoso.Benefits",
              "companyName": "Contoso",
              "expirationDate": "2016-08-03T11:00:00.000Z",
              "topPicks": [
                "Employees only",
                "Add spouse or guest",
                "Add family"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Отклик 5

Ниже представлен отклик из пятого примера, содержащий новую беседу и идентификатор цепочки. Эта новая цепочка содержит автоматически созданную запись, включающую новое расширение.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

Чтобы получить новое расширение, сначала получите все записи в этом потоке, и изначально должно быть только одно. Затем примените идентификатор записи и имя Com.Contoso.Benefits расширения, чтобы получить расширение.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations/$entity",
    "id": "AAQkADJToRlbJ5Mg7TFM7H-j3Y=",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}