サブスクリプションを作成する
名前空間: microsoft.graph
変更の要求された種類が Microsoft Graph の指定されたリソースに発生したときに変更通知を受信するため、リスナー アプリケーションに登録します。
サブスクリプションを作成できるリソースとサブスクリプションの制限事項を特定するには、「 リソース データの変更に関する通知を設定する: サポートされているリソース」を参照してください。
一部のリソースでは、リッチ通知 、つまりリソース データを含む通知がサポートされています。 これらのリソースの詳細については、「 リソース データを含む変更通知を設定する: サポートされているリソース」を参照してください。
この API は、次の国内クラウド展開で使用できます。
グローバル サービス | 米国政府機関 L4 | 米国政府機関 L5 (DOD) | 21Vianet が運営する中国 |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
アクセス許可
サブスクリプションを作成するにはリソースへの読み取りスコープが必要です。 たとえば、メッセージに関する変更通知を受信するには、アプリに Mail.Read
アクセス許可が必要です。
要求されたリソースとアクセス許可の種類 (委任およびアプリケーション) によっては、以下の表で指定されているアクセス許可がこの API を呼び出すために最小限必要な特権となります。 より多くの特権アクセス許可を選択する前に 注意する ことを含め、詳細については、[アクセス許可] で次のアクセス許可を検索してください。
サポートされているリソース | 委任 (職場または学校のアカウント) | 委任 (個人用 Microsoft アカウント) | アプリケーション |
---|---|---|---|
callRecord (/communications/callRecords) | 非サポート | 非サポート | CallRecords.Read.All |
callRecording communications/onlineMeetings/getAllRecordings organization内のすべての録音。 |
サポートされていません。 | サポートされていません。 | OnlineMeetingRecording.Read.All |
callRecording communications/onlineMeetings/{onlineMeetingId}/recordings 特定の会議のすべての記録。 |
OnlineMeetingRecording.Read.All | サポートされていません。 | OnlineMeetingRecording.Read.All |
callRecording users/{userId}/onlineMeetings/getAllRecordings 特定のユーザーが開催した会議で使用可能になる通話記録。 |
OnlineMeetingRecording.Read.All | サポートされていません。 | OnlineMeetingRecording.Read.All |
callTranscript communications/onlineMeetings/getAllTranscripts organization内のすべてのトランスクリプト。 |
サポートされていません。 | サポートされていません。 | OnlineMeetingTranscript.Read.All |
callTranscript communications/onlineMeetings/{onlineMeetingId}/transcripts 特定の会議のすべてのトランスクリプト。 |
OnlineMeetingTranscript.Read.All | サポートされていません。 | OnlineMeetingTranscript.Read.All |
callTranscript users/{userId}/onlineMeetings/getAllTranscripts 特定のユーザーが開催した会議で使用できる通話トランスクリプト。 |
OnlineMeetingTranscript.Read.All | サポートされていません。 | OnlineMeetingTranscript.Read.All |
チャネル (/teams/getAllChannels – 組織内のすべてのチャネル) | 非サポート | 非サポート | Channel.ReadBasic.All、ChannelSettings.Read.All |
チャネル (/teams/{id}/channels) | Channel.ReadBasic.All、ChannelSettings.Read.All | 非サポート | Channel.ReadBasic.All、ChannelSettings.Read.All |
チャット (/chats – 組織内のすべてのチャット) | サポート対象外 | 非サポート | Chat.ReadBasic.All、 Chat.Read.All、 Chat.ReadWrite.All |
チャット (/chats/{id}) | Chat.ReadBasic、 Chat.Read、 Chat.ReadWrite | 非サポート | ChatSettings.Read.Chat*, ChatSettings.ReadWrite.Chat*, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
チャット /appCatalogs/teamsApps/{id}/installedToChats 特定の Teams アプリがインストールされているorganization内のすべてのチャット。 |
非サポート | 非サポート | Chat.ReadBasic.WhereInstalled、Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled |
chatMessage (/teams/{id}/channels/{id}/messages) | ChannelMessage.Read.All | 非サポート | ChannelMessage.Read.Group*、ChannelMessage.Read.All |
chatMessage (/teams/getAllMessages -- all channel messages in organization) | 非サポート | 非サポート | ChannelMessage.Read.All |
chatMessage (/chats/{id}/messages) | Chat.Read、Chat.ReadWrite | 非サポート | Chat.Read.All |
chatMessage (/chats/getAllMessages -- all chat messages in organization) | 非サポート | 非サポート | Chat.Read.All |
チャット メッセージ (/users/{id}/chats/getAllMessages -- 特定のユーザーが参加しているすべてのチャットのチャット メッセージ) | Chat.Read、Chat.ReadWrite | 非サポート | Chat.Read.All、Chat.ReadWrite.All |
chatMessage /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages 特定の Teams アプリがインストールされているorganization内のすべてのチャットのチャット メッセージ。 |
非サポート | 非サポート | Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled |
contact | Contacts.Read | Contacts.Read | Contacts.Read |
conversationMember (/chats/getAllMembers) | サポート対象外 | 非サポート | ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
conversationMember (/chats/{id}/members) | ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite | サポート対象外 | ChatMember.Read.Chat*, Chat.Manage.Chat*, ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
conversationMember /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers 特定の Teams アプリがインストールされているorganization内のすべてのチャットのチャット メンバー。 |
サポートされていません。 | サポートされていません。 | ChatMember.Read.WhereInstalled、ChatMember.ReadWrite.WhereInstalled、Chat.ReadBasic.WhereInstalled、Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled |
conversationMember (/teams/{id}/members) | TeamMember.Read.All | 非サポート | TeamMember.Read.All |
conversationMember (/teams/{id}/channels/getAllMembers) | サポート対象外 | 非サポート | ChannelMember.Read.All |
driveItem (ユーザーの個人用 OneDrive) | サポート対象外 | Files.Read | サポート対象外 |
driveItem (OneDrive for Business) | Files.Read.All | 非サポート | Files.Read.All |
event | Calendars.Read | Calendars.Read | Calendars.Read |
グループ | Group.Read.All | サポート対象外 | Group.Read.All |
グループ会話 | Group.Read.All | 非サポート | 非サポート |
リスト | Sites.Read.All | 非サポート | Sites.Read.All |
message | Mail.ReadBasic, Mail.Read | Mail.ReadBasic, Mail.Read | Mail.Read |
offerShiftRequest (/teams/{id}/schedule/offerShiftRequests) チーム内のオファー シフト要求に対する変更。 |
Schedule.Read.All、Schedule.ReadWrite.All | サポートされていません。 | Schedule.Read.All、Schedule.ReadWrite.All |
openShiftChangeRequest (/teams/{id}/schedule/openShiftChangeRequests) チーム内のオープン シフト要求に対する変更。 |
Schedule.Read.All、Schedule.ReadWrite.All | サポートされていません。 | Schedule.Read.All、Schedule.ReadWrite.All |
プレゼンス | Presence.Read.All | 非サポート | サポート対象外 |
プリンター | 非サポート | 非サポート | Printer.Read.All, Printer.ReadWrite.All |
printTaskDefinition | 非サポート | 非サポート | PrintTaskDefinition.ReadWrite.All |
セキュリティの警告 | SecurityEvents.ReadWrite.All | サポート対象外 | SecurityEvents.ReadWrite.All |
シフト (/teams/{id}/schedule/shifts) チーム内の任意のシフトに対する変更。 |
Schedule.Read.All、Schedule.ReadWrite.All | サポートされていません。 | Schedule.Read.All、Schedule.ReadWrite.All |
swapShiftsChangeRequest (/teams/{id}/schedule/swapShiftsChangeRequests) チーム内のスワップ シフト要求に対する変更。 |
Schedule.Read.All、Schedule.ReadWrite.All | サポートされていません。 | Schedule.Read.All、Schedule.ReadWrite.All |
team (/teams – 組織内のすべてのチーム) | 非サポート | サポート対象外 | Team.ReadBasic.All、TeamSettings.Read.All |
team (/teams/{id}) | Team.ReadBasic.All、TeamSettings.Read.All | 非サポート | Team.ReadBasic.All、TeamSettings.Read.All |
timeOffRequest (/teams/{id}/schedule/timeOffRequests) チーム内の任意の休暇要求に対する変更。 |
Schedule.Read.All、Schedule.ReadWrite.All | サポートされていません。 | Schedule.Read.All、Schedule.ReadWrite.All |
todoTask | Tasks.ReadWrite | Tasks.ReadWrite | 非サポート |
user | User.Read.All | User.Read.All | User.Read.All |
virtualEventWebinar | VirtualEvent.Read | サポートされていません。 | VirtualEvent.Read.All |
前の表に記載されているように、アクセス許可を使用することをお勧めします。 セキュリティの制限により、読み取りアクセス許可のみが必要な場合、Microsoft Graph サブスクリプションでは書き込みアクセス許可はサポートされません。
注: * でマークされた権限は、リソース固有の同意を使用します。
chatMessage
chatMessage サブスクリプションは、リソース データを含めるように指定できます。 リソース データを含めるように指定した場合 (includeResourceData を true
に設定)、暗号化が必要です。 そのようなサブスクリプションに encryptionCertificate が指定されていない場合、サブスクリプションの作成は失敗します。
要求ヘッダーを使用して、Prefer: include-unknown-enum-members
chatMessagemessageTypeの進化可能な列挙型systemEventMessage
の for と /chats/{id}/messages
resource で次の値を/teams/{id}/channels/{id}/messages
取得する必要があります。
注:
/teams/getAllMessages
、 /chats/getAllMessages
、 /me/chats/getAllMessages
、 /users/{id}/chats/getAllMessages
および /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
は従量制課金 API です。 支払いモデルとライセンス要件が 適用される場合があります。
/teams/getAllMessages
と /chats/getAllMessages
の両方model=A
のmodel=B
支払いモデル、、/me/chats/getAllMessages
/users/{id}/chats/getAllMessages
、および のみがサポートmodel=B
されます/appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
。
クエリで支払いモデルを指定しない場合は、既定の 評価モード が使用されます。
注:
変更通知のサブスクライブされたリソースの支払いモデルを追加または変更するには、新しい支払いモデルを使用して新しい変更通知サブスクリプションを作成する必要があります。既存の変更通知の更新は機能しません。
conversationMember
conversationMember サブスクリプションを指定して、リソース データを含めることができます。 リソース データを含めるように指定した場合 (includeResourceData を true
に設定)、暗号化が必要です。
encryptionCertificateが指定されていない場合、サブスクリプションの作成は失敗します。
注:
/teams/getAllMembers
、 /chats/getAllMembers
、および /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
は従量制課金 API です。 支払いモデルとライセンス要件が 適用される場合があります。
/teams/getAllMembers
と /chats/getAllMembers
支払いモデルの両方 model=A
を model=B
サポートします。
/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
は のみを model=B
サポートします。
クエリで支払いモデルを指定しない場合は、既定の 評価モード が使用されます。
注:
変更通知のサブスクライブされたリソースの支払いモデルを追加または変更するには、新しい支払いモデルを使用して新しい変更通知サブスクリプションを作成する必要があります。既存の変更通知の更新は機能しません。
チーム、チャネル、チャット
チーム、 チャネル、 チャット サブスクリプションを指定して、リソース データを含めることができます。 リソース データを含めるように指定した場合 (includeResourceData を true
に設定)、暗号化が必要です。
encryptionCertificateが指定されていない場合、サブスクリプションの作成は失敗します。
notifyOnUserSpecificProperties クエリ文字列パラメーターは、特定のチャットまたはユーザー レベルの変更をサブスクライブするときに使用できます。 サブスクリプションの作成時にクエリ文字列パラメーター notifyOnUserSpecificProperties を に true
設定すると、2 種類のペイロードがサブスクライバーに送信されます。 1 つの型にはユーザー固有のプロパティが含まれており、もう 1 つの型はユーザー固有のプロパティなしで送信されます。 詳細については、「 Microsoft Graph を使用してチャットの変更通知を取得する」を参照してください。
注:
/appCatalogs/teamsApps/{id}/installedToChats
には 、ライセンスと支払いの要件があり、特に のみを model=B
サポートしています。
モデルが指定されていない場合は、評価モードが使用されます。
注:
変更通知のサブスクライブされたリソースの支払いモデルを追加または変更するには、新しい支払いモデルを使用して新しい変更通知サブスクリプションを作成する必要があります。既存の変更通知の更新は機能しません。
要求の例
要求本文の リソース プロパティで、model
クエリ パラメーターを指定します。
POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
"changeType": "created",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"resource": "chats/getAllMessages?model=A",
"expirationDateTime":"2016-11-20T18:23:45.9356913Z",
"clientState": "secretClientValue",
"latestSupportedTlsVersion": "v1_2"
}
driveItem
OneDrive アイテムのサブスクリプションには追加の制限が適用されます。 この制限は、サブスクリプションの作成および管理 (取得、更新、削除) に適用されます。
個人用 OneDrive では、そのドライブのルート フォルダーまたは任意のサブフォルダーにサブスクライブできます。 OneDrive for Business の場合、サブスクライブできるのはルート フォルダーのみです。 サブスクライブしたフォルダー、または階層内の任意のファイル、フォルダー、あるいは他の driveItem インスタンスに関する変更の要求された種類についての変更通知が送信されます。 個々のファイルなど、フォルダーではない drive または driveItem インスタンスをサブスクライブすることはできません。
OneDrive for Business と SharePoint は、driveItem で発生するセキュリティ イベントのアプリケーション通知の送信をサポートします。 これらのイベントをサブスクライブするには、prefer:includesecuritywebhooks
ヘッダーを要求に追加してサブスクリプションを作成します。 サブスクリプションが作成された後、アイテムに対するアクセス許可が変更されたときに通知を受け取ります。 このヘッダーは、SharePoint と OneDrive for Business には適用できますが、コンシューマー向け OneDrive アカウントには適用できません。
連絡先、イベント、メッセージ
Outlook の 連絡先、イベント、または メッセージ リソースの変更にサブスクライブできます。
サブスクリプションの作成と管理 (取得、更新、および削除) には、リソースの読み取りスコープが必要です。 たとえば、メッセージに関する変更通知を受信するには、アプリに Mail.Read アクセス許可が必要です。 Outlook 変更通知は、委任されたアクセス許可スコープとアプリケーション アクセス許可スコープをサポートします。 次の制限がある点に注意してください。
委任されたアクセス許可では、サインインしているユーザーのメールボックス内のフォルダーにあるアイテムのみをサブスクライブできます。 たとえば、委任されたアクセス許可 Calendars.Read を使用して、別のユーザーのメールボックス内のイベントをサブスクライブすることはできません。
共有または委任フォルダーの Outlook 連絡先、イベント、メッセージの変更通知をサブスクライブするには、次のようにします。
- 対応するアプリケーション アクセス許可を使用して、テナントの任意のユーザーのフォルダーまたはメールボックス内にあるアイテムの変更をサブスクライブします。
- Outlook 共有アクセス許可 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared、およびその読み取り/書き込みに対応するアクセス許可) は使用しないでください。これは、共有フォルダーまたは委任されたフォルダー内のアイテムに対する通知の変更のサブスクライブをサポート していないため です。
プレゼンス
プレゼンス でのサブスクリプションには、変更通知に含まれるリソース データが暗号化されている必要があります。 サブスクリプションを作成 する場合は、常に encryptionCertificate パラメーターを指定してエラーを回避します。 リソース データが含まれる変更通知を設定する を参照してください。
virtualEventWebinar
仮想イベントのサブスクリプションでは、基本的な通知のみがサポートされ、仮想イベントのいくつかのエンティティに制限されます。 サポートされているサブスクリプションの種類の詳細については、「 Microsoft Teams仮想イベントの更新に関する変更通知を取得する」を参照してください。
HTTP 要求
POST /subscriptions
要求ヘッダー
名前 | 型 | 説明 |
---|---|---|
Authorization | string | ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。 |
要求本文
要求本文で、subscription オブジェクトの JSON 表記を指定します。
応答
成功した場合、このメソッドは 201 Created
応答コードと、応答本文に入った subscription オブジェクトを返します。
エラーがどのように返されるかの詳細については、「エラー応答」を参照してください。
例
要求
次の例は、ユーザーが新しいメールを受信したときに変更通知を送信する要求を示しています。
POST https://graph.microsoft.com/v1.0/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 表記を指定します。
clientState
と latestSupportedTlsVersion
フィールドは省略可能です。
重複するサブスクリプションの動作
重複するサブスクリプションは許可されません。 サブスクリプション要求に、既存のサブスクリプションに含まれている changeType と リソース に同じ値が含まれている場合、要求は HTTP エラー コード 409 Conflict
、およびエラー メッセージ Subscription Id <> already exists for the requested combination
で失敗します。
リソースの例
以下は、サブスクリプションのリソース プロパティの有効な値です。
リソースの種類 | 例 |
---|---|
通話レコード | communications/callRecords |
callRecording |
communications/onlineMeetings/getAllRecordings , communications/onlineMeetings/{onlineMeetingId}/recordings , users/{userId}/onlineMeetings/getAllRecordings |
callTranscript |
communications/onlineMeetings/getAllTranscripts , communications/onlineMeetings/{onlineMeetingId}/transcripts , users/{userId}/onlineMeetings/getAllTranscripts |
チャット メッセージ |
chats/{id}/messages , chats/getAllMessages , teams/{id}/channels/{id}/messages , teams/getAllMessages |
連絡先 | me/contacts |
会話 | groups('{id}')/conversations |
ドライブ | me/drive/root |
イベント | me/events |
グループ | groups |
リスト | sites/{site-id}/lists/{list-id} |
メール |
me/mailfolders('inbox')/messages , me/messages |
プレゼンス |
/communications/presences/{id} (単一ユーザー)、/communications/presences?$filter=id in ('{id}','{id}',…) (複数のユーザー) |
プリンター | print/printers/{id}/jobs |
printTaskDefinition | print/taskDefinitions/{id}/tasks |
セキュリティの警告 | security/alerts?$filter=status eq 'New' |
todoTask | /me/todo/lists/{todoTaskListId}/tasks |
ユーザー | users |
注:
me
で始まるパスは、me
ではなくusers/{id}
でも使用して、現在のユーザーではなく特定のユーザーをターゲットにすることができます。
応答
次の例は応答を示しています。
注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$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",
"notificationContentType": "application/json"
}
通知エンドポイントの検証
サブスクリプションの通知のエンドポイントは (notificationUrl
プロパティで指定されている)、「ユーザー データの変更に関する通知の設定」での説明にあるように、検証依頼に応答できなければなりません。 検証に失敗した場合、サブスクリプションを作成する要求は「400 要求が正しくありません」というエラーを返します。