次の方法で共有


Office 365 のデータ拡張機能の REST API リファレンス (バージョン 2.0)

適用対象: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Office 365 データ拡張機能 REST API を使用すると、アプリによりユーザー アカウントのメッセージ、イベント、または連絡先でカスタム データを動的に保存できるようになります。 ここでのアカウントには、Office 365 アカウントまたは Microsoft アカウント (Hotmail.com、Live.com、MSN.com、Outlook.com、Passport.com) を使用することができます。

注意

リファレンスをわかりやすくするため、この記事の残りの部分では Outlook.com を、これら Microsoft のアカウント ドメインを含無ものとして使用しています。

API v2.0 が不要な場合 左の目次で、** Office 365 REST API reference ** セクションに移動し、使用したいバージョンを選択します。

概要

Outlook REST API のデータ拡張情報は、OData v4 オープン型で、実行時に指定できるプロパティが含まれています。 データ拡張機能 API を使用すると、JSON ペイロード内でカスタムのプロパティや値を動的に指定することにより、Entity Data Model (EDM) で既に定義されているエンティティ型 (メッセージ、イベント、連絡先) のインスタンスを_拡張_できます。 したがって、このようなエンティティ型の定義の柔軟性が増し、この目的だけのために新しいエンティティ型を定義する時間を節約できます。

すべての拡張情報に対して定義されるプロパティは、ExtensionName プロパティだけです。 拡張情報名を一意にするのに役立つ方法の 1 つとして、独自のドメイン (Com.Contoso.Contact) に依存しているドメイン ネーム システム (DNS) 逆引きの方法を使用できます。 拡張情報名に Microsoft ドメインを含めることはできません。

拡張情報はオープン型なので、エンティティのインスタンスに固有の追加データを指定できます。 たとえば、次に示すように、個々の取引先担当者に関する拡張情報を作成することにより会社名や初期参照元などのカスタム データを追跡できるようにして、JSON ペイロード内でデータを指定できます。

POST https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions
{
   @odata.type: "Microsoft.OutlookServices.OpenTypeExtension",  
   "ExtensionName": "Com.Contoso.Customer",
   "CompanyName": "Alpine Skis",
   "InitialReferrer":  "Robin McCall"
}

データ拡張機能 API を使用すると、新しいリソースや既存のリソースに対して CRUD 操作を実行できます。詳細については、 supported operations を参照してください。

OData オープン型の詳細については、OData.org 上の OData v4 のドキュメントを参照してください。

データ拡張機能 REST API の使用法

データ拡張情報と拡張プロパティのどちらを使用するか

データ拡張機能は、カスタム データの格納およびカスタムデータへのアクセスを必要とするほとんどのシナリオに対して推奨されるソリューションです。 ただし、拡張プロパティとこの REST API は、Outlook REST API のメタデータを通じてまだ公開されていない Outlook MAPI プロパティのカスタム データにアクセスする必要がある場合にのみ使用します。 {version} を v2.0、beta など、選択したバージョンに置き換えて、メタデータが https://outlook.office.com/api/{version}/ $metadataでどのプロパティを公開するかを確認できます。

認証

他の Outlook REST API と同様に、データ拡張機能 API へのすべての要求に対して、有効なアクセス トークンを含める必要があります。 アクセス トークンを取得するには、アプリを登録して識別し、適切な承認を取得する必要があります。

効率化された登録と承認のオプションに関する詳細情報を参照してください。 データ拡張機能 API で特定の操作を続行する際には、この点に留意してください。

サポートされている REST リソース

Outlook REST エンドポイントで、次のリソースのインスタンスに対する拡張情報を作成できます。

API のバージョン

この API は、プレビューから一般提供 (GA) の状態にレベル上げされています。v2.0 とベータのバージョンでサポートされます。

https://outlook.office.com/api/v2.0/

https://outlook.office.com/api/beta/

URL パラメーター

この記事の例では、REST 要求 URL のパラメーターに次の ID のプレース ホルダーを使用します。拡張機能を作成する対象のリソースのインスタンスの ID を指定する必要があります。

パラメーター 説明
URL パラメーター
連絡先の ID 文字列 連絡先の ID。
イベントの ID 文字列 イベント ID。
メッセージ ID 文字列 メッセージ ID。

Outlook REST API と Office 365 データ拡張機能 REST API のすべてのサブセットに共通の情報の詳細については、「Outlook REST API の使用法」を参照してください。

拡張情報の操作

既存のアイテムの拡張情報を作成する

指定したリソースのインスタンスに関する拡張情報を作成してカスタム プロパティを追加します。Office 365 または Outlook.com のメッセージ、予定表イベント、または連絡先をリソースにすることができます。JSON ペイロード内のデータは、プリミティブ型か、プリミティブ型の配列にすることができます。

サポートされているリソースごとに拡張情報を作成するには、次のようにします。

POST https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions
POST https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions
POST https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions

最低限必要なスコープ

対象リソースに対応する次の読み取り/書き込みスコープのうちのいずれかです。

パラメーター 説明
本文のパラメーター
拡張情報名 文字列 拡張情報の一意のテキスト識別子。必須。

要求のサンプル

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

  • Microsoft.OutlookServices.OpenTypeExtension。Outlook REST API メタデータ内で OData オープン型として定義されています。
  • 拡張情報名 "Com.Contoso.Referral"。
  • JSON ペイロード内にカスタム プロパティとして保存される追加のデータ: プリミティブ型が含まれる CompanyNameDealValueExpirationDate とプリミティブ型の配列が含まれる TopModelsTopSalespersonsです。
POST https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions

Content-Type: application/json

{ 
  "@odata.type" : "Microsoft.OutlookServices.OpenTypeExtension", 
  "ExtensionName" : "Com.Contoso.Referral", 
  "CompanyName" : "Wingtip Toys",
  "DealValue@odata.type": "#Int64", 
  "DealValue" : 500050, 
  "ExpirationDate" : "2015-12-03T10:00:00.000Z",
  "TopModels": [
     3001,
     4002,
     5003
  ],
  "TopSalespersons": [
     "Dana Swope",
     "Fanny Downs",
     "Randi Welch"
  ]
} 

応答のサンプル

成功した応答は、HTTP 201 Created 応答コードで示されます。

応答本文には、新しい拡張情報に関する次のものが含まれています。

  • 既定のプロパティ ExtensionName
  • Id プロパティと Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral の完全修飾名。
  • 保存されるカスタム データ。
{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue@odata.type": "#Int64",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "TopModels@odata.type": "#Collection(Int32)",
    "TopModels": [
      3001,
      4002,
      5003
    ],
    "TopSalespersons@odata.type": "#Collection(String)",
    "TopSalespersons": [
      "Dana Swope",
      "Fanny Downs",
      "Randi Welch"
    ]
}

新しいアイテムの拡張情報を作成する

同一の POST 呼び出しで新しいリソースのインスタンスを作成しながら 1 つ以上の拡張情報を作成し、その拡張情報にカスタム プロパティを追加します。 Office 365 または Outlook.com のメッセージ、予定表イベント、または連絡先をリソースにすることができます。 JSON ペイロード内のデータは、プリミティブ型か、プリミティブ型の配列にすることができます。

サポートされているリソースごとに拡張情報を作成するには、そのリソースを作成する場合と同様に POST 呼び出しを行い、POST 要求の本文に拡張情報を含めます。

POST https://outlook.office.com/api/v2.0/me/messages
POST https://outlook.office.com/api/v2.0/me/events
POST https://outlook.office.com/api/v2.0/me/contacts

最低限必要なスコープ

対象リソースに対応する次の読み取り/書き込みスコープのうちのいずれかです。

パラメーター 説明
本文のパラメーター
拡張情報名 文字列 拡張情報の一意のテキスト識別子。必須。

要求のサンプル

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

  • 新しいメッセージ固有の SubjectBodyToRecipients プロパティ。
  • 拡張情報に関する次のもの。
    • Microsoft.OutlookServices.OpenTypeExtension。Outlook REST API メタデータ内で OData オープン型として定義されています。
    • 拡張情報名 "Com.Contoso.Referral"。
    • JSON ペイロード内にカスタム プロパティとして保存される追加のデータ: プリミティブ型が含まれる CompanyNameExpirationDateDealValue とプリミティブ型の配列が含まれる TopModelsTopSalespersonsです。
POST https://outlook.office.com/api/v2.0/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.OutlookServices.OpenTypeExtension",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

応答のサンプル

成功した応答は、HTTP 201 Created 応答コードで示されます。

応答本文には、新しいメッセージのプロパティと、新しい拡張情報に関する次のものが含まれています。

  • Id プロパティと Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral の完全修飾名。
  • 要求で指定されている既定のプロパティ ExtensionName
  • 要求で指定されている、カスタム プロパティとして保存されるカスタム データ。
{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.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",
  "MentionedMe": null,
  "Mentioned": [ ],
  "InferenceClassification": "Focused",
  "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages
('AAMkAGEbs88AAB84uLuAAA%3D')/Extensions",
  "Extensions": [
    {
      "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
      "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels@odata.type": "#Collection(Int32)",
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons@odata.type": "#Collection(String)",
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

拡張情報を取得する

指定されたリソースのインスタンス内で、名前か ID で拡張情報を取得します。Office 365 または Outlook.com のメッセージ、予定表イベント、または連絡先をリソースにすることができます。

名前と ID のどちらで拡張情報を取得しても、同じ応答本体が返されます。

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extensionId}')

最低限必要なスコープ

対象リソースに対応する次の読み取りスコープのうちのいずれかです。

パラメーター 説明
URL パラメーター
拡張機能 ID 文字列 リソース インスタンスのすべての拡張情報間で一意のテキスト識別子である拡張機能名にするか、拡張情報の種類と一意のテキスト識別子を連結した完全修飾名にすることができます。完全修飾名は、拡張情報の作成時に id プロパティ内に返されます。必須。

要求のサンプル

最初の例では、名前で拡張情報を参照し、指定されたメッセージの拡張情報を取得します。

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

2 番目の例では、ID (完全修飾名) で拡張情報を参照し、指定されたメッセージの拡張情報を取得します。

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

応答のサンプル

成功した応答は、HTTP 200 OK 応答コードで示されます。

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00Z"
}

拡張情報を使用して展開されたアイテムを取得する

のフィルターで指定されている拡張情報を使用して展開されたリソースのインスタンスを取得します。Id Office 365 または Outlook.com のメッセージ、予定表イベント、または連絡先をリソースにすることができます。

以下のように、Id で拡張情報名または完全修飾名に対してフィルター処理してから、拡張情報を使用して展開されたインスタンスを取得できます。 フィルター文字列内の空白文字に URL エンコードを適用していることを確認してください。

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

最低限必要なスコープ

対象リソースに対応する次の読み取りスコープのうちのいずれかです。

パラメーター 説明
URL パラメーター
拡張機能 ID 文字列 リソース インスタンスのすべての拡張情報間で一意のテキスト識別子である拡張機能名にするか、拡張情報の種類と一意のテキスト識別子を連結した完全修飾名にすることができます。完全修飾名は、拡張情報の作成時に id プロパティ内に返されます。必須。

要求のサンプル

次の例では、フィルターから返される拡張情報を含めることにより、指定されたメッセージを取得して展開します。 このフィルターは、Id が完全修飾名と一致する拡張情報を返します。

利便性を考慮して、以下の要求では、予約文字のスペースの URL エンコーディングで示しています。

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')?$expand=Extensions($filter=Id%20eq%20'Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

応答のサンプル

成功した応答は、HTTP 200 OK 応答コードで示されます。

応答本文には、指定されたメッセージのすべてのプロパティと、フィルターから返される拡張情報が含まれます。

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
    "Id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
    "Categories": [
    ],
    "CreateDateTime": "2015-06-19T02:03:31Z",
    "LastModifiedDateTime": "2015-08-13T02:28:00Z",
    "Subject": "Attached is the requested info",
    "BodyPreview": "See the images attached.",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "Importance": "Normal",
    "HasAttachments": true,
    "ParentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
    "From": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "Sender": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "ToRecipients": [
        {
            "EmailAddress": {
                "Address": "wendy@contoso.com",
                "Name": "Wendy Molina"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
    "ReceivedDateTime": "2015-06-19T02:05:04Z",
    "SentDateTime": "2015-06-19T02:04:59Z",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsDraft": false,
    "IsRead": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Users('desmond40contoso.com')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions", 
    "Extensions": [ 
      { 
        "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
        "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
        "ExtensionName": "Com.Contoso.Referral",
        "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
        "CompanyName": "Wingtip Toys",
        "DealValue": 500050,
        "ExpirationDate": "2015-12-03T10:00:00Z"
      }
     ]
}

拡張情報を使用してアイテムを検索したり展開したりする

フィルターと一致する拡張情報が含まれているリソースのインスタンスを検索できます。 さらに、同じクエリで、この拡張情報を使用して展開されたこれらのインスタンスを取得できます。 このセクションのクエリは、このようなインスタンスを検索し、展開して、応答に拡張情報を含めます。

Office 365 または Outlook.com のメッセージ、予定表イベント、または連絡先をリソースにすることができます。

次のように、Id で拡張情報名または完全修飾名に対してフィルター処理してから、拡張情報を使用して展開されたインスタンスを取得できます。 フィルター文字列内の空白文字に URL エンコードを適用していることを確認してください。

GET https://outlook.office.com/api/v2.0/me/messages?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/events?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/contacts?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

最低限必要なスコープ

対象リソースに対応する次の読み取りスコープのうちのいずれかです。

パラメーター 説明
URL パラメーター
拡張機能 ID 文字列 リソース インスタンスのすべての拡張情報間で一意のテキスト識別子である拡張機能名にするか、拡張情報の種類と一意のテキスト識別子を連結した完全修飾名にすることができます。完全修飾名は、拡張情報の作成時に id プロパティ内に返されます。必須。

要求のサンプル

次の例では、サインインしているユーザーのメールボックス内のすべてのメッセージを検索して、フィルターと一致する拡張情報が含まれているメッセージを検出し、拡張情報を組み込んでそれらのメッセージを展開します。 フィルターは、Id が拡張情報名 Com.Contoso.Referral と一致する拡張情報を返します。

利便性を考慮して、以下の要求では、予約文字のスペースの URL エンコーディングで示しています。

GET https://outlook.office.com/api/v2.0/me/messages?$filter=Extensions/any(f:f/Id%20eq%20'Com.Contoso.Referral')&$expand=Extensions($filter=Id%20eq%20'Com.Contoso.Referral')

応答のサンプル

成功した応答は、HTTP 200 OK 応答コードで示されます。

応答本文には、拡張情報が一致するすべてのメッセージとすべてのメッセージ プロパティが含まれています。この例では、応答には 2 つのメッセージが含まれています。

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages",
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.EventMessage",
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')",
            "@odata.etag": "W/\"DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn\"",
            "Id": "AAMkADIyDREAAA=",
            "CreatedDateTime": "2016-01-06T02:20:17Z",
            "LastModifiedDateTime": "2016-01-13T02:13:54Z",
            "ChangeKey": "DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:18Z",
            "SentDateTime": "2016-01-06T02:20:18Z",
            "HasAttachments": false,
            "InternetMessageId": "<BY1PR19MB0023E92E0B43F5E268406F0DF5F40@BY1PR19MB0023.namprd19.prod.outlook.com>",
            "Subject": "Accepted: Latin American Product Manual Group",
            "Body": {
                "ContentType": "Text",
                "Content": ""
            },
            "BodyPreview": "",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAAEJAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyWejUoYAg=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": true,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyDREAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "MeetingMessageType": "MeetingAccepted",
            "StartDateTime": {
                "DateTime": "2015-01-05T19:00:00.0000000",
                "TimeZone": "UTC"
            },
            "EndDateTime": {
                "DateTime": "2015-01-05T20:30:00.0000000",
                "TimeZone": "UTC"
            },
            "Location": {
                "DisplayName": "Mt. Adams"
            },
            "Type": "SeriesMaster",
            "Recurrence": {
                "Pattern": {
                    "Type": "RelativeMonthly",
                    "Interval": 2,
                    "Month": 0,
                    "DayOfMonth": 0,
                    "DaysOfWeek": [
                        "Monday"
                    ],
                    "FirstDayOfWeek": "Sunday",
                    "Index": "First"
                },
                "Range": {
                    "Type": "NoEnd",
                    "StartDate": "2015-01-05",
                    "EndDate": "0001-01-01",
                    "RecurrenceTimeZone": "tzone://Microsoft/Utc",
                    "NumberOfOccurrences": 0
                }
            },
            "IsOutOfDate": false,
            "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkADIyDREAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500300,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ],
            "Event@odata.associationLink": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')/$ref",
            "Event@odata.navigationLink": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')"
        },
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')",
            "@odata.etag": "W/\"CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq\"",
            "Id": "AAMkADIyAHVAAA=",
            "CreatedDateTime": "2016-01-06T02:20:02Z",
            "LastModifiedDateTime": "2016-01-13T02:24:50Z",
            "ChangeKey": "CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:02Z",
            "SentDateTime": "2016-01-06T02:20:01Z",
            "HasAttachments": false,
            "InternetMessageId": "<CY1PR19MB0032531C620A46068FDDD45DE3F40@CY1PR19MB0032.namprd19.prod.outlook.com>",
            "Subject": "International Launch Planning for XT2000",
            "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\nWe will be ready to ship XT 2000 on 10/1, how's the International launch plan going?<br>\r\n<div style=\"display:inline-block\">\r\n<table border=\"0\" cellspacing=\"0\" style=\"background-color:#F4F4F4\">\r\n<tbody>\r\n<tr>\r\n<td style=\"padding:20px; font-size:12px; color:#666666\">You're receiving this message because you're a subscribed member of the Engineering group.<br>\r\n<a href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=conversations&amp;source=EscalatedMessage\">View group conversations</a> |\r\n<a href=\"https://adatumltd.sharepoint.com/_layouts/groupstatus.aspx?id=dbcbe107-6244-40ba-b0f1-1c46ad35435d&amp;target=documents\">\r\nView group files</a> | <a id=\"BD5134C6-8D33-4ABA-A0C4-08581FDF89DB\" href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=unsubscribe&amp;source=EscalatedMessage\">\r\nUnsubscribe</a></td>\r\n</tr>\r\n</tbody>\r\n</table>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "BodyPreview": "We will be ready to ship XT 2000 on 10/1, how's the International launch plan going?\r\nYou're receiving this message because you're a subscribed member of the Engineering group.\r\nView group conversations | View group files | Unsubscribe",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAEMAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "Engineering",
                    "Address": "engineering@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "Garret Vargas",
                    "Address": "GarretV@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyLESZnSPc=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": false,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyAHVAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkADIyAHVAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500050,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ]
        }
    ]
} 

拡張情報のデータを追加したり変更したりする

要求本文内のプロパティを使用して拡張機能を更新します。

  • 要求本文内のプロパティが拡張情報内の既存のプロパティの名前と一致すると、拡張情報内のデータが更新されます。
  • 一致しないと、このプロパティとそのデータは拡張情報に追加されます。

拡張情報は、Office 365 または Outlook.com のメッセージ、予定表イベント、または連絡先のリソース内にあります。名前か ID で参照でき、どちらの方法でも同じ応答を返します。JSON ペイロード内のデータは、プリミティブ型か、プリミティブ型の配列にすることができます。

PATCH https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extensionId}')

最低限必要なスコープ

対象リソースに対応する次の読み取り/書き込みスコープのうちのいずれかです。

パラメーター 説明
URL パラメーター
拡張機能 ID 文字列 リソース インスタンスのすべての拡張情報間で一意のテキスト識別子である拡張機能名にするか、拡張情報の種類と一意のテキスト識別子を連結した完全修飾名にすることができます。完全修飾名は、拡張情報の作成時に id プロパティ内に返されます。必須。
本文のパラメーター
拡張情報名 文字列 拡張情報の一意のテキスト識別子。必須。

要求のサンプル

このセクションの 2 つの例では、それぞれ上記の「拡張情報を取得する」の例の拡張情報を使用しています。最初の例は拡張情報を名前で参照し、2 番目の例は ID で参照しています。要求本文と応答は同じです。

各例では、次の方法で上記の拡張情報を更新します。

  • Wingtip Toys から Wingtip Toys (USA) に変更する Wingtip Toys (USA)
  • 500050 から 500100 に変更する 500100
  • 新しいデータをカスタム プロパティ Updated として追加する Updated

次の例は、拡張情報を名前で参照します。

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
} 

次の例は、拡張情報を ID (完全修飾名) で参照します。

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
} 

応答のサンプル

成功した応答は HTTP 200 OK 応答コードで示され、応答本文内に更新された拡張情報が示されています。

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": 500100,
    "ExpirationDate": "2015-12-03T10:00:00Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

拡張情報を削除する

指定されたリソースのインスタンスから拡張情報を削除します。Office 365 または Outlook.com のメッセージ、予定表イベント、または連絡先をリソースにすることができます。

サポートされている各リソースのインスタンスの拡張情報を削除するには、次のようにします。

DELETE https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extension_name}')

最低限必要なスコープ

対象リソースに対応する次の読み取り/書き込みスコープのうちのいずれかです。

パラメーター 説明
URL パラメーター
拡張名 文字列 拡張情報の一意のテキスト識別子。必須。

要求のサンプル

次の例は、拡張情報を名前で参照し、指定されたメッセージ内の拡張情報を削除します。

DELETE https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

応答のサンプル

成功した応答は、HTTP 204 No Content 応答コードで示されます。

拡張情報のエンティティ

拡張

型:Microsoft.OutlookServices.Entity

基本型が Entity エンティティの抽象型エンティティ。

オープン型の拡張機能

型:Microsoft.OutlookServices.Extension

エンティティ型のインスタンスの更新目的で JSON ペイロード内でのプロパティとデータの動的指定をサポートする抽象型の OData v4 オープン型。

プロパティ 説明 書き込み可能 フィルター処理可能
拡張情報名 文字列 一意の拡張情報名。Com.Contoso.Contact など、独自のドメインに基づくドメイン ネーム システム逆引きを使用します。 はい いいえ

次の手順

アプリケーション開発を開始する準備ができている方にも、単に詳しい情報を必要としている方にも、最適なコンテンツをご用意しています。

Office 365 プラットフォームの使い方の詳細については、次のリンク先をご覧ください。