フィードバック 編集

オープン拡張機能を作成する

  • [アーティクル]

名前空間: microsoft.graph

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

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

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

アクセス許可

拡張機能を含むリソースおよび要求されたアクセス許可の種類（代理またはアプリケーション）に応じて、以下の表で指定されているアクセス許可が、この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 Tasks.ReadWrite.All
todoTaskList Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
ユーザー 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 を行います。

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 該当するコレクション内のオブジェクトの一意識別子。必須。

要求ヘッダー

名前 値
Authorization ベアラー {token}。必須。
Content-Type application/json

要求本文

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

名前 値
@odata.type microsoft.graph.openTypeExtension
extensionName %unique_string%

新しい リソース インスタンスに拡張機能を作成するときは、新しい 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/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
    }
  ]
}

応答 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/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

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

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

応答 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/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

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

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

応答 3

3 番目の例の要求からの応答を次に示します。

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

4 番目の例では、既存のグループ投稿に対する reply アクション呼び出しと同じ呼び出しを使用して、新しいグループ投稿に拡張情報を作成します。reply アクションは、新しい投稿と、投稿に埋め込まれる新しい拡張情報を作成します。要求本文には post プロパティが含まれます。そのプロパティには新しい投稿の body が含まれ、さらに新しい拡張情報の次のデータが含まれます。

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

応答 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/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

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

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

新しい拡張情報を取得するには、まずこのスレッド内のすべての投稿を取得します。投稿は最初は 1 つしかありません。その後、投稿 ID と拡張情報名 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=="
        }
    ]
}