サブスクリプションを作成するCreate subscription

変更の要求された種類が Microsoft Graph の指定されたリソースに発生したときに通知を受信するため、リスナー アプリケーションに登録します。Subscribes a listener application to receive notifications when the requested type of changes occur to the specified resource in Microsoft Graph.

アクセス許可Permissions

サブスクリプションを作成するにはリソースへの読み取りスコープが必要です。Creating a subscription requires read scope to the resource. たとえば、メッセージに関する通知を受信するには、アプリに Mail.Read アクセス許可が必要です。For example, to get notifications on messages, your app needs the Mail.Read permission.

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

サポートされているリソースSupported resource 委任 (職場または学校のアカウント)Delegated (work or school account) 委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) アプリケーションApplication
連絡先contact Contacts.ReadContacts.Read Contacts.ReadContacts.Read Contacts.ReadContacts.Read
driveItem (ユーザーの個人用 OneDrive)driveItem (user's personal OneDrive) サポート対象外Not supported Files.ReadWriteFiles.ReadWrite サポート対象外Not supported
driveItem (OneDrive for Business)driveItem (OneDrive for Business) Files.ReadWrite.AllFiles.ReadWrite.All サポート対象外Not supported Files.ReadWrite.AllFiles.ReadWrite.All
イベントevent Calendars.ReadCalendars.Read Calendars.ReadCalendars.Read Calendars.ReadCalendars.Read
グループgroup Group.Read.AllGroup.Read.All サポート対象外Not supported Group.Read.AllGroup.Read.All
グループ会話group conversation Group.Read.AllGroup.Read.All サポート対象外Not supported サポート対象外Not supported
messagemessage Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read
セキュリティの警告security alert SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All サポート対象外Not supported SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All
ユーザーuser User.Read.AllUser.Read.All User.Read.AllUser.Read.All User.Read.AllUser.Read.All

注: OneDrive と Outlook のアイテムのサブスクリプションについては、追加の制限があります。Note: There are additional limitations for subscriptions on OneDrive and Outlook items. この制限は、サブスクリプションの作成および管理 (サブスクリプションの取得、更新、削除) に適用されます。The limitations apply to creating as well as managing subscriptions (getting, updating, and deleting subscriptions).

  • 個人用 OneDrive では、そのドライブのルート フォルダーまたは任意のサブフォルダーにサブスクライブできます。On personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. OneDrive for Business の場合、サブスクライブできるのはルート フォルダーのみです。On OneDrive for Business, you can subscribe to only the root folder. サブスクライブしたフォルダー、または階層内の任意のファイル、フォルダー、あるいは他の driveItem インスタンスに関する変更の要求された種類についての通知が送信されます。Notifications are sent for the requested types of changes on the subscribed folder, or any file, folder, or other driveItem instances in its hierarchy. 個別のファイルなどのフォルダーではない、ドライブ インスタンスまたは driveItem インスタンスをサブスクライブすることはできません。You cannot subscribe to drive or driveItem instances that are not folders, such as individual files.

  • Outlook における委任されたアクセス許可では、サインインしているユーザーのメールボックス内のフォルダーにあるアイテムのみをサブスクライブできます。In Outlook, delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. つまり、委任されたアクセス許可 Calendars.Read を使用して、別のユーザーのメールボックス内のイベントをサブスクライブすることなどはできません。That means, for example, you cannot use the delegated permission Calendars.Read to subscribe to events in another user’s mailbox.

  • _共有または委任_フォルダーの Outlook 連絡先、イベント、メッセージの変更通知をサブスクライブするには、次のようにします。To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:

    • 対応するアプリケーション アクセス許可を使用して、テナントの_任意_のユーザーのフォルダーまたはメールボックス内にあるアイテムの変更をサブスクライブします。Use the corresponding application permission to subscribe to changes of items in a folder or mailbox of any user in the tenant.
    • Outlook 共有アクセス許可 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared、および対応する読み取り/書き込み) は使用しないでください。それらは、共有フォルダーまたは委任フォルダーにあるアイテムの変更通知のサブスクライブをサポートしていないからです。Do not use the Outlook sharing permissions (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared, and their read/write counterparts), as they do not support subscribing to change notifications on items in shared or delegated folders.

HTTP 要求HTTP request

POST /subscriptions

要求ヘッダーRequest headers

名前Name 種類Type 説明Description
AuthorizationAuthorization stringstring ベアラー {トークン}。必須。Bearer {token}. Required.

応答Response

成功した場合、このメソッドは 201 Created 応答コードと、応答本文に入った subscription オブジェクトを返します。If successful, this method returns 201 Created response code and a subscription object in the response body.

Example

要求Request

ユーザーが新しいメールを受信したときに通知を送信する要求の例を次に示します。Here is an example of the request to send a notification when the user receives a new mail.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
   "changeType": "updated",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue"
}

要求本文で、subscription オブジェクトの JSON 表記を指定します。In the request body, supply a JSON representation of the subscription object. clientState フィールドは省略可能です。The clientState field is optional.

リソースの例Resources examples

以下は、サブスクリプションのリソース プロパティの有効な値です。The following are valid values for the resource property of the subscription:

リソースの種類Resource type Examples
メールMail me/mailfolders('inbox')/messagesme/mailfolders('inbox')/messages
me/messagesme/messages
連絡先Contacts me/contactsme/contacts
カレンダーCalendars me/eventsme/events
ユーザーUsers usersusers
グループGroups groupsgroups
会話Conversations groups('{id}')/conversationsgroups('{id}')/conversations
ドライブDrives me/drive/rootme/drive/root
セキュリティの警告Security alert security/alerts?$filter=status eq ‘New’security/alerts?$filter=status eq ‘New’
応答Response

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

HTTP/1.1 201 Created
Content-type: application/json
Content-length: 252

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "updated",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437"
}

通知エンドポイントの検証Notification endpoint validation

サブスクリプションの通知のエンドポイントは (notificationUrl プロパティで指定されている)、「ユーザー データの変更に関する通知の設定」での説明にあるように、検証依頼に応答できなければなりません。The subscription notification endpoint (specified in the notificationUrl property) must be capable of responding to a validation request as described in Set up notifications for changes in user data. 検証に失敗した場合、サブスクリプションを作成する要求は「400 要求が正しくありません」というエラーを返します。If validation fails, the request to create the subscription returns a 400 Bad Request error.