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

名前空間: microsoft.graphNamespace: microsoft.graph

重要

/betaMicrosoft Graph のバージョンの api は変更される可能性があります。APIs under the /beta version in Microsoft Graph are subject to change. 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。Use of these APIs in production applications is not supported. API が v2.0 で利用できるかどうかを確認するには、 バージョン セレクターを使用します。To determine whether an API is available in v1.0, use the Version selector.

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

アクセス許可Permissions

サブスクリプションを作成するには、リソースに対する読み取りアクセス許可が必要です。Creating a subscription requires read permission to the resource. たとえば、メッセージの変更通知を取得するには、アプリにはメールの読み取りアクセス許可が必要です。For example, to get change 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
callRecord (/communications/callRecords)callRecord (/communications/callRecords) 非サポートNot supported 非サポートNot supported CallRecords.Read.AllCallRecords.Read.All
chatMessage (/teams/{id}/channels/{id}/messages)chatMessage (/teams/{id}/channels/{id}/messages) ChannelMessage.Read.All、Group.Read.All、Group.ReadWrite.AllChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All 非サポートNot supported ChannelMessage. Group *, ChannelMessage. AllChannelMessage.Read.Group*, ChannelMessage.Read.All
chatMessage (/teams/getAllMessages -- all channel messages in organization)chatMessage (/teams/getAllMessages -- all channel messages in organization) 非サポートNot supported 非サポートNot supported ChannelMessage.Read.AllChannelMessage.Read.All
chatMessage (/chats/{id}/messages)chatMessage (/chats/{id}/messages) Chat.Read、Chat.ReadWriteChat.Read, Chat.ReadWrite 非サポートNot supported Chat.Read.AllChat.Read.All
chatMessage (/chats/getAllMessages -- all chat messages in organization)chatMessage (/chats/getAllMessages -- all chat messages in organization) 非サポートNot supported 非サポートNot supported Chat.Read.AllChat.Read.All
contactcontact 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
リストlist Sites.ReadWrite.AllSites.ReadWrite.All サポート対象外Not supported Sites.ReadWrite.AllSites.ReadWrite.All
メッセージmessage Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read
プレゼンスpresence Presence.Read.AllPresence.Read.All サポート対象外Not supported 非サポートNot supported
printTaskDefinitionprintTaskDefinition 非サポートNot supported 非サポートNot supported PrintTaskDefinition.ReadWrite.AllPrintTaskDefinition.ReadWrite.All
セキュリティの警告security alert SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All サポート対象外Not supported SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All
todoTasktodoTask Tasks.ReadWriteTasks.ReadWrite Tasks.ReadWriteTasks.ReadWrite 非サポートNot supported
ユーザーuser User.Read.AllUser.Read.All User.Read.AllUser.Read.All User.Read.AllUser.Read.All

: * でマークされた権限は、リソース固有の同意を使用します。Note: Permissions marked with * use resource-specific consent.

chatMessagechatMessage

[委任されたアクセス許可を持つ メッセージ サブスクリプションは、リソースデータをサポートしていません (この データ は必須である必要があり false ます)。また、暗号化は必要ありません。chatMessage subscriptions with delegated permissions do not support resource data (includeResourceData must be false), and do not require encryption.

アプリケーションへのアクセス許可を持つ chatMessage サブスクリプションにはリソース データが含まれており、暗号化が必要です。chatMessage subscriptions with application permissions include resource data, and require encryption. encryptionCertificate が指定されていない場合、サブスクリプションの作成は失敗します。Subscription creation will fail if encryptionCertificate is not specified. chatMessage サブスクリプションを作成する前に、アクセスを要求する必要があります。Before creating a chatMessage subscription, you must request access. 詳細については、「Microsoft Teams の保護された API」を参照してください。For details, see Protected APIs in Microsoft Teams.

注: /teams/getAllMessages および /chats/getAllMessages は、必要なライセンスを持つユーザーが利用できます。Note: /teams/getAllMessages and /chats/getAllMessages are available to users that have the required licenses.

注: /chats/getAllMessages テナントが所有するチャットからのメッセージのみを返します。Note: /chats/getAllMessages only returns messages from chats owned by the tenant. チャットスレッドがテナント外部のユーザーによって開始された場合、そのチャットスレッドはテナントによって所有されず、変更通知は作成されません。If a chat thread is initiated by a user outside the tenant, that chat thread is not owned by the tenant, and does not create change notifications.

driveItemdriveItem

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

個人用 OneDrive では、そのドライブのルート フォルダーまたは任意のサブフォルダーにサブスクライブできます。On a 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 インスタンスに関する変更の要求された種類についての変更通知が送信されます。Change 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.

連絡先、イベント、メッセージcontact, event, and message

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

  • 委任されたアクセス許可では、サインインしているユーザーのメールボックス内のフォルダーにあるアイテムのみをサブスクライブできます。Delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. 委任されたアクセス許可 Calendars.Read を使用して、別のユーザーのメールボックス内のイベントをサブスクライブすることなどはできません。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.

プレゼンスpresence

プレゼンス サブスクリプションは 暗号化を必要とします。presence subscriptions require encryption. encryptionCertificate が指定されていない場合、サブスクリプションの作成は失敗します。Subscription creation will fail if encryptionCertificate is not specified.

HTTP 要求HTTP request

POST /subscriptions

要求ヘッダーRequest headers

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

応答Response

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

エラーがどのように返されるかの詳細については、「エラー応答」を参照してください。For details about how errors are returned, see Error responses.

Example

要求Request

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

この要求は、現在サインインしているユーザーが受信した新しいメールに関する変更通知のサブスクリプションを作成します。This request creates a subscription for change notifications about new mail received by the currently signed in user.

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

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

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

リソースの例Resources examples

Resource プロパティの有効な値は次のとおりです。The following are valid values for the resource property.

リソースの種類Resource type Examples
通話レコードCall records communications/callRecords
チャット メッセージChat message chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessageschats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages
連絡先Contacts me/contacts
会話Conversations groups('{id}')/conversations
ドライブDrives me/drive/root
イベントEvents me/events
グループGroups groups
リストList sites/{site-id}/lists/{list-id}
メールMail me/mailfolders('inbox')/messages, me/messagesme/mailfolders('inbox')/messages, me/messages
置かPresence /communications/presences/{id} (1 人のユーザー) ( /communications/presences?$filter=id in ({id},{id}…) 複数のユーザー)/communications/presences/{id} (single user), /communications/presences?$filter=id in ({id},{id}…) (multiple users)
PrintTaskDefinitionPrintTaskDefinition print/taskDefinitions/{id}/tasks
UsersUsers users
todoTasktodoTask /me/todo/lists/{todoTaskListId}/tasks
セキュリティの警告Security alert security/alerts?$filter=status eq 'NewAlert'

注: me で始まるパスは、me ではなく users/{id} でも使用して、現在のユーザーではなく特定のユーザーをターゲットにすることができます。Note: Any path starting with me can also be used with users/{id} instead of me to target a specific user instead of the current user.

応答Response

次の例は応答を示しています。The following example shows the response.

注: 読みやすくするために、ここに示す応答オブジェクトは短くされている場合があります。実際の呼び出しからは、すべてのプロパティが返されます。Note: The response object shown here might be shortened for readability. All 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": "created",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2"
}

通知エンドポイントの検証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.