Outlook ストリーミング通知 REST API リファレンス (プレビュー)

[アーティクル]
05/31/2017

注意

このバージョンのドキュメントは、プレビュー版のストリーミング通知 API について説明します。プレビュー機能は、最終版までに変更される場合があり、それらの機能を使用するコードが動作しなくなる場合もあります。このため、一般に、運用コードでは運用バージョンの API のみを使用してください。入手可能な場合、現時点ではバージョン 2.0 が優先バージョンです。

Outlook ストリーミング通知 REST API は直接接続で通知を送信して、クライアントアプリがユーザーのメールボックスデータに対する変更について把握できるようにします。対象のデータは、Azure Active Directory によってセキュリティで保護されている Office 365 内、または Microsoft アカウント (具体的には次のドメイン) 内のユーザーのメール、予定表、連絡先、またはタスクデータ内にあります。Hotmail.com、Live.com、MSN.com、Outlook.com、および Passport.com。

注意

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

概要

Office 365 ストリーミング通知サービスはクライアントとの直接接続を確立して、クライアントアプリから要求されたデータ変更の通知を配信します。

アプリが特定のリソース (ユーザーの受信トレイ内のメッセージなど) の変更イベントの種類に関する通知をサブスクライブすると、Office 365 サーバーとクライアント間で有効期間が長い接続が確立されます。トリガーイベント (受信トレイの新しいメッセージなど) が発生すると、Office 365 サービスは、クライアントに通知をストリーム配信します。クライアントは通知を解析し、新しいメッセージを取得する、未読のカウントを更新するなど、ビジネスロジックに従って、アクションを実施します。

ストリーミングとプッシュ通知の比較

メール、予定表、CRM アプリは通常、通知を使用して、ローカルキャッシュ、対応するクライアントのビュー、またはバックエンドシステムで変更を更新します。 Outlook は、ストリーミング通知とプッシュ通知の両方をサポートしています。通知プッシュ通知では、クライアントがリスナー Web サービスを提供して Office 365 サーバーから通知を取得する必要がありますが、ストリーミング通知で必要なのは、クライアントと Office 365 サーバー間での直接接続のみです。サーバーとの接続が確立されると、接続は一定時間、開いたままになります。この間、クライアントは有効期間が長い GetNotifications 要求を 1 回だけ投稿します。トリガーイベントが発生するたびに、サーバーは通知を応答ストリームの一部として簡単に送信できます。これは接続がタイムアウトになる、クライアントによって接続が切断される、またはネットワークに問題が発生するまで続行されます。

ストリーミング通知 REST API を使用する

認証

通知をサブスクライブ、取得、および閉じるには、通知対象のリソースの種類に適したスコープを指定します。

最低限必要なスコープ

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

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

他の Outlook REST API と同様に、Outlook ストリーミング通知 API へのすべての要求に、有効なアクセストークンを含める必要があります。アクセストークンを取得するには、アプリを登録して識別させ、適切な承認を取得する必要があります。

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

API のバージョン

現時点では、この API はプレビュー状態で表示され、ベータ版の REST API エンドポイントでのみ利用できます。

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

ターゲットユーザー

ストリーミング通知 API 要求は、常に現在のユーザーのために実行されます。

ストリーミング通知の操作

Office 365 または Outlook.com のメールボックスでメール、予定表イベント、連絡先、またはタスクが変更されたときに、ストリーミング通知をサブスクライブします。これは、クライアントがリソース (エンティティまたはエンティティのコレクション) の通知の取得を開始する最初のステップです。

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

要求本文で、ストリーミングサブスクリプション要求に対して次の必須プロパティを指定します。詳細については、「 通知エンティティ」をご覧ください。

odata.type - "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription" を含めます。
ChangeType - そのリソースで監視するイベントの種類を指定します。サポートされる種類については、ChangeType をご覧ください。
Resource - 監視対象のリソースを指定します。その通知を受け取ることになります。オプションのクエリパラメーター $filter または $select を使用して、通知の条件を絞り込むか、リッチ通知に特定のプロパティを含めます。サポートされているリソースは次のとおりです。
- メッセージ、イベント、連絡先、タスクの通常のフォルダーまたは検索フォルダー。例:
  
  https://outlook.office.com/api/beta/me/mailfolders('inbox')/messages
  
  https://outlook.office.com/api/beta/me/taskfolders('{folder_id}')/tasks
- または、メッセージ、イベント、連絡先、またはタスクのトップレベルのエンティティのコレクション。
  
  https://outlook.office.com/api/beta/me/messages
  
  https://outlook.office.com/api/beta/me/events
  
  https://outlook.office.com/api/beta/me/contacts
  
  https://outlook.office.com/api/beta/me/tasks

サブスクリプション要求が成功した場合は、サブスクリプション ID が返されます。既定では、クライアントが接続で通知のリッスンを開始する場合を除き、このサブスクリプション ID は 90 分後に有効期限が切れます。接続が開いている限り、サブスクリプションは自動的に更新されます。

サブスクリプション要求のサンプル

次の要求は、ユーザーの受信トレイの作成済み、更新済み、削除済みの変更に対するストリーミングサブスクリプションを作成します。

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
   ChangeType: "Created,Updated,Deleted"
}

サブスクリプション応答のサンプル

正常な応答では、HTTP 201 が返され、サブスクリプション ID が含まれています。応答の例を次に示します。

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('RUM4OEJFNUIQUQ4MQ==')",
    "Id":"RUM4OEJFNUIQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

通知条件を絞り込む

句を使用して、アイテムのサブセットに対する通知を制限することができます。たとえば、次のサブスクリプション要求は、"Supplements" フィールドを持つメッセージに変更が行われた場合にのみ通知をトリガーするサブスクリプションを作成します。$filter

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
   ChangeType: "Created,Updated,Deleted"
}

正常なサブスクリプションの応答は、次のようになります。

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('MjcwOUQ2MjEtQUQ4MQ==')",
    "Id":"MjcwOUQ2MjEtQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

単にリソースコレクションのために設定されたサブスクリプションは、変更されたリソースインスタンスの ID を返します。そのインスタンスのプロパティを別に取得する必要があります。上の最初のサブスクリプション要求では、この種類のサブスクリプションの例を示しています。次のセクションの通知ストリームでは、リソース ID だけが通知に入れて返される様子を示しています。

サブスクリプション要求で代わりに $select パラメーターを使用し、必要なプロパティを指定して、それらのプロパティの値をストリーミング通知で返すこともできます。

次に、イベントが作成された場合に、ストリーミング通知に Subject プロパティを含めるよう要求する例を示します。

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
    @odata.type:"#Microsoft.OutlookServices.StreamingSubscription",
    Resource: "https://outlook.office.com/api/beta/me/events?$select=Subject",
    ChangeType: "Created"
}

リッチストリーミング通知へのサブスクライブが正常に完了したら、通知をリッスンしてリッチ通知ペイロードで Subject プロパティを取得します。

通知のリッスン

クライアントは、指定したサブスクリプションに対して有効期間が長い保留中の POST 接続を作成して、ストリーミング通知を開始するようサーバーに要求します。

POST https://outlook.office.com/api/beta/Me/GetNotifications

この POST 要求は、指定した ConnectionTimeoutinMinutes に到達して、サーバーが応答で JSON BLOB を終了するまで、あるいは他に問題があり、クライアントまたはサーバーが接続を閉じる場合は完了しません。

接続が開いている限り、接続を使用するすべてのサブスクリプションは自動更新されます。接続が終了すると、クライアントがこれらのサブスクリプションに対して新しい接続をセットアップしない限り、これらのサブスクリプションも 90 分後に有効期限が切れます。

この POST 要求を実行するコードが、リターン状態コード HTTP 404 Not found を処理することを確認します。このリターン状態コードは、指定したサブスクリプションが実際に有効期限切れになっている場合に返されます。この場合は、通知を再度リッスンする前に、新しいサブスクリプションを要求します。

必要な本文パラメーター	種類	説明
ConnectionTimeoutInMinutes	int32	接続を有効にする時間 (分)。
KeepAliveNotificationIntervalInSeconds	int32	キープアライブ通知を送信して、接続が開いたままであることをクライアントに通知するための、サーバーによって使用される間隔。
SubscriptionIds	Collection(String)	この接続で通知されるサブスクリプションの ID。

リッスン要求のサンプル

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg=="
   ]
}

POST 要求に 1 つ以上のサブスクリプション ID を含めることによって、同じ有効期間の長い接続を使用して、複数のサブスクリプションの通知をリッスンできます。

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg==",
       "Dc4NS04MTg2LUYwRjFFNUVFNTNDRgN0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtN=="
   ]
}

通知ストリームのサンプル

サービスをセットアップすると、クライアントは JSON BLOB 通知の先頭を受信します。

{
    {"@odata.context":"https://outlook.office.com/api/beta/metadata#Notifications", 
    "value": [

サーバーでは、キープアライブ通知を一定の間隔で送信し、接続が開いていて有効である状態を維持します。この間隔は、KeepAliveNotificationIntervalInSeconds プロパティのクライアントによって設定されます。キープアライブ通知の形式は次のようになります。

{
    "@odata.type": "#Microsoft.OutlookServices.KeepAliveNotification",
    "Status": "OK"
}

サーバーで変更が追跡されると、サーバーは接続を介してクライアントに通知を送信します。各通知で、サーバーは SubscriptionExpirationDateTime プロパティを設定して、前の通知が成功する限り、このプロパティを更新し続けます。

{ 
    "@odata.type": "#Microsoft.OutlookServices.Notification",
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    "SubscriptionExpirationDateTime": "2016-09-09T18:36:42.3454926Z",
    "SequenceNumber": 9, 
    "ChangeType": "Created", 
    "Resource": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
    "ResourceData": { 
        "@odata.type": "#Microsoft.OutlookServices.Message", 
        "@odata.id": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
        "@odata.etag": "W/\"CQAAABYAAAB+0z/4Ly/1ToDr5FGl5k99AAABl5Do\"", 
        "Id": "AAMkADdlAA=" 
    } 
}

アプリケーションが同じ有効期限の長い接続で複数の通知をリッスンしている場合は、SubscriptionId フィールドを使用して、通知を送信したサブスクリプションを特定できます。

注意

サーバーから送信された 2 番目以降の通知では、通知を有効な JSON にするために、左かっこの前にコンマが先頭に追加されています。

,{
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    ...
}

リッチ通知ペイロードのサンプル

サブスクリプション要求で特定のプロパティを返すことを指定している場合、通知ペイロードにはこれらのプロパティの値が含まれます。上記のリッチ通知へのサブスクライブの例に従い、Subject プロパティを含むリッチ通知ペイロードは次のようになります。

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Notifications",
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "QjQzNzAwBQQ==",
      "SubscriptionExpirationDateTime": "2017-01-18T00:57:28.6134733Z",
      "SequenceNumber": 1,
      "ChangeType": "Created",
      "Resource": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
      "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Event",
        "@odata.id": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

接続を閉じる

プロパティに指定したタイムアウトに達すると、サーバーは接続を閉じて、次のような JSON BLOB の末尾を送信します。ConnectionTimeoutInMinutes

]
}

ネットワークの問題や再起動のようなサーバーへの変更など他の状況では、接続が切断する可能性があります。クライアントはキープアライブ通知を使用して、接続がアクティブのままであるか、切断されているかを特定できます。後者の場合、クライアントは既存のサブスクリプション ID を使用して再接続を試行します。サブスクリプション ID の有効期限が切れている場合は、接続を再確立するために新しいサブスクリプション要求を行う必要があります。

クライアントがこれ以上サブスクリプションをリッスンしない場合は、クライアントは POST 要求をキャンセルして、接続を切断できます。次回、サーバーが通知を送信しようとするとエラーが発生し、サーバーは接続の切断を検出して、キープアライブ通知を停止して接続を閉じます。

通知のエンティティおよび列挙型

サブスクリプション

基本のサブスクリプションを表します。これは抽象基本クラスです。

基本型:Entity

プロパティ	型	説明	書き込み可能	フィルター処理可能
リソース	文字列	変更の監視対象となるリソースを指定します。	はい	該当なし
ChangeType	ChangeType	通知を発生させるイベントの種類を示します。サポートされる種類については、ChangeType をご覧ください。	はい	該当なし

通知

クライアントに送られる通知を表します。

基本型:Entity

プロパティ	型	説明	書き込み可能	フィルター処理可能
SubscriptionId	文字列	サブスクリプションの一意の識別子です。	いいえ	該当なし
SequenceNumber	int32	変更通知のシーケンス値を示します。	いいえ	該当なし
ChangeType	文字列	通知を発生させたイベントの種類を示します。サポートされる種類については、ChangeType をご覧ください。	いいえ	該当なし
リソース	文字列	変更の監視対象となっているリソースアイテムを指定します	いいえ	該当なし
ResourceData	エンティティ	変更されたエンティティを識別します。これはナビゲーションのプロパティです。	いいえ	該当なし

ChangeType

通知を発生させることのできるサポートされているリソースに対して発生するイベントの種類を指定する列挙型。

サポートされている値:

承認
作成済み
削除済み
Missed。Missed 通知は、通知サービスが要求された通知を送信できない場合に発生します。
更新済み

次の手順

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

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

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

次の方法で共有

Outlook ストリーミング通知 REST API リファレンス (プレビュー)

概要

ストリーミングとプッシュ通知の比較

ストリーミング通知 REST API を使用する

認証

最低限必要なスコープ

API のバージョン

ターゲットユーザー

ストリーミング通知の操作

サブスクリプション要求のサンプル

サブスクリプション応答のサンプル

通知条件を絞り込む

通知のリッスン

リッスン要求のサンプル

通知ストリームのサンプル

リッチ通知ペイロードのサンプル

接続を閉じる

通知のエンティティおよび列挙型

サブスクリプション

通知

ChangeType

次の手順

その他のリソース

次の方法で共有

Outlook ストリーミング通知 REST API リファレンス (プレビュー)

概要

ストリーミングとプッシュ通知の比較

ストリーミング通知 REST API を使用する

認証

最低限必要なスコープ

API のバージョン

ターゲット ユーザー

ストリーミング通知の操作

自分のメール、予定表、連絡先、またはタスクの変更のサブスクライブ

サブスクリプション要求のサンプル

サブスクリプション応答のサンプル

通知条件を絞り込む

リッチ ストリーミング通知にサブスクライブする

通知のリッスン

リッスン要求のサンプル

通知ストリームのサンプル

リッチ通知ペイロードのサンプル

接続を閉じる

通知のエンティティおよび列挙型

サブスクリプション

通知

ChangeType

次の手順

その他のリソース

ターゲットユーザー

リッチストリーミング通知にサブスクライブする