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


Создание открытого расширения

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

Создание открытого расширения (объекта 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 Tasks.ReadWrite.All
todoTaskList Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
user User.ReadWrite User.ReadWrite User.ReadWrite.All

HTTP-запрос

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

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

POST /users/{id|userPrincipalName}/events
POST /users/{id|userPrincipalName}/messages
POST /groups/{id}/events
POST /groups/{id}/threads/{id}/posts/{id}/reply
POST /users/{id|userPrincipalName}/contacts
POST /users/{id|userPrincipalName}/todo/lists/{id}/tasks
POST /users/{id|userPrincipalName}/todo/lists

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

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

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

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

POST /devices/{id}/extensions
POST /users/{id|userPrincipalName}/events/{id}/extensions
POST /groups/{id}/extensions
POST /groups/{id}/events/{id}/extensions
POST /groups/{id}/threads/{id}/posts/{id}/extensions
POST /users/{id|userPrincipalName}/messages/{id}/extensions
POST /organization/{id}/extensions
POST /users/{id|userPrincipalName}/contacts/{id}/extensions
POST /users/{id|userPrincipalName}/extensions
POST /users/{id|userPrincipalName}/todo/lists/{id}/tasks/{id}/extensions
POST /users/{id|userPrincipalName}/todo/lists/{id}/extensions

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

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

Параметры пути

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

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

Имя Значение
Авторизация 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/v1.0/me/messages

{
  "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
    }
  ]
}

Отклик

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

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

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

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages/$entity",
  "@odata.id": "https://graph.microsoft.com/v1.0/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/v1.0/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".
  • Дополнительные данные, хранящиеся в виде трех настраиваемых свойств в полезных данных JSON: companyName, dealValue и expirationDate.
POST https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions

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

Отклик

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/v1.0/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".
  • Дополнительные данные, хранящиеся в виде трех настраиваемых свойств в полезных данных JSON: companyName, dealValue и expirationDate.
POST https://graph.microsoft.com/v1.0/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions

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

Отклик

Ниже показан пример отклика.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$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 создает запись и внедряет в нее новое расширение. Текст запроса включает свойство post, которое, в свою очередь, содержит свойство body новой записи и следующие данные для нового расширения:

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

{
  "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"
      ]
    }
  ]
  }
}

Отклик

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

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

Пример 5. Создание расширения в новой группе после выполнения операции POST

Запрос 5

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

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

{
  "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/v1.0/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations/$entity",
    "id": "AAQkADJToRlbJ5Mg7TFM7H-j3Y=",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}