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

重要

Microsoft Graph の/betaバージョンの api は変更される可能性があります。APIs under the /beta version in Microsoft Graph are subject to change. 実稼働アプリケーションでは、これらの API の使用はサポートされていません。Use of these APIs in production applications is not supported.

オープン拡張機能 (Opentypeextensionオブジェクト) を作成し、サポートされているリソースの新規または既存のインスタンスにカスタムプロパティを追加します。Create an open extension (openTypeExtension object) and add custom properties in a new or existing instance of a supported resource.

注: Outlook リソースでオープン拡張機能を作成する場合は、openTypeExtension リソースの種類にあるOutlook-固有の考慮事項 を参照してください。Note: If you're creating open extensions on Outlook resources, see Outlook-specific considerations in openTypeExtension resource type.

アクセス許可Permissions

拡張機能を含むリソースおよび要求されたアクセス許可の種類(代理またはアプリケーション)に応じて、以下の表で指定されているアクセス許可が、このAPIを呼び出すために最低限必要な特権になります。Depending on the resource you're creating the extension in and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。To learn more, including how to choose permissions, see Permissions.

サポートされているリソースSupported resource 委任 (職場または学校のアカウント)Delegated (work or school account) 委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) アプリケーションApplication
devicedevice Directory.AccessAsUser.AllDirectory.AccessAsUser.All サポート対象外Not supported Device.ReadWrite.AllDevice.ReadWrite.All
イベントevent Calendars.ReadWriteCalendars.ReadWrite Calendars.ReadWriteCalendars.ReadWrite Calendars.ReadWriteCalendars.ReadWrite
グループgroup Group.ReadWrite.AllGroup.ReadWrite.All サポート対象外Not supported Group.ReadWrite.AllGroup.ReadWrite.All
グループ イベントgroup event Group.ReadWrite.AllGroup.ReadWrite.All サポート対象外Not supported 非サポートNot supported
グループの投稿group post Group.ReadWrite.AllGroup.ReadWrite.All サポート対象外Not supported Group.ReadWrite.AllGroup.ReadWrite.All
メッセージmessage Mail.ReadWriteMail.ReadWrite Mail.ReadWriteMail.ReadWrite Mail.ReadWriteMail.ReadWrite
組織organization Directory.AccessAsUser.AllDirectory.AccessAsUser.All サポート対象外Not supported 非サポートNot supported
個人用連絡先personal contact Contacts.ReadWriteContacts.ReadWrite Contacts.ReadWriteContacts.ReadWrite Contacts.ReadWriteContacts.ReadWrite
useruser User.ReadWrite.AllUser.ReadWrite.All User.ReadWriteUser.ReadWrite User.ReadWrite.AllUser.ReadWrite.All

HTTP 要求HTTP request

新規のリソース インスタンスに拡張機能を作成するCreate an extension in a new resource instance

インスタンスを作成するには、同じ REST 要求を使います。Use the same REST request that you use to create the instance.

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

注: この構文は、サポートされているリソース インスタンスを作成する一般的な方法を示しています。Note: This syntax shows some common ways to create the supported resource instances. こうしたリソース インスタンスを作成するために使用できる他の POST 構文すべても、同様の方法でオープン拡張機能を作成できます。All other POST syntaxes that allows you to create these resource instances supports creating open extensions in them in a similar way.

要求本文に、新規のリソース インスタンスのプロパティおよび_拡張機能_を含める方法については、要求本文のセクションをご覧ください。See the Request body section about including the properties of the new resource instance and the extension in the request body.

既存のリソース インスタンスに拡張機能を作成するCreate an extension in an existing resource instance

その要求でリソース インスタンスを識別し、機能拡張 ナビゲーション プロパティで POST を行います。Identify the resource instance in the request and do a POST to the extensions navigation property.

POST /administrativeunits/{id}/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

注: 上記の構文は、拡張機能をその中に作成するリソース インスタンスを特定する一般的な方法を示しています。Note: This syntax shows some common ways to identify a resource instance, in order to create an extension in it. こうしたリソース インスタンスを特定するために使用できる他の構文すべても、同様の方法でオープン拡張機能を作成できます。All other syntaxes that allows you to identify these resource instances supports creating open extensions in them in a similar way.

要求本文にある_拡張機能_を含めた要求本文のセクションを参照してください。See the Request body section about including the extension in the request body.

パス パラメーターPath parameters

パラメーターParameter Type 説明Description
idid stringstring 該当するコレクション内のオブジェクトの一意識別子。必須。A unique identifier for an object in the corresponding collection. Required.

要求ヘッダーRequest headers

名前Name Value
AuthorizationAuthorization ベアラー {トークン}。必須。Bearer {token}. Required.
Content-TypeContent-Type application/jsonapplication/json

要求本文Request body

次の必須の名前と値のペアと追加のカスタムデータを使用して、 Opentypeextensionの JSON 本文を指定します。JSON ペイロードのデータは、プリミティブ型、またはプリミティブ型の配列にすることができます。Provide a JSON body of an openTypeExtension, with the following required name-value pairs and any additional custom data. The data in the JSON payload can be primitive types, or arrays of primitive types.

名前Name Value
@odata.type@odata.type microsoft.graph.openTypeExtensionmicrosoft.graph.openTypeExtension
extensionNameextensionName %unique_string%%unique_string%

_新しい_リソース インスタンスに拡張機能を作成するときは、新しい openTypeExtension オブジェクトに加えて、関連するプロパティの JSON 表現を指定して、このようなリソース インスタンスを作成します。When creating an extension in a new resource instance, in addition to the new openTypeExtension object, provide a JSON representation of the relevant properties to create such a resource instance.

応答Response

応答コードResponse code

操作によって、応答コードは 201 Created または 202 Accepted になります。Depending on the operation, the response code can be 201 Created or 202 Accepted.

リソース インスタンスを作成するために使用するのと同じ操作を使用して、拡張子を作成すると、操作は拡張子なしのリソースのインスタンスの作成時に返される同じ応答コードを返します。When you create an extension using the same operation that you use to create a resource instance, the operation returns the same response code that it returns when you use the operation to create the resource instance without the extension. それぞれ対応するインスタンスの作成については上記の一覧を参照してください。Refer to the corresponding topics for creating the instance, as listed above.

応答本文Response body

シナリオScenario リソースResource 応答本文Response body
_新しい_リソース インスタンスを明示的に作成しながら、拡張機能を作成するCreating an extension while explicitly creating a new resource instance 連絡先イベントメッセージcontact, event, message openTypeExtension オブジェクトで展開した新しいインスタンスを含みます。Includes the new instance expanded with the openTypeExtension object.
新しいリソース インスタンスを暗示的に作成しながら、拡張機能を作成するCreating an extension while implicitly creating a resource instance postpost 応答には、応答コードだけが含まれ、応答本体は含まれません。The response includes only a response code but not a response body.
_既存_のリソース インスタンスに拡張機能を作成するCreating an extension in an existing resource instance サポートされているすべてのリソースAll supported resources openTypeExtension オブジェクトが含まれます。Includes the openTypeExtension object.

Example

要求 1Request 1

最初の例では、同一の呼び出しでメッセージと拡張情報を作成します。要求本文には、次のものが含まれます。The first example creates a message and an extension in the same call. The request body includes the following:

  • 新しいメッセージ固有の subjectbodytoRecipients プロパティ。The subject, body, and toRecipients properties typical of a new message.

  • 拡張情報に関する次のもの。And for the extension:

    • microsoft.graph.openTypeExtensionThe type microsoft.graph.openTypeExtension.
    • 拡張情報名 "Com.Contoso.Referral"。The extension name "Com.Contoso.Referral".
    • JSON ペイロードに 3 つのカスタム プロパティとして格納される追加のデータ: companyNameexpirationDatedealValueAdditional data to be stored as three custom properties in the JSON payload: companyName, expirationDate, and 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
    }
  ]
}

応答 1Response 1

最初の例の応答を次に示します。応答本文には、新しいメッセージのプロパティと、新しい拡張情報に関する次のものが含まれています。Here is the response for the first example. The response body includes properties of the new message, and the following for the new extension:

  • id プロパティと microsoft.graph.openTypeExtension.Com.Contoso.Referral の完全修飾名。The id property with the fully qualified name of microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • 要求で指定されている既定のプロパティ extensionNameThe default property extensionName specified in the request.
  • 要求で指定されている、3 つのカスタム プロパティとして格納されるカスタム データ。The custom data specified in the request stored as 3 custom properties.

注: 簡潔にするために、ここに示す応答オブジェクトは切り詰められている場合があります。すべてのプロパティは実際の呼び出しから返されます。Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

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.context": "https://graph.microsoft.com/beta/$metadata#Me/messages
('AAMkAGEbs88AAB84uLuAAA%3D')/extensions",
  "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
    }
  ]
}

要求 2Request 2

2 番目の例では、指定されたメッセージに拡張情報を作成します。要求本文には、拡張情報に関する次のものが含まれます。The second example creates an extension in the specified message. The request body includes the following for the extension:

  • microsoft.graph.openTypeExtensionThe type microsoft.graph.openTypeExtension.
  • 拡張情報名 "Com.Contoso.Referral"。The extension name "Com.Contoso.Referral".
  • JSON ペイロードに 3 つのカスタム プロパティとして格納される追加のデータ: companyNamedealValueexpirationDateAdditional data to be stored as 3 custom properties in the JSON payload: companyName, dealValue, and 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"
}

応答 2Response 2

2 番目の例の応答を次に示します。応答本文には、新しい拡張情報に関する次のものが含まれています。Here is the response for the second example. The response body includes the following for the new extension:

  • 既定のプロパティ extensionNameThe default property extensionName.
  • id プロパティと microsoft.graph.openTypeExtension.Com.Contoso.Referral の完全修飾名。The id property with the fully qualified name of microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • 格納されるカスタム データ。The custom data to be stored.
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"
}

要求 3Request 3

3 番目の例では、指定されたグループ イベントに拡張情報を作成します。要求本文には、拡張情報に関する次のものが含まれます。The third example creates an extension in the specified group event. The request body includes the following for the extension:

  • microsoft.graph.openTypeExtensionThe type microsoft.graph.openTypeExtension.
  • 拡張情報名 "Com.Contoso.Deal"。The extension name "Com.Contoso.Deal".
  • JSON ペイロードに 3 つのカスタム プロパティとして格納される追加のデータ: companyNamedealValueexpirationDateAdditional data to be stored as 3 custom properties in the JSON payload: companyName, dealValue, and 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"
}

応答 3Response 3

3 番目の例の要求からの応答を次に示します。Here is the response from the third example request.

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

要求 4Request 4

4 番目の例では、既存のグループ投稿に対する reply アクション呼び出しと同じ呼び出しを使用して、新しいグループ投稿に拡張情報を作成します。reply アクションは、新しい投稿と、投稿に埋め込まれる新しい拡張情報を作成します。要求本文には post プロパティが含まれます。そのプロパティには新しい投稿の body が含まれ、さらに新しい拡張情報の次のデータが含まれます。The fourth example creates an extension in a new group post, using the same reply action call to an existing group post. The reply action creates a new post, and a new extension embedded in the post. The request body includes a post property, which in turn contains the body of the new post, and the following data for the new extension:

  • microsoft.graph.openTypeExtensionThe type microsoft.graph.openTypeExtension.
  • 拡張情報名 "Com.Contoso.HR"。The extension name "Com.Contoso.HR".
  • JSON ペイロードに 3 つのカスタム プロパティとして格納される追加のデータ: companyNameexpirationDate、文字列 topPicks の配列。Additional data to be stored as 3 custom properties in the JSON payload: companyName, expirationDate, and the array of strings 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"
      ]
    }
  ]
  }
}

応答 4Response 4

4 番目の例の応答を次に示します。新しいグループ投稿に正常に拡張情報を作成できた場合は、HTTP 202 応答コードのみが生成されます。Here is the response from the fourth example. Successfully creating an extension in a new group post results in only the HTTP 202 response code.

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

要求 5Request 5

5 番目の例では、会話を作成するための同じ POST 操作を使用して、新しいグループ投稿に拡張情報を作成します。POST 操作は、新しい会話、スレッドと投稿、投稿に埋め込まれた新しい拡張情報を作成します。要求本文には、Topic プロパティと Threads プロパティや、新しい会話の子 post オブジェクトが含まれます。次いで、その post オブジェクトには、新しい投稿の body と、拡張情報の次のデータが含まれます。The fifth example creates an extension in a new group post using the same POST operation to create a conversation. The POST operation creates a new conversation, thread and post, and a new extension embedded in the post. The request body includes the Topic and Threads properties, and a child post object for the new conversation. The post object in turn contains the body of the new post, and the following data for the extension:

  • microsoft.graph.openTypeExtensionThe type microsoft.graph.openTypeExtension.
  • 拡張情報名 "Com.Contoso.HR"。The extension name "Com.Contoso.HR".
  • JSON ペイロードに 3 つのカスタム プロパティとして格納される追加のデータ: companyNameexpirationDate、文字列 topPicks の配列。Additional data to be stored as 3 custom properties in the JSON payload: companyName, expirationDate, and the array of strings 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"
              ]
            }
          ]
        }
      ]
    }
  ]
}

応答 5Response 5

5 番目の例の応答を次に示します。この応答には、新しい会話とスレッド ID が含まれています。この新しいスレッドには、自動的に作成された投稿が含まれ、その投稿に新しい拡張情報が含まれます。Here is the response from the fifth example which contains the new conversation and a thread ID. This new thread contains an automatically created post, which in turn contains the new extension.

注:簡潔にするために、ここに示す応答オブジェクトは切り詰められている場合があります。実際の呼び出しではすべてのプロパティが返されます。Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

新しい拡張情報を取得するには、まずこのスレッド内のすべての投稿を取得します。投稿は最初は 1 つしかありません。その後、投稿 ID と拡張情報名 Com.Contoso.Benefits を適用して、拡張情報を取得します。To get the new extension, first get all the posts in this thread, and initially there should be only one. Then apply the post ID and the extension name Com.Contoso.Benefits to get the extension.

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@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations('AAQkADJToRlbJ5Mg7TFM7H-j3Y%3D')/threads",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}