Outlook 拡張プロパティ REST API リファレンス (ベータ版)

[アーティクル]
06/30/2018

注意

このドキュメントのバージョンでは、プレビュー段階の Outlook 拡張プロパティ REST API を取り上げます。プレビュー機能は、最終版までに変更される場合があり、それらの機能を使用するコードが動作しなくなる場合もあります。このため、一般に、運用コードでは運用バージョンの API のみを使用してください。入手可能な場合、現時点ではバージョン 2.0 が優先バージョンです。

Outlook 拡張プロパティの REST API により、アプリがカスタムデータを格納してフォールバック機構を提供し、これらのプロパティがまだ _Outlook REST API のメタデータで公開されていない_場合に、OutlookMAPI プロパティのカスタムデータにアクセスできるようにします。 ExtendedProperties API を使用して、サインインしているユーザーのアカウント内のメッセージ、メールフォルダー、イベント、予定表、連絡先、または連絡先フォルダー内のカスタムデータを格納または取得できます。ここでのアカウントには、Office 365 アカウントまたは Microsoft アカウント (Hotmail.com、Live.com、MSN.com、Outlook.com、Passport.com) を使用することができます。

注意

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

ベータ版の API が不要な場合 左の目次で、Office 365 REST API リファレンス セクションに移動し、使用したいバージョンを選択します。

REST API の拡張プロパティを使用する

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

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

認証

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

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

API のバージョン

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

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

次のリソースのインスタンスについて、拡張プロパティを作成できます。

リソースは、Office 365 または Outlook.com のサインインしているユーザーのメールボックスに存在している必要があります。

URL のパラメーター

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

パラメーター	型	説明
URL パラメータ
calendar_id	string	予定表 ID。
contact_id	string	連絡先 ID。
contactFolder_id	文字列	連絡先フォルダー ID。
event_id	string	イベント ID。
mailFolder_id	文字列	メールフォルダー ID。
message_id	string	メッセージ ID。
propertyId_value	string	いずれかのサポートされている形式の PropertyId の値。
property_value	文字列	拡張プロパティの値。
task_id	string	タスクの ID。
taskFolder_id	string	タスクフォルダーの Id。

Outlook REST API のすべてのサブセットに共通な情報の詳細については、「Outlook REST API の使用」をご覧ください。

概要

エンティティインスタンスの_拡張プロパティ_でデータを動的に作成して保存することができます。単一の値、または (同じ型の) 複数の値を保存しようとしているかどうかに応じて、拡張プロパティを SingleValueLegacyExtendedProperty、または MultiValueLegacyExtendedProperty として作成できます。

これらのタイプはそれぞれ、PropertyId によってプロパティを識別し、データを Value に格納します。

PropertyId を使用して、特定のエンティティインスタンスをその拡張プロパティと一緒に取得するか、単一の値の拡張プロパティでフィルターして、そのプロパティのすべてのインスタンスを取得できます。

注意

REST API を使用して、1 つの呼び出しで特定のインスタンスのすべての拡張プロパティを取得することはできません。

PropertyId の形式

単一値または複数値の拡張プロパティを作成する場合、文字列の名前または数値識別子のいずれか、および値の実際の型またはプロパティの値に基づき、2 つの形式のいずれかで PropertyId を指定できます。以下に示す 2 つの表では、単一値または複数値の拡張プロパティを指定するためにサポートされている形式について説明します。 {_type_} プロパティ値の種類を表しますこの例では、文字列、整数とこれらの種類の配列を示しています。

Sinceextended プロパティはほとんどの場合、Outlook REST API メタデータで公開されていない定義済みの MAPI プロパティと相互運用します。簡略化のため、選択する形式は、対応する MAPI プロパティが MAPI プロパティの識別子で文字列を使用しているか、数値を使用しているかを反映する必要があります。 [MS-OXPROPS] マイクロソフト社の「Exchange Server プロトコルマスタープロパティリスト」で、プロパティ識別子や GUID など、拡張プロパティを既存の MAPI プロパティにマッピングするのに必要な情報を検索できます。

注意

PropertyId に対してある形式を選択したら、その形式でのみ拡張プロパティにアクセスしてください。

単一値の拡張プロパティに有効な PropertyId の形式

形式	例	説明
"{type} {guid} Name {name}"	`"String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty"`	属している名前空間 (GUID) と名前で、プロパティを識別します。
"{type} {guid} Id {id}"	`"Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012"`	属している名前空間 (GUID) と識別子で、プロパティを識別します。

複数値の拡張プロパティの有効な PropertyId の形式

形式	例	説明
"{type} {guid} Name {name}"	`"StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty"`	名前空間 (GUID) と名前で、プロパティを識別します。
"{type} {guid} Id {id}"	`"IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013"`	名前空間 (GUID) と識別子で、プロパティを識別します。

既存のアイテムで拡張プロパティを作成する

サポートされたリソースの指定されたインスタンスに対して 1 つ以上の拡張プロパティを作成します。各拡張プロパティには、単一値または複数値を指定できます。

PATCH https://outlook.office.com/api/beta/me/messages('{message_id}')
PATCH https://outlook.office.com/api/beta/me/events('{event_id}')
PATCH https://outlook.office.com/api/beta/me/contacts('{contact_id}')
PATCH https://outlook.office.com/api/beta/me/tasks('{task_id}')
PATCH https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')
PATCH https://outlook.office.com/api/beta/me/calendars('{calendar_id}')
PATCH https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')
PATCH https://outlook.office.com/api/beta/me/taskfolders('{taskFolder_id}')

最低限必要なスコープ

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

https://outlook.office.com/mail.readwrite
https://outlook.office.com/calendars.readwrite
https://outlook.office.com/contacts.readwrite
https://outlook.office.com/tasks.readwrite
wl.imap
wl.calendars_update
wl.events_create
wl.contacts_create

パラメーター	型	説明
本文のパラメーター
SingleValueExtendedProperties	コレクション (SingleValueLegacyExtendedProperty)	1 つ以上の単一値を持つ拡張プロパティの配列。
PropertyId	string	SingleValueExtendedProperties コレクションの各プロパティに対してこれを指定し、プロパティを特定します。単一値の拡張プロパティに対し、サポートされる形式の 1 つに従う必要があります。必須。
Value	string	SingleValueExtendedProperties コレクションの各プロパティに対し、プロパティ値を指定します。必須です。
MultiValueExtendedProperties	コレクション (MultiValueLegacyExtendedProperty)	1 つ以上の複数値を持つ拡張プロパティの配列。
PropertyId	string	MultiValueExtendedProperties コレクションの各プロパティに対してこれを指定し、プロパティを特定します。複数値の拡張プロパティに対し、サポートされる形式の 1 つに従う必要があります。必須。
Value	コレクション (文字列)	MultiValueExtendedProperties コレクションの各プロパティに対し、そのプロパティの値を指定します。必須です。

要求のサンプル

最初の例では、指定したメッセージに対して 1 つの単一値の拡張プロパティを作成します。拡張プロパティは、SingleValueExtendedProperties 配列で唯一の要素です。要求本文には、拡張プロパティに関する次のものが含まれています。

PropertyId は、プロパティの型を string、GUID、および Color という名前のプロパティとして指定します。
Value は Green を Color プロパティの値として指定します。

PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')

Content-Type: application/json

{
  "SingleValueExtendedProperties": [
      {
         "PropertyId":"String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
         "Value":"Green"
      }
    ]
}

応答のサンプル

メッセージの更新からの応答と同様に、HTTP 200 OK 応答コードによって正常な応答が示され、応答の本文に指定したメッセージが含まれています。応答には、新しく作成された拡張プロパティは含まれません。

要求のサンプル

2 番目の例では、指定したメッセージに対して1 つの複数値の拡張プロパティを作成します。そのプロパティは、MultiValueExtendedProperties 配列の唯一の要素です。要求本文には、次のものが含まれます。

指定された GUID と名前 Palette を使用した文字列の配列を指定する PropertyId。
Value 3 つの文字列値 ["Green", "Aqua", "Blue"] の配列として Palette を指定します。

PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_as77AACHsLrBBBA=')

Content-Type: application/json

{
  "MultiValueExtendedProperties": [
      {
         "PropertyId":"StringArray {66f5a359-4659-4830-9070-00049ec6ac6e} Name Palette",
         "Value":["Green", "Aqua", "Blue"]
      }
    ]
}

応答のサンプル

新しく作成された拡張プロパティを表示するには、拡張プロパティを使用して展開されているメッセージを取得します。

新しいアイテムの拡張プロパティを作成する

同一の POST 呼び出しでサポートされるリソースの新しいインスタンスを作成しながら、1 つ以上の拡張プロパティを作成します。POST 要求の本文に、拡張プロパティが含まれます。

POST https://outlook.office.com/api/beta/me/messages
POST https://outlook.office.com/api/beta/me/events
POST https://outlook.office.com/api/beta/me/contacts
POST https://outlook.office.com/api/beta/me/tasks
POST https://outlook.office.com/api/beta/me/mailfolders
POST https://outlook.office.com/api/beta/me/calendars
POST https://outlook.office.com/api/beta/me/contactfolders
POST https://outlook.office.com/api/beta/me/taskfolders

最低限必要なスコープ

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

https://outlook.office.com/mail.readwrite
https://outlook.office.com/calendars.readwrite
https://outlook.office.com/contacts.readwrite
https://outlook.office.com/tasks.readwrite
wl.imap
wl.calendars_update
wl.events_create
wl.contacts_create

パラメーター	型	説明
本文のパラメーター
SingleValueExtendedProperties	コレクション (SingleValueLegacyExtendedProperty)	1 つ以上の単一値を持つ拡張プロパティの配列。
PropertyId	string	SingleValueExtendedProperties コレクションの各プロパティに対してこれを指定し、プロパティを特定します。単一値の拡張プロパティに対し、サポートされる形式の 1 つに従う必要があります。必須。
Value	string	SingleValueExtendedProperties コレクションの各プロパティに対し、プロパティ値を指定します。必須です。
MultiValueExtendedProperties	コレクション (MultiValueLegacyExtendedProperty)	1 つ以上の複数値を持つ拡張プロパティの配列。
PropertyId	string	MultiValueExtendedProperties コレクションの各プロパティに対してこれを指定し、プロパティを特定します。複数値の拡張プロパティに対し、サポートされる形式の 1 つに従う必要があります。必須。
Value	コレクション (文字列)	MultiValueExtendedProperties コレクションの各プロパティに対し、そのプロパティの値を指定します。必須です。

要求のサンプル

最初の例では、新しいイベントと単一値の拡張プロパティを作成します。新しいイベントに対して通常含めるプロパティとは別に、1 つの単一値の拡張プロパティを含む SingleValueExtendedProperties を要求の本文に含め、プロパティに対しては次のようにします。

PropertyId は、プロパティの型を string、GUID、および Fun という名前のプロパティとして指定します。
Value は Food を Fun プロパティの値として指定します。

POST https://outlook.office.com/api/beta/me/events

Content-Type: application/json

{
  "Subject": "Celebrate Thanksgiving",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together!"
  },
  "Start": {
      "DateTime": "2015-11-26T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-26T23:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    }
  ],
  "SingleValueExtendedProperties": [
     {
           "PropertyId":"String {66f5a359-4659-4830-9070-00040ec6ac6e} Name Fun",
           "Value":"Food"
     }
  ]
}

応答のサンプル

イベントのみの作成からの応答と同様に、HTTP 201 Created 応答コードによって正常な応答が示され、応答の本文に新しいイベントが含まれます。応答には、新しく作成された拡張プロパティは含まれません。

新しく作成された拡張プロパティを表示するには、拡張プロパティを使用して展開されているアイテムを取得します。

要求のサンプル

2 番目の例では、すべて同じ POST 操作の新しいイベントで複数値の拡張プロパティを作成します。新しいイベントに通常含まれるプロパティとは別に、要求の本文に 1 つの拡張プロパティを含む MultiValueExtendedProperties が含まれます。

要求本文には、その複数値の拡張プロパティに関する次のものが含まれています。

PropertyId 指定された GUID と名前 Recreation の文字列の配列としてプロパティを指定します。
Value 3 つの文字列値 ["Food", "Hiking", "Swimming"] の配列として Recreation を指定します。

POST https://outlook.office.com/api/beta/me/events

Content-Type: application/json

{
  "Subject": "Family reunion",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together this Thanksgiving!"
  },
  "Start": {
      "DateTime": "2015-11-26T09:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-29T21:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "Lauren@contoso.com",
        "Name": "Lauren Solis"
      },
      "Type": "Required"
    }
  ],
  "MultiValueExtendedProperties": [
     {
           "PropertyId":"StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
           "Value": ["Food", "Hiking", "Swimming"]
     }
  ]
}

応答のサンプル

新しく作成された拡張プロパティを表示するには、拡張プロパティを使用して展開されているアイテムを取得します。

拡張プロパティを使用して拡張されたアイテムを取得する

PropertyId のフィルターで指定されている拡張プロパティを使用して拡張されたサポートされるリソースのインスタンスを取得します。

PropertyId に対するフィルターで指定する文字列 {propertyId_value} は、サポートされる PropertyId の形式のどれかに従う必要があります。フィルター文字列内の空白文字に URL エンコードを適用していることを確認してください。

単一値の拡張プロパティに一致するアイテムを展開する

GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/events('{event_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/tasks('{task_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/calendars('{calendar_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/taskfolders('{taskfolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

複数値の拡張プロパティに一致するアイテムを展開する

GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/events('{event_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/tasks('{task_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/calendars('{calendar_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/taskfolders('{taskfolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

最低限必要なスコープ

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

https://outlook.office.com/mail.read
https://outlook.office.com/calendars.read
https://outlook.office.com/contacts.read
https://outlook.office.com/tasks.read
wl.imap
wl.calendars
wl.contacts_calendars
wl.basic

要求のサンプル

最初の例では、単一値の拡張プロパティを含めることによって指定されたメッセージを取得して展開します。フィルターは、文字列 String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color （読みやすさのためにURL エンコードを削除したもの) に一致する ProperId をもつ拡張プロパティを返します。

GET https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')?$expand=SingleValueExtendedProperties($filter=PropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color')

応答のサンプル

正常に作動した応答は、HTTP 200 OK 応答コードで示されます。

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

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE1M2_bs88AACHsLqWAAA=')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H\"",
    "Id": "AAMkAGE1M2_bs88AACHsLqWAAA=",
    "CreatedDateTime": "2015-11-11T02:41:24Z",
    "LastModifiedDateTime": "2015-12-09T04:07:57Z",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H",
    "Categories": [
    ],
    "ReceivedDateTime": "2015-11-11T02:41:24Z",
    "SentDateTime": "2015-11-11T02:41:24Z",
    "HasAttachments": false,
    "InternetMessageId": "<SN2SR0101MB002977E7C30F9CA9AA55961484130@SN2SR0101MB0029.contoso.com>",
    "Subject": "RE: Talk about emergency prep",
    "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=iso-8859-1\">\r\n<style type=\"text/css\" style=\"\">\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n</style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<hr tabindex=\"-1\" style=\"display:inline-block; width:98%\">\r\n<div id=\"divRplyFwdMsg\" dir=\"ltr\"><font face=\"Calibri, sans-serif\" color=\"#000000\" style=\"font-size:11pt\"><b>From:</b> Christine Irwin<br>\r\n<b>Sent:</b> Sunday, November 8, 2015 12:28:31 AM<br>\r\n<b>To:</b> Terrie Barrera<br>\r\n<b>Subject:</b> Talk about emergency prep<br>\r\n<b>When:</b> Sunday, November 8, 2015 7:00 PM-8:00 PM.<br>\r\n<b>Where:</b> The Commons</font>\r\n<div>&nbsp;</div>\r\n</div>\r\n<div>\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt; color:#000000; background-color:#FFFFFF; font-family:Calibri,Arial,Helvetica,sans-serif\">\r\n<p>Please see the attached before you come to the meeting.<br>\r\n</p>\r\n</div>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "________________________________",
    "Importance": "Normal",
    "ParentFolderId": "AQMkAGE1M2jgxCloXP1JupQN7j5uzzwAAAIBDwAAAA==",
    "Sender": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "From": null,
    "ToRecipients": [
        {
            "EmailAddress": {
                "Name": "Christine Irwin",
                "Address": "christine@contoso.com"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVlLTY0YjcxZWUzNTE1MAAQAHWT1sRiMChEmlQCIZUadoU=",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsRead": true,
    "IsDraft": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACHsLqWAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "HashtagDetailsPreview": null,
    "LikesPreview": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "UnsubscribeData": [
    ],
    "UnsubscribeEnabled": false,
    "SingleValueExtendedProperties@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGE1M2_bs88AACHsLqWAAA%3D')/SingleValueExtendedProperties",
    "SingleValueExtendedProperties": [
        {
            "PropertyId": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
            "Value": "Green"
        }
    ]
}

要求のサンプル

2 番目の例では、複数値の拡張プロパティを含めることによって指定されたイベントを取得して展開します。フィルターは、文字列 StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation （読みやすさのためにURL エンコードを削除したもの) に一致する ProperId をもつ拡張プロパティを返します。

GET https://outlook.office.com/api/beta/me/events('AAMkAGE1M2_bs88AACbuFiiAAA=')?$expand=MultiValueExtendedProperties($filter=PropertyId%20eq%20'StringArray%20{66f5a359-4659-4830-9070-00050ec6ac6e}%20Name%20Recreation')

応答のサンプル

正常に作動した応答は、HTTP 200 OK 応答コードで示されます。

応答本文には、指定されたイベントのすべてのプロパティと、フィルターから返される拡張プロパティが含まれています。

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE1M2_bs88AACbuFiiAAA=')",
    "@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAAm8k15A==\"",
    "Id": "AAMkAGE1M2_bs88AACbuFiiAAA=",
    "CreatedDateTime": "2015-12-09T05:18:05.9477979Z",
    "LastModifiedDateTime": "2015-12-09T05:18:06.197802Z",
    "ChangeKey": "mODEKWhc/Um6lA3uPm7PPAAAm8k15A==",
    "Categories": [
    ],
    "OriginalStartTimeZone": "Pacific Standard Time",
    "OriginalEndTimeZone": "Pacific Standard Time",
    "ResponseStatus": {
        "Response": "Organizer",
        "Time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "04000000828A332796D9",
    "ReminderMinutesBeforeStart": 15,
    "IsReminderOn": true,
    "HasAttachments": false,
    "Subject": "Family reunion",
    "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\nLet's get together this Thanksgiving!\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "Let's get together this Thanksgiving!",
    "Importance": "Normal",
    "Sensitivity": "Normal",
    "Start": {
        "DateTime": "2015-11-26T17:00:00.0000000",
        "TimeZone": "UTC"
    },
    "End": {
        "DateTime": "2015-11-30T05:00:00.0000000",
        "TimeZone": "UTC"
    },
    "Location": {
        "DisplayName": ""
    },
    "IsAllDay": false,
    "IsCancelled": false,
    "IsOrganizer": true,
    "Recurrence": null,
    "ResponseRequested": true,
    "SeriesMasterId": null,
    "ShowAs": "Busy",
    "Type": "SingleInstance",
    "Attendees": [
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Terrie Barrera",
                "Address": "Terrie@contoso.com"
            }
        },
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Lauren Solis",
                "Address": "Lauren@contoso.com"
            }
        }
    ],
    "Organizer": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACbuFiiAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "MultiValueExtendedProperties@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events('AAMkAGE1M2_bs88AACbuFiiAAA%3D')/MultiValueExtendedProperties",
    "MultiValueExtendedProperties": [
        {
            "PropertyId": "StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
            "Value": [
                "Food",
                "Hiking",
                "Swimming"
            ]
        }
    ]
}

拡張プロパティにフィルターを使用してアイテムを取得する

PropertyId と Value のフィルターによって指定される拡張プロパティを持つサポートされるリソースのインスタンスを取得します。フィルターは、サインインしているユーザーのメールボックス内のリソースのすべてのインスタンスに適用されます。このフィルターは、単一値のみをサポートし、複数値の拡張プロパティはサポートしません。

PropertyId に対するフィルターで指定する文字列 {propertyId_value} は、サポートされる PropertyId の形式のどれかに従う必要があります。

{property_value} が文字列ではない場合、{property_value} と比較するときに、ep/value を、必ず適切な Edm データに明示的にキャストしてください。そのようなキャストの例については、以下の非文字列型プロパティに対するサンプル要求を参照してください。

フィルター文字列内のコロン、スラッシュ、スペースに URL エンコードを適用していることをご確認ください。

GET https://outlook.office.com/api/beta/me/messages?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/events?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/contacts?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/tasks?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/mailfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/calendars?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/contactfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/taskfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

最低限必要なスコープ

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

https://outlook.office.com/mail.read
https://outlook.office.com/calendars.read
https://outlook.office.com/contacts.read
https://outlook.office.com/tasks.read
wl.imap
wl.calendars
wl.contacts_calendars
wl.basic

要求のサンプル

最初の例では、フィルターで指定された文字列型の単一値拡張プロパティをもつメッセージを取得します。フィルターは、以下のような拡張プロパティを検索します。

その PropertyId は文字列 String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color と一致します (ここでは、読みやすくするため URL エンコードを削除しています)。
その Value は文字列 Green です。

GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties%2FAny(ep%3A%20ep%2FPropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color'%20and%20ep%2FValue%20eq%20'Green')

次の 2 つの例では、文字列以外で型指定された単一値の拡張プロパティを持つメッセージを取得する方法を示しています。読みやすくするため、必要な URL エンコードは含まれていません。次の例は、以下のような拡張プロパティを検索するフィルターを示しています。

その PropertyId は文字列 CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid と一致します。
その Value は GUID b9cf8971-7d55-4b73-9ffa-a584611b600b です。プロパティ値を GUID と比較するには、ep/Value を Edm.Guid にキャストします。

GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid' and cast(ep/Value, Edm.Guid) eq (b9cf8971-7d55-4b73-9ffa-a584611b600b))

3 番目と最後の例は、以下のような拡張プロパティを検索するフィルターを示しています。

その PropertyId は文字列 Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete と一致します。
その Value は整数 12 と等しくなります。プロパティ値を整数と比較するには、ep/Value を Edm.Int32 にキャストします。

GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete' and cast(ep/Value, Edm.Int32) eq 12)

応答のサンプル

正常な応答が HTTP 200 OK 応答コードによって示され、応答の本文には、対応するフィルターに一致する拡張プロパティを持つメッセージのすべてのプロパティが含まれます。応答本文は、メッセージのコレクションの取得からの応答に似ています。応答は、一致する拡張プロパティを含みません。

次の手順

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

メール、予定表、および連絡先 REST API の使用を開始します。
サンプルについては、こちらをご覧ください。

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

Outlook 拡張プロパティ REST API リファレンス (ベータ版)

REST API の拡張プロパティを使用する

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

認証

API のバージョン

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

URL のパラメーター

概要

PropertyId の形式

拡張プロパティの操作

既存のアイテムで拡張プロパティを作成する

最低限必要なスコープ

要求のサンプル

応答のサンプル

要求のサンプル

応答のサンプル

新しいアイテムの拡張プロパティを作成する

最低限必要なスコープ

要求のサンプル

応答のサンプル

要求のサンプル

応答のサンプル

拡張プロパティを使用して拡張されたアイテムを取得する

単一値の拡張プロパティに一致するアイテムを展開する

複数値の拡張プロパティに一致するアイテムを展開する

最低限必要なスコープ

要求のサンプル

応答のサンプル

要求のサンプル

応答のサンプル

拡張プロパティにフィルターを使用してアイテムを取得する

最低限必要なスコープ

要求のサンプル

応答のサンプル

次の手順

その他のリソース