openTypeExtension を作成する

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

注意

この機能を baseTask または baseTaskList と共に使用する既存のアプリは、これらのリソースに基づいて構築された To Do API セットが 2022 年 5 月 31 日に非推奨になったので、更新する必要があります。 その API セットは、2022 年 8 月 31 日にデータを戻すことを停止します。 todoTask 上に構築された API セットを使用してください。

オープン拡張機能 (openTypeExtension オブジェクト) を作成し、リソースの新規または既存のインスタンスのカスタム プロパティを追加します。 開いている拡張機能 を作成リソース インスタンスにし、特定のリソースを除くすべてのカスタム データを同じ操作で格納できます。

[アクセス許可] セクションの表に、開いている拡張機能をサポートするリソースを示します。

注: Outlook リソースでオープン拡張機能を作成する場合は、openTypeExtension リソースの種類にあるOutlook-固有の考慮事項 を参照してください。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

拡張機能を含むリソースおよび要求されたアクセス許可の種類（代理またはアプリケーション）に応じて、以下の表で指定されているアクセス許可が、このAPIを呼び出すために最低限必要な特権になります。 より多くの特権アクセス許可を選択する前に注意することを含め、詳細については、[アクセス許可] で次のアクセス許可を検索してください。

サポートされているリソース 委任 (職場または学校のアカウント) 委任 (個人用 Microsoft アカウント) アプリケーション
device Directory.AccessAsUser.All サポート対象外 Device.ReadWrite.All
イベント Calendars.ReadWrite Calendars.ReadWrite Calendars.ReadWrite
グループ Group.ReadWrite.All サポート対象外 Group.ReadWrite.All
グループ イベント Group.ReadWrite.All サポート対象外 非サポート
グループの投稿 Group.ReadWrite.All サポート対象外 Group.ReadWrite.All
メッセージ Mail.ReadWrite Mail.ReadWrite Mail.ReadWrite
organization Organization.ReadWrite.All 非サポート Organization.ReadWrite.All
個人用連絡先 Contacts.ReadWrite Contacts.ReadWrite Contacts.ReadWrite
todoTask Tasks.ReadWrite Tasks.ReadWrite 非サポート
todoTaskList Tasks.ReadWrite Tasks.ReadWrite 非サポート
ユーザー 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 を行います。

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

注: 上記の構文は、拡張機能をその中に作成するリソース インスタンスを特定する一般的な方法を示しています。 こうしたリソース インスタンスを特定するために使用できる他の構文すべても、同様の方法でオープン拡張機能を作成できます。

要求本文にある拡張機能を含めた要求本文のセクションを参照してください。

要求ヘッダー

名前 値
Authorization ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。
Content-Type application/json

要求本文

openTypeExtension の JSON 本文に、次の必須の名前と値のペアと追加のカスタム データを指定します。 JSON ペイロード内のデータは、プリミティブ型か、プリミティブ型の配列にすることができます。

名前 値
@odata.type microsoft.graph.openTypeExtension
extensionName 一意の文字列

新しいリソース インスタンスに拡張機能を作成するときは、新しい openTypeExtension オブジェクトに加えて、関連するプロパティの JSON 表現を指定して、このようなリソース インスタンスを作成します。

応答

応答コード

操作によって、応答コードは 201 Created または 202 Accepted になります。

リソース インスタンスを作成するために使用するのと同じ操作を使用して、拡張子を作成すると、操作は拡張子なしのリソースのインスタンスの作成時に返される同じ応答コードを返します。 それぞれ対応するインスタンスの作成については上記の一覧を参照してください。

応答本文

シナリオ リソース 応答本文
新しいリソース インスタンスを明示的に作成しながら、拡張機能を作成する 連絡先、イベント、メッセージ openTypeExtension オブジェクトで展開した新しいインスタンスを含みます。
新しいリソース インスタンスを暗示的に作成しながら、拡張機能を作成する post 応答には、応答コードだけが含まれ、応答本体は含まれません。
既存のリソース インスタンスに拡張機能を作成する サポートされているすべてのリソース openTypeExtension オブジェクトが含まれます。

例

要求 1

最初の例では、同一の呼び出しでメッセージと拡張情報を作成します。 要求本文には、次のものが含まれます。

  • 新しいメッセージ固有の subject、body、toRecipients プロパティ。

  • 拡張情報に関する次のもの。

    • 型 microsoft.graph.openTypeExtension。
    • 拡張情報名 "Com.Contoso.Referral"。
    • JSON ペイロードに 3 つのカスタム プロパティとして格納される追加のデータ: 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

2 番目の例では、指定されたメッセージに拡張情報を作成します。 要求本文には、拡張情報に関する次のものが含まれます。

  • 型 microsoft.graph.openTypeExtension。
  • 拡張情報名 "Com.Contoso.Referral"。
  • JSON ペイロードに 3 つのカスタム プロパティとして格納される追加のデータ: 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

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

3 番目の例では、指定されたグループ イベントに拡張情報を作成します。 要求本文には、拡張情報に関する次のものが含まれます。

  • 型 microsoft.graph.openTypeExtension。
  • 拡張情報名 "Com.Contoso.Deal"。
  • JSON ペイロードに 3 つのカスタム プロパティとして格納される追加のデータ: 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

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

4 番目の例では、既存のグループ 投稿に対する同じ 応答 アクション呼び出しを使用して、新しいグループ投稿に拡張機能を作成します。 要求本文には post プロパティが含まれます。 要求本文には post プロパティが含まれます。これには、新しい投稿の 本文 と、新しい拡張機能の次のデータが含まれます。

  • 型 microsoft.graph.openTypeExtension。
  • 拡張情報名 "Com.Contoso.HR"。
  • JSON ペイロードに 3 つのカスタム プロパティとして格納される追加のデータ: 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

4 番目の例の応答を次に示します。 新しいグループ投稿に正常に拡張情報を作成できた場合は、HTTP 202 応答コードのみが生成されます。

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

要求 5

5 番目の例では、会話を作成するための同じ POST 操作を使用して、新しいグループ投稿に拡張情報を作成します。 POST 操作は、新しい会話、スレッドと投稿、投稿に埋め込まれた新しい拡張情報を作成します。 要求本文には、Topic プロパティと Threads プロパティや、新しい会話の子 post オブジェクトが含まれます。 次いで、その post オブジェクトには、新しい投稿の body と、拡張情報の次のデータが含まれます。

  • 型 microsoft.graph.openTypeExtension。
  • 拡張情報名 "Com.Contoso.HR"。
  • JSON ペイロードに 3 つのカスタム プロパティとして格納される追加のデータ: 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

新しい会話とスレッド ID を含む 5 番目の例からの応答を次に示します。 この新しいスレッドには、自動的に作成された投稿が含まれています。これには、新しい拡張機能が含まれます。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

新しい拡張機能を取得するには、まずこのスレッド のすべての投稿を取得 し、最初は 1 つだけにする必要があります。 次に、post ID と拡張機能名 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=="
        }
    ]
}