Table of contents
TOC
目次を折りたたむ
目次を展開する
最終更新日: 2017/11/10

Outlook プッシュ通知 REST API リファレンス

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

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

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

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

ベータ版の API が不要な場合右上隅のコントロールを使用して、必要なバージョンを選択します。

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

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

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

API v2.0 が不要な場合右上隅のコントロールを使用して、必要なバージョンを選択します。

概要

Office 365 プッシュ通知サービスと API は、コールバック アドレスを Web サービスに提供するクライアントを処理し、Webhook を使用してクライアント アプリに通知を配信します。Webhook は、通常、サード パーティの信頼されたバックエンド Web サービスで構成されている HTTP コールバックです。Web サービスは、1 つのサイトでトリガー イベントを発生させて別のサイトで動作を呼び出すように Webhook を構成できます。

アプリが特定のリソース (ユーザーの受信トレイ内のメッセージなど) の通知をサブスクライブする場合は、サブスクリプション要求に Webhook コールバック URL を指定します。トリガー イベント (受信トレイの新しいメッセージなど) が発生すると、Office 365 通知サービスは、コールバック URL に Webhook を使用して通知をプッシュします。次に、アプリが、新しいメッセージを取得する、未読のカウントを更新するなど、ビジネス ロジックに従って、アクションを実施します。

アプリは、期限が切れる前にサブスクリプションを更新する必要があります。また、サブスクリプションを中止して、通知の受信をいつでも停止することができます。

Office 365 プッシュ通知サービスと API は、コールバック アドレスを Web サービスに提供するクライアントを処理し、Webhook を使用してクライアント アプリに通知を配信します。Webhook は、通常、サード パーティの信頼されたバックエンド Web サービスで構成されている HTTP コールバックです。Web サービスは、1 つのサイトでトリガー イベントを発生させて別のサイトで動作を呼び出すように Webhook を構成できます。

アプリが特定のリソース (ユーザーの受信トレイ内のメッセージなど) の通知をサブスクライブする場合は、サブスクリプション要求に Webhook コールバック URL を指定します。トリガー イベント (受信トレイの新しいメッセージなど) が発生すると、Office 365 通知サービスは、コールバック URL に Webhook を使用して通知をプッシュします。次に、アプリが、新しいメッセージを取得する、未読のカウントを更新するなど、ビジネス ロジックに従って、アクションを実施します。

アプリは、期限が切れる前にサブスクリプションを更新する必要があります。また、サブスクリプションを中止して、通知の受信をいつでも停止することができます。

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

メール、予定表、CRM アプリは通常、通知を使用して、ローカル キャッシュ、対応するクライアントのビュー、またはバックエンド システムで変更を更新します。 Outlook は、ストリーミング通知とプッシュ通知の両方をサポートしています。 現時点で、プッシュ通知は一般にモバイル アプリで使用されています。クライアントは変更をポーリングする必要がなく、更新内容はクライアントに対してほぼ瞬時に利用可能になるからです。

プッシュ通知とストリーミング通知と比較すると、プッシュ通知の場合、クライアントは通知を取得するために独自の Web サービスを提供する必要がありますが、ストリーミング通知の場合は、クライアントと Office 365 のストリーミング通知サービスとの間の直接接続しか必要としません。

メール、予定表、CRM アプリは通常、通知を使用して、ローカル キャッシュ、対応するクライアントのビュー、またはバックエンド システムで変更を更新します。 Outlook は、ストリーミング通知とプッシュ通知の両方をサポートしています。 現時点で、プッシュ通知は一般にモバイル アプリで使用されています。クライアントは変更をポーリングする必要がなく、更新内容はクライアントに対してほぼ瞬時に利用可能になるからです。

プッシュ通知とストリーミング通知と比較すると、プッシュ通知の場合、クライアントは通知を取得するために独自の Web サービスを提供する必要がありますが、ストリーミング通知の場合は、クライアントと Office 365 のストリーミング通知サービスとの間の直接接続しか必要としません。

プッシュ通知 REST API の使用

認証

サブスクリプションの登録、クエリの実行、更新、削除を行うには、通知対象のリソースの種類に適したスコープを指定します。

最小限必要なスコープ: 次の対象リソースに対応する読み取りスコープのうちのいずれかです。

他の Outlook REST API と同様に、Outlook プッシュ通知 API へのすべての要求に、有効なアクセス トークンを含める必要があります。 アクセス トークンを取得するには、アプリを登録して識別させ、適切な承認を取得する必要があります。 効率化された登録と承認のオプションに関する詳細情報を参照してください。 プッシュ通知 API で特定の操作を続行する際には、この点にご留意ください。

サブスクリプションの登録、クエリの実行、更新、削除を行うには、通知対象のリソースの種類に適したスコープを指定します。

最小限必要なスコープ: 次の対象リソースに対応する読み取りスコープのうちのいずれかです。

他の Outlook REST API と同様に、Outlook プッシュ通知 API へのすべての要求に、有効なアクセス トークンを含める必要があります。 アクセス トークンを取得するには、アプリを登録して識別させ、適切な承認を取得する必要があります。 効率化された登録と承認のオプションに関する詳細情報を参照してください。 プッシュ通知 API で特定の操作を続行する際には、この点にご留意ください。

API のバージョン

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

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

ターゲット ユーザー

プッシュ通知 API 要求は、常に現在のユーザーのために実行されます。

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


プッシュ通知 API 要求は、常に現在のユーザーのために実行されます。

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


プッシュ通知の操作

通知をサブスクライブする | サブスクリプションを更新する | サブスクリプションを削除する

通知をサブスクライブする | サブスクリプションを更新する | サブスクリプションを削除する

自分のメール、予定表、連絡先、タスクの変更に対するサブスクライブ

サブスクリプション プロセス

サブスクリプション プロセスは、次のようになります。

  1. クライアント アプリが、特定のリソースのサブスクリプション要求 (POST) を行います。それには通知 URL などのプロパティが含まれます。

  2. Outlook の通知サービスは、リスナー サービスによって通知 URL を検証しようとします。これには、検証要求の検証トークンが含まれます。

  3. リスナー サービスが正常に URL の検証を行った場合、次のように成功の応答を 5 秒以内に返します。

    • 応答ヘッダーのコンテンツ タイプを  text\plain に設定します。
    • 応答の本文に同じ検証トークンを含めます。
    • HTTP 200 の応答コードを返します。リスナーは、その後の検証トークンを破棄できます。
  4. URL の検証結果に応じて、Outlook の通知サービスはクライアント アプリに応答を送信します。

    • URL の検証が成功した場合、サービスは一意なサブスクリプション ID を持つサブスクリプションを作成し、クライアントへの応答を送信します。
    • URL の検証が正常に終了しない場合、サービスはエラー コードとその他の詳細を含むエラー応答を送信します。
  5. クライアント アプリは、正常な応答を受信すると、将来の通知をこのサブスクリプションと関連付けるため、サブスクリプション ID を格納します。

サブスクリプション要求

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

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

要求本文で、プッシュ サブスクリプション要求に対して次のプロパティを指定します。 ClientState 以外のすべてのプロパティが必須です。 詳細については、「 Notification エンティティ」を参照してください。

  • odata.type - "@odata.type":"#Microsoft.OutlookServices.PushSubscription" を含めます。 PushSubscription エンティティは NotificationURL を定義します。
  • ChangeType - そのリソースのために監視するイベントの種類を指定します。 サポートされる種類については、「ChangeType」を参照してください。
  • ClientState - 同じ ClientState の値のヘッダーで各通知が送信されなければならないことを示す、オプションのプロパティ。 これにより、リスナーは各通知の正当性を確認できます。
  • NotificationURL - 通知の送信先を指定します。 この URL は、通常クライアントで実装される Web サービスを表します。
  • 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

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

次の例は、新しいイベントをサブスクライブする方法を示しています。

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

{
   "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
   "Resource": "https://outlook.office.com/api/beta/me/events",
   "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",  
   "ChangeType": "Created",
   "ClientState": "c75831bd-fad3-4191-9a66-280a48528679"
}

通知条件を絞り込む

$filter クエリ パラメーターを使用すれば、通知の条件をさらに詳細に設定することができます。

次の例では、下書きフォルダーで作成中で、1 つまたは複数の添付ファイルを含み、重要度が  Highメッセージに関して通知を要求します。

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/me/mailfolders('Drafts')/messages?$filter=HasAttachments%20eq%20true%20AND%20Importance%20eq%20%27High%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Has attachments and high importance" 
} 

次の例では、作成中の終日イベントに関して通知を要求します。

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/me/events?$filter=IsAllDay%20eq%20true", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Notifications for events that IsAllDay." 
} 

次の例では、Contoso という会社の、作成中の Contact に関する通知を要求します。

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/me/contacts?$filter=CompanyName%20eq%20%27Contoso%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Contacts in Contoso." 
} 

$filter の一般的な使用方法として、指定されたリソースの特定のプロパティが変化したら通知を受けるというものがあります。 たとえば、$filter を使用して、フォルダー内の未読メッセージ (IsRead プロパティが false) を受信し、すべての変更の種類を含めることができます。

  • フォルダー内の追加されたメッセージ、または未読のマークが付けられているメッセージにより、Created 通知がトリガーされます。
  • フォルダー内のメッセージを閲覧すること、またはメッセージに開封済みのマークを付けることにより、Deleted 通知がトリガーされます。
  • フォルダー内のメッセージで IsRead 以外のプロパティを変更すると、Updated 通知がトリガーされます。

そのようなサブスクリプションを次のように作成することができます。

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

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/beta/me/mailfolders('folder_id')/messages$filter=IsRead%20eq%20false",
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

サブスクリプションを作成するときに $filter を使用しない場合 (以下に例を挙げます)、次のようになります。

  • フォルダーにメッセージを追加すると、結果として Created 通知が行われます。
  • フォルダー内のメッセージの閲覧、メッセージに開封済みのマークを付けること、またはフォルダー内のメッセージのその他のメッセージ プロパティを変更することにより、結果として Updated 通知が行われます。
  • メッセージを削除すると、結果として Delete 通知が行われます。
POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/beta/me/mailfolders('folder_id')/messages,
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

検証要求

検証要求は、サブスクリプション要求でクライアント アプリが指定する NotificationURL を検証しようとします。

POST https://{notificationUrl}?validationToken={token}

Outlook のサービスでは、サブスクリプション要求の NotificationURL を{notificationUrl} で指定し、文字列 {token} を検証トークンとして定義します。 クライアント アプリがサブスクリプション要求に ClientState ヘッダーを含める場合、Outlook サービスもそのヘッダーを含めます。

サブスクリプション応答

サブスクリプション応答には、要求のプロパティ、および次の追加のプロパティが含まれています。

  • Id – 今後の通知と一致するようにクライアント アプリが保存する必要がある一意なサブスクリプション ID。
  • ChangeType - 要求で指定された値とは別に、追加の通知タイプである Missed が応答に含まれます。
  • SubscriptionExpirationDateTime - サブスクリプションの有効期限が切れる日付と時刻。 サブスクリプション要求に有効期限の時刻を指定しない場合、または要求が最大時間よりも長い有効期限を指定している場合、このプロパティは要求が送信された時刻からの最大時間に設定されます。 特定のプロパティのリッチ通知を要求するサブスクリプションについて、最大許容値は 1 日です。 その他のサブスクリプションでは、最大値は 7 日間です。
  • 他の OData 関連のプロパティ。

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

この応答では、リスナー サービスが新しいイベントと失敗した変更の通知の受信を想定していることを示します。変更に失敗した場合、クライアントはその変更をキャプチャするためにサービスと同期する必要があります。

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')",
    "Id": "Mjk3QNERDQQ==",
    "Resource": "https://outlook.office.com/api/beta/me/events",
    "ChangeType": "Created, Missed",
    "ClientState": "c75831bd-fad3-4191-9a66-280a48528679",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
    "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z"
}

サブスクリプションを問い合わせる: サインインしているユーザーの既存のサブスクリプションのいずれかに関する詳細情報は、そのサブスクリプション ID を指定することによって検索できます。 たとえば、最後の例で作成したサブスクリプションのクエリを実行するには、次のようにします。

GET https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')

成功すると、クライアント アプリケーションが潜在的なセキュリティ リスクを回避するために指定した ClientState を除外するという点を除き、
応答はサンプルの最後の応答データと同じです。

通知

各通知には、その種類に関係なく、以下のプロパティが含まれています。

  • ClientState ヘッダー - クライアントがサブスクリプション要求で ClientState プロパティを指定した場合にのみ存在します。 通知の正当性を確認するために、リスナーによって使用されます。
  • SubscriptionId - この通知が所属するサブスクリプションをクライアント アプリに識別させます。
  • SubscriptionExpirationDateTime - サブスクリプションの有効期限が切れる日付と時刻。
  • SequenceNumber - 通知が欠落していないかどうかをクライアント アプリが識別できるようにする、通知の連続した番号。
  • ChangeType - クライアント アプリケーションに通知しようとしているイベントの種類 (たとえば、メールを受信したときの Created イベント、メッセージを読むときの Update イベント)。
  • Resource – 監視されている特定のリソース アイテムの URL (変更されたメッセージまたはイベントへの URL など)。
  • ResourceData - リソースの変更に関連する通知 (メッセージを受信する、読む、削除するなど) が、変更されたアイテムのリソース ID を含むこの追加のプロパティを持っています。 クライアントはこのリソース ID を使用して、ビジネス ロジック (このアイテムをフェッチする、フォルダーを同期するなど) に従ってこのアイテムを処理できます

注:Notification エンティティでは、Id プロパティは使用されません。

変更通知のペイロード

次の例では、ユーザーが新しいイベントを受け取ると、通知サービスは ChangeType を "Created" に設定した通知を送信します。通知のヘッダーには、初期サブスクリプション要求で指定されている ClientState が含まれます。受信イベントの通知には、次のようなペイロードがあります。

{
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.Notification",
            "Id": null,
            "SubscriptionId": "Mjk3QNERDQQ==",
            "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z",
            "SequenceNumber": 1,
            "ChangeType": "Created",
            "Resource" : "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
            "ResourceData": {
                "@odata.type": "#Microsoft.OutlookServices.Event",
                "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
                "Id": "AAMkADNkNmAA="
            }
        }
    ]
}

リッチ通知へのサブスクライブによってインスタンス プロパティを取得する

変更通知ペイロードの最後のに示したとおり、リソース コレクションに設定したプッシュ通知のサブスクリプションでは、変更されたリソース インスタンスの ID だけを返します。 そのインスタンスのプロパティを別に取得する必要があります。

サブスクリプション要求で $select パラメーターを使用して、必要なプロパティを指定すれば、追加の GET API の呼び出しを省くことができます。 次に、イベントが作成された場合に、通知に subject プロパティを含めるよう要求する例を示します。

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

{
    "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
    "Resource": "https://outlook.office.com/api/beta/me/events?$select=Subject",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myRichNotifyClient",
    "ChangeType": "Created"
}

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

リッチ通知ペイロードには、サブスクリプション要求で指定したプロパティの値が含まれます。 前の例に従い、リッチ通知には次のように 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"
      }
    }
  ]
}

サブスクリプション プロセス

サブスクリプション プロセスは、次のようになります。

  1. クライアント アプリが、特定のリソースのサブスクリプション要求 (POST) を行います。それには通知 URL などのプロパティが含まれます。

  2. Outlook の通知サービスは、リスナー サービスによって通知 URL を検証しようとします。これには、検証要求の検証トークンが含まれます。

  3. リスナー サービスが正常に URL の検証を行った場合、次のように成功の応答を 5 秒以内に返します。

    • 応答ヘッダーのコンテンツ タイプを  text\plain に設定します。
    • 応答の本文に同じ検証トークンを含めます。
    • HTTP 200 の応答コードを返します。リスナーは、その後の検証トークンを破棄できます。
  4. URL の検証結果に応じて、Outlook の通知サービスはクライアント アプリに応答を送信します。

    • URL の検証が成功した場合、サービスは一意なサブスクリプション ID を持つサブスクリプションを作成し、クライアントへの応答を送信します。
    • URL の検証が正常に終了しない場合、サービスはエラー コードとその他の詳細を含むエラー応答を送信します。
  5. クライアント アプリは、正常な応答を受信すると、将来の通知をこのサブスクリプションと関連付けるため、サブスクリプション ID を格納します。

サブスクリプション要求

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

POST https://outlook.office.com/api/v2.0/me/subscriptions

要求本文で、プッシュ サブスクリプション要求に対して次のプロパティを指定します。 ClientState 以外のすべてのプロパティが必須です。 詳細については、「 Notification エンティティ」を参照してください。

  • odata.type - "@odata.type":"#Microsoft.OutlookServices.PushSubscription" を含めます。 PushSubscription エンティティは NotificationURL を定義します。
  • ChangeType - そのリソースのために監視するイベントの種類を指定します。 サポートされる種類については、「ChangeType」を参照してください。
  • ClientState - 同じ ClientState の値のヘッダーで各通知が送信されなければならないことを示す、オプションのプロパティ。 これにより、リスナーは各通知の正当性を確認できます。
  • NotificationURL - 通知の送信先を指定します。 この URL は、通常クライアントで実装される Web サービスを表します。
  • Resource - - Resource - 監視対象のリソースを指定します。その通知を受け取ることになります。 オプションのクエリ パラメーター $filter を使用して通知の条件を絞り込むか、$select を使用してリッチ通知に特定のプロパティを含めることができます。 サポートされているリソースは次のとおりです。

    • メッセージ、イベント、連絡先、タスクの通常のフォルダーまたは検索フォルダー。例:

      https://outlook.office.com/api/v2.0/me/mailfolders('inbox')/messages

      https://outlook.office.com/api/v2.0/me/taskfolders('{folder_id}')/tasks

    • または、メッセージ、イベント、連絡先、またはタスクのトップレベルのエンティティのコレクション。

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

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

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

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

要求のサンプル

次の例は、新しいイベントをサブスクライブする方法を示しています。

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

{
   "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
   "Resource": "https://outlook.office.com/api/v2.0/me/events",
   "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",  
   "ChangeType": "Created",
   "ClientState": "c75831bd-fad3-4191-9a66-280a48528679"
}

通知条件を絞り込む

$filter クエリ パラメーターを使用すれば、通知の条件をさらに詳細に設定することができます。

次の例では、下書きフォルダーで作成中で、1 つまたは複数の添付ファイルを含み、重要度が  Highメッセージに関して通知を要求します。

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('Drafts')/messages?$filter=HasAttachments%20eq%20true%20AND%20Importance%20eq%20%27High%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Has attachments and high importance" 
} 

次の例では、作成中の終日イベントに関して通知を要求します。

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/v2.0/me/events?$filter=IsAllDay%20eq%20true", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Notifications for events that IsAllDay." 
} 

次の例では、Contoso という会社の、作成中の Contact に関する通知を要求します。

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

{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/v2.0/me/contacts?$filter=CompanyName%20eq%20%27Contoso%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Contacts in Contoso." 
} 

$filter の一般的な使用方法として、指定されたリソースの特定のプロパティが変化したら通知を受けるというものがあります。 たとえば、$filter を使用して、フォルダー内の未読メッセージ (IsRead プロパティが false) を受信し、すべての変更の種類を含めることができます。

  • フォルダー内の追加されたメッセージ、または未読のマークが付けられているメッセージにより、Created 通知がトリガーされます。
  • フォルダー内のメッセージを閲覧すること、またはメッセージに開封済みのマークを付けることにより、Deleted 通知がトリガーされます。
  • フォルダー内のメッセージで IsRead 以外のプロパティを変更すると、Updated 通知がトリガーされます。

そのようなサブスクリプションを次のように作成することができます。

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

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('folder_id')/messages$filter=IsRead%20eq%20false",
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

サブスクリプションを作成するときに $filter を使用しない場合 (以下に例を挙げます)、次のようになります。

  • フォルダーにメッセージを追加すると、結果として Created 通知が行われます。
  • フォルダー内のメッセージの閲覧、メッセージに開封済みのマークを付けること、またはフォルダー内のメッセージのその他のプロパティを変更することにより、結果として Updated 通知が行われます。
  • メッセージを削除すると、結果として Delete 通知が行われます。
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('folder_id')/messages,
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

検証要求

検証要求は、サブスクリプション要求でクライアント アプリが指定する NotificationURL を検証しようとします。

POST https://{notificationUrl}?validationToken={token}

Outlook のサービスでは、サブスクリプション要求の NotificationURL を{notificationUrl} で指定し、文字列 {token} を検証トークンとして定義します。 クライアント アプリがサブスクリプション要求に ClientState ヘッダーを含める場合、Outlook サービスもそのヘッダーを含めます。

サブスクリプション応答

サブスクリプション応答には、要求のプロパティ、および次の追加のプロパティが含まれています。

  • Id – 今後の通知と一致するようにクライアント アプリが保存する必要がある一意なサブスクリプション ID。
  • ChangeType - 要求で指定された値とは別に、追加の通知タイプである Missed が応答に含まれます。
  • SubscriptionExpirationDateTime - サブスクリプションの有効期限が切れる日付と時刻。 サブスクリプション要求に有効期限の時刻を指定しない場合、または要求が最大時間よりも長い有効期限を指定している場合、このプロパティは要求が送信された時刻からの最大時間に設定されます。 特定のプロパティのリッチ通知を要求するサブスクリプションについて、最大許容値は 1 日です。 その他のサブスクリプションでは、最大値は 7 日間です。
  • 他の OData 関連のプロパティ。

応答データのサンプル

この応答では、リスナー サービスが新しいイベントと失敗した変更の通知の受信を想定していることを示します。変更に失敗した場合、クライアントはその変更をキャプチャするためにサービスと同期する必要があります。

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Subscriptions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')",
    "Id": "Mjk3QNERDQQ==",
    "Resource": "https://outlook.office.com/api/v2.0/me/events",
    "ChangeType": "Created, Missed",
    "ClientState": "c75831bd-fad3-4191-9a66-280a48528679",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
    "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z"
}

サブスクリプションを問い合わせる: サインインしているユーザーの既存のサブスクリプションのいずれかに関する詳細情報は、そのサブスクリプション ID を指定することによって検索できます。 たとえば、最後の例で作成したサブスクリプションのクエリを実行するには、次のようにします。

GET https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')

成功すると、クライアント アプリケーションが潜在的なセキュリティ リスクを回避するために指定した ClientState を除外するという点を除き、
応答はサンプルの最後の応答データと同じです。

通知

各通知には、その種類に関係なく、以下のプロパティが含まれています。

  • ClientState ヘッダー - クライアントがサブスクリプション要求で ClientState プロパティを指定した場合にのみ存在します。 通知の正当性を確認するために、リスナーによって使用されます。
  • SubscriptionId - この通知が所属するサブスクリプションをクライアント アプリに識別させます。
  • SubscriptionExpirationDateTime - サブスクリプションの有効期限が切れる日付と時刻。
  • SequenceNumber - 通知が欠落していないかどうかをクライアント アプリが識別できるようにする、通知の連続した番号。
  • ChangeType - クライアント アプリケーションに通知しようとしているイベントの種類 (たとえば、メールを受信したときの Created イベント、メッセージを読むときの Update イベント)。
  • Resource – 監視されている特定のリソース アイテムの URL (変更されたメッセージまたはイベントへの URL など)。
  • ResourceData - リソースの変更に関連する通知 (メッセージを受信する、読む、削除するなど) が、変更されたアイテムのリソース ID を含むこの追加のプロパティを持っています。 クライアントはこのリソース ID を使用して、ビジネス ロジック (このアイテムをフェッチする、フォルダーを同期するなど) に従ってこのアイテムを処理できます

注:Notification エンティティでは、Id プロパティは使用されません。

変更通知のペイロード

次の例では、ユーザーが新しいイベントを受け取ると、通知サービスは ChangeType を "Created" に設定した通知を送信します。通知のヘッダーには、初期サブスクリプション要求で指定されている ClientState が含まれます。受信イベントの通知には、次のようなペイロードがあります。

{
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.Notification",
            "Id": null,
            "SubscriptionId": "Mjk3QNERDQQ==",
            "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z",
            "SequenceNumber": 1,
            "ChangeType": "Created",
            "Resource" : "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
            "ResourceData": {
                "@odata.type": "#Microsoft.OutlookServices.Event",
                "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
                "Id": "AAMkADNkNmAA="
            }
        }
    ]
}

リッチ通知へのサブスクライブによってインスタンス プロパティを取得する

変更通知ペイロードの最後のに示したとおり、リソース コレクションに設定したプッシュ通知のサブスクリプションでは、変更されたリソース インスタンスの ID だけを返します。 そのインスタンスのプロパティを別に取得する必要があります。

サブスクリプション要求で $select パラメーターを使用して、必要なプロパティを指定すれば、追加の GET API の呼び出しを省くことができます。 次に、イベントが作成された場合に、通知に subject プロパティを含めるよう要求する例を示します。

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

{
    "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
    "Resource": "https://outlook.office.com/api/v2.0/me/events?$select=Subject",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myRichNotifyClient",
    "ChangeType": "Created"
}

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

リッチ通知ペイロードには、サブスクリプション要求で指定したプロパティの値が含まれます。 次の最後の例では、リッチ通知は Subject プロパティを含んでいます。

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$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/v2.0/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/v2.0/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

サブスクリプションを更新する

更新要求の時間から最大時間までサブスクリプションを更新します。

PATCH https://outlook.office.com/api/beta/me/subscriptions/{subscriptionId}

応答に特定のインスタンス プロパティを必要としないサブスクリプション要求では既定のサブスクリプション時間は 7 日であり、リッチ通知のサブスクリプションでは 1 日です。

ペイロードなしで更新要求を送信することができ、サブスクリプションは対応する最大期間だけ延長されます。

要求のサンプル

PATCH https://outlook.office.com/api/beta/me/subscriptions/Mjk3QNERDQQ==

{
   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   "SubscriptionExpirationDateTime": "2015-05-28T17:17:45.9028722Z"
}

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

更新要求の時間から最大時間までサブスクリプションを更新します。

PATCH https://outlook.office.com/api/v2.0/me/subscriptions/{subscriptionId}

応答に特定のインスタンス プロパティを必要としないサブスクリプション要求では既定のサブスクリプション時間は 7 日であり、リッチ通知のサブスクリプションでは 1 日です。

ペイロードなしで更新要求を送信することができ、サブスクリプションは対応する最大期間だけ延長されます。

要求のサンプル

PATCH https://outlook.office.com/api/v2.0/me/subscriptions/Mjk3QNERDQQ==

{
   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   "SubscriptionExpirationDateTime": "2015-05-28T17:17:45.9028722Z"
}

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

サブスクリプションを削除する

サブスクリプション ID を指定して、サブスクリプションを削除します。

DELETE https://outlook.office.com/api/beta/me/subscriptions('{subscriptionId}')

要求のサンプル

Delete https://outlook.office.com/api/beta/me/subscriptions('Mjk3QNERDQQ==')

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

サブスクリプション ID を指定して、サブスクリプションを削除します。

DELETE https://outlook.office.com/api/v2.0/me/subscriptions('{subscriptionId}')

要求のサンプル

Delete https://outlook.office.com/api/v2.0/me/subscriptions('Mjk3QNERDQQ==')

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

通知 API エンティティと列挙型

Subscription

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

基本型:Entity

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

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

基本型:Entity

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

Notification

クライアントに送られる通知を表します。プッシュ通知の場合、通知はクライアントで指定されたリスナー サービスに送られます。

基本型:Entity

プロパティ説明書き込み可能フィルター処理可能
SubscriptionIdstringサブスクリプションの一意の識別子です。いいえいいえ
SubscriptionExpirationDateTimeEdm.DateTimeOffset通知サブスクリプションの有効期限が切れる日時を指定します。時刻は UTC です。はい該当なし
SequenceNumberint32変更通知のシーケンス値を示します。いいえ該当なし
ChangeTypeChangeType通知を発生させたイベントの種類を示します。列挙値は次のとおりです。作成 =1、更新=2、削除=4、失敗=16。通知の失敗は、通知サービスが要求された通知を送信できない場合に発生します。いいえ該当なし
Resourcestring変更の監視対象となっているリソース アイテムを指定します。はい該当なし
ResourceDataEntity変更されたエンティティを識別します。これはナビゲーションのプロパティです。いいえ該当なし

クライアントに送られる通知を表します。プッシュ通知の場合、通知はクライアントで指定されたリスナー サービスに送られます。

基本型:Entity

プロパティ説明書き込み可能フィルター処理可能
SubscriptionIdstringサブスクリプションの一意の識別子です。いいえいいえ
SubscriptionExpirationDateTimeEdm.DateTimeOffset通知サブスクリプションの有効期限が切れる日時を指定します。時刻は UTC です。はい該当なし
SequenceNumberint32変更通知のシーケンス値を示します。いいえ該当なし
ChangeTypeChangeType通知を発生させたイベントの種類を示します。列挙値は次のとおりです。作成 =1、更新=2、削除=4、失敗=16。通知の失敗は、通知サービスが要求された通知を送信できない場合に発生します。いいえ該当なし
Resourcestring変更の監視対象となっているリソース アイテムを指定します。はい該当なし
ResourceDataEntity変更されたエンティティを識別します。これはナビゲーションのプロパティです。いいえ該当なし

PushSubscription

プッシュ通知の機構を使用するサブスクリプションを表します。

基本型:Subscription

プロパティ説明書き込み可能フィルター処理可能
NotificationURLstringプッシュ通知を受け取るアプリケーションの URL です。はい該当なし
SubscriptionExpirationDateTimeEdm.DateTimeOffset通知サブスクリプションの有効期限が切れる日時を指定します。時刻は UTC です。はい該当なし
ClientStatestring通知ごとにサービスによって送信される ClientState ヘッダーの値を指定します。最大の長さは 255 文字です。クライアントはサービスから通知が送られたことを確認できます。これは、ClientState プロパティに設定されている値と、各通知と共に受信された ClientState ヘッダーの値を比較することによって行います。はいいいえ

プッシュ通知の機構を使用するサブスクリプションを表します。

基本型:Subscription

プロパティ説明書き込み可能フィルター処理可能
NotificationURLstringプッシュ通知を受け取るアプリケーションの URL です。はい該当なし
SubscriptionExpirationDateTimeEdm.DateTimeOffset通知サブスクリプションの有効期限が切れる日時を指定します。時刻は UTC です。はい該当なし
ClientStatestring通知ごとにサービスによって送信される ClientState ヘッダーの値を指定します。最大の長さは 255 文字です。クライアントはサービスから通知が送られたことを確認できます。これは、ClientState プロパティに設定されている値と、各通知と共に受信された ClientState ヘッダーの値を比較することによって行います。はいいいえ

<a "name"="ChangeType">

ChangeType

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

サポートされている値:

  • Acknowledgment
  • Created
  • Deleted
  • Missed。 Missed 通知は、通知サービスが要求された通知を送信できない場合に発生します。
  • Updated

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

サポートされている値:

  • Acknowledgment
  • Created
  • Deleted
  • Missed。 Missed 通知は、通知サービスが要求された通知を送信できない場合に発生します。
  • Updated

次のステップ

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

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

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

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

© 2018 Microsoft