サブスクリプションを更新する
名前空間: microsoft.graph
重要
Microsoft Graph の /beta
バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
サブスクリプションを更新するには、サブスクリプションの有効期限を延長します。
[ アクセス許可 ] セクションの表に、変更通知のサブスクライブをサポートするリソースの一覧を示します。
サブスクリプションは、リソースの種類によって異なる長い時間が経過すると期限切れになります。 変更通知が見つからないのを防ぐために、アプリは有効期限の前にサブスクリプションを更新する必要があります。 各リソースの種類の サブスクリプション の最大長については、「サブスクリプション」を参照してください。
この API は、次の国内クラウド展開で使用できます。
グローバル サービス | 米国政府機関 L4 | 米国政府機関 L5 (DOD) | 21Vianet が運営する中国 |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
アクセス許可
要求されたリソースとアクセス許可の種類 (委任またはアプリケーション) に応じて、以下の表で指定されているアクセス許可がこの API を呼び出すため必要な最小限の特権となります。 より多くの特権アクセス許可を選択する前に注意することを含め、詳細については、[アクセス許可] で次のアクセス許可を検索してください。
注:
一部のリソースでは、複数のシナリオで変更通知がサポートされており、それぞれに異なるアクセス許可が必要な場合があります。 このような場合は、リソース パスを使用してシナリオを区別します。
サポートされているリソース | 委任 (職場または学校のアカウント) | 委任 (個人用 Microsoft アカウント) | アプリケーション |
---|---|---|---|
approvalItems | サポートされていません。 | サポートされていません。 | ApprovalSolution.ReadWrite.All |
callRecord | サポートされていません。 | サポートされていません。 | CallRecords.Read.All |
callRecording communications/onlineMeetings/getAllRecordings すべての記録がテナントで使用できるようになります。 |
サポートされていません。 | サポートされていません。 | 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 |
callRecording appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings 特定の Teams アプリがインストールされている会議で使用できる通話記録。 |
サポートされていません。 | サポートされていません。 | OnlineMeetingRecording.Read.All、OnlineMeetingRecording.Read.Chat |
callTranscript communications/onlineMeetings/getAllTranscripts すべてのトランスクリプトがテナントで使用できるようになります。 |
サポートされていません。 | サポートされていません。 | 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 |
callTranscript appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts 特定の Teams アプリがインストールされている会議で使用できる通話トランスクリプト。 |
サポートされていません。 | サポートされていません。 | OnlineMeetingTranscript.Read.All、OnlineMeetingTranscript.Read.Chat |
channel /teams/getAllChannels 組織内のすべてのチャネル。 |
サポートされていません。 | サポートされていません。 | Channel.ReadBasic.All、ChannelSettings.Read.All |
channel /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 アプリがインストールされている組織内のすべてのチャット。 |
サポートされていません。 | サポートされていません。 | Chat.ReadBasic.WhereInstalled、Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled |
チャット /users/{id}/chats 特定のユーザーが参加しているすべてのチャット。 |
Chat.ReadBasic、 Chat.Read、 Chat.ReadWrite | サポートされていません。 | Chat.ReadBasic.All、 Chat.Read.All、 Chat.ReadWrite.All |
chatMessage /teams/{id}/channels/{id}/messages 特定のチャネルのすべてのメッセージと応答。 |
ChannelMessage.Read.All、Group.Read.All、Group.ReadWrite.All | サポートされていません。 | ChannelMessage.Read.Group、ChannelMessage.Read.All |
chatMessage /teams/getAllMessages 組織内のすべてのチャネル メッセージ。 |
サポートされていません。 | サポートされていません。 | ChannelMessage.Read.All |
chatMessage /chats/{id}/messages チャット内のすべてのメッセージ。 |
Chat.Read、Chat.ReadWrite | サポートされていません。 | Chat.Read.All |
chatMessage /chats/getAllMessages 組織内のすべてのチャット メッセージ。 |
サポートされていません。 | サポートされていません。 | Chat.Read.All |
chatMessage /users/{id}/chats/getAllMessages 特定のユーザーが参加しているすべてのチャットに対するチャット メッセージ。 |
Chat.Read、Chat.ReadWrite | サポートされていません。 | Chat.Read.All、Chat.ReadWrite.All |
chatMessage /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages 特定の Teams アプリがインストールされている組織内のすべてのチャットのチャット メッセージ。 |
サポートされていません。 | サポートされていません。 | 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 アプリがインストールされている組織内のすべてのチャットのチャット メンバー。 |
サポートされていません。 | サポートされていません。 | ChatMember.Read.WhereInstalled、ChatMember.ReadWrite.WhereInstalled、Chat.ReadBasic.WhereInstalled、Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled |
conversationMember /teams/getAllMembers 組織内のすべてのチームのメンバー。 |
サポートされていません。 | サポートされていません。 | TeamMember.Read.All, TeamMember.ReadWrite.All |
conversationMember /teams/{id}/members 特定のチームのメンバー。 |
TeamMember.Read.All | サポートされていません。 | TeamMember.Read.All |
conversationMember /teams/{id}/channels/getAllMembers 特定のチームのすべてのプライベート チャネルのメンバー。 |
サポートされていません。 | サポートされていません。 | ChannelMember.Read.All |
conversationMember /teams/getAllChannels/getAllMembers |
サポートされていません。 | サポートされていません。 | ChannelMember.Read.All |
driveItem (ユーザーの個人用 OneDrive) | サポートされていません。 | Files.ReadWrite | サポートされていません。 |
driveItem (職場または学校用の OneDrive) | Files.ReadWrite.All | サポートされていません。 | Files.ReadWrite.All |
イベント | Calendars.Read | Calendars.Read | Calendars.Read |
グループ | Group.Read.All | サポートされていません。 | Group.Read.All |
グループ会話 | Group.Read.All | サポートされていません。 | サポートされていません。 |
リスト | Sites.ReadWrite.All | サポートされていません。 | Sites.ReadWrite.All |
メッセージ | 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 |
オンライン会議 | サポートされていません。 | サポートされていません。 | OnlineMeetings.Read.All、OnlineMeetings.ReadWrite.All |
openShiftChangeRequest /teams/{id}/schedule/openShiftChangeRequests チーム内のオープン シフト要求に対する変更。 |
Schedule.Read.All、Schedule.ReadWrite.All | サポートされていません。 | Schedule.Read.All、Schedule.ReadWrite.All |
プレゼンス | Presence.Read.All | サポートされていません。 | サポートされていません。 |
printer | サポートされていません。 | サポートされていません。 | 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 |
baseTask (非推奨) | Tasks.ReadWrite | Tasks.ReadWrite | サポートされていません。 |
注:
次のアクセス許可では 、リソース固有の同意が使用されます。
- OnlineMeetingRecording.Read.Chat
- OnlineMeetingTranscript.Read.Chat
- ChatSettings.Read.Chat
- ChatSettings.ReadWrite.Chat
- Chat.Manage.Chat
- ChannelMessage.Read.Group
- ChatMember.Read.Chat
chatMessage
chatMessage サブスクリプションは、リソース データを含めるように指定できます。 リソース データを含めるように指定した場合 (includeResourceData を true
に設定)、暗号化が必要です。 そのようなサブスクリプションに encryptionCertificate が指定されていない場合、サブスクリプションの作成は失敗します。
Prefer: include-unknown-enum-members
要求ヘッダーを使用して、chatMessagemessageTypeの進化可能な列挙型で次の値を取得する必要があります。/teams/{id}/channels/{id}/messages
リソースと/chats/{id}/messages
リソースのsystemEventMessage
。
注:
/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
、/appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
サポートmodel=B
のみをサポートします。
クエリで支払いモデルを指定しない場合は、既定の 評価モード が使用されます。
注:
変更通知のサブスクライブされたリソースの支払いモデルを追加または変更するには、新しい支払いモデルを使用して新しい変更通知サブスクリプションを作成する必要があります。既存の変更通知の更新は機能しません。
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 では、ルート フォルダーのみをサブスクライブできます。 変更通知は、サブスクライブされたフォルダー、またはその階層内の任意のファイル、フォルダー、またはその他の driveItem インスタンスに対して要求された変更に対して送信されます。 個々のファイルなど、フォルダーではない drive または driveItem インスタンスをサブスクライブすることはできません。
連絡先、イベント、メッセージ
Outlook の連絡先、 イベント、または メッセージ リソースの変更をサブスクライブし、必要に応じて POST 要求ペイロードに、暗号化されたリソース データを通知に含めるかどうかを指定できます。
サブスクリプションの作成と管理 (取得、更新、および削除) には、リソースの読み取りスコープが必要です。 たとえば、メッセージに関する変更通知を受信するには、アプリに Mail.Read アクセス許可が必要です。 Outlook 変更通知は、委任されたアクセス許可スコープとアプリケーション アクセス許可スコープをサポートします。 次の制限がある点に注意してください。
委任されたアクセス許可では、サインインしているユーザーのメールボックス内のフォルダーにあるアイテムのみをサブスクライブできます。 たとえば、委任されたアクセス許可 Calendars.Read を使用して、別のユーザーのメールボックス内のイベントをサブスクライブすることはできません。
共有または委任フォルダーの Outlook 連絡先、イベント、メッセージの変更通知をサブスクライブするには、次のようにします。
- 対応するアプリケーション アクセス許可を使用して、テナントの任意のユーザーのフォルダーまたはメールボックス内にあるアイテムの変更をサブスクライブします。
- Outlook 共有アクセス許可 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared、およびその読み取り/書き込みに対応するアクセス許可) は使用しないでください。これは、共有フォルダーまたは委任されたフォルダー内のアイテムに対する通知の変更のサブスクライブをサポート していないため です。
onlineMeetings, プレゼンス
onlineMeetings および プレゼンス サブスクリプションでは、リソース データを使用した通知の 暗号化 が必要です。 通知でリソース データが必要な場合に encryptionCertificate と encryptionCertificateId が 指定されていない場合、サブスクリプションの作成は失敗します。 プレゼンスとオンライン会議のサブスクリプションの詳細については、「 Microsoft Teamsでのプレゼンス更新の変更通知を取得 する」および「 オンライン会議の変更通知を取得する」を参照してください。
virtualEventWebinar
仮想イベントのサブスクリプションでは、基本的な通知のみがサポートされ、仮想イベントのいくつかのエンティティに制限されます。 サポートされているサブスクリプションの種類の詳細については、「 Microsoft Teams仮想イベントの更新に関する変更通知を取得する」を参照してください。
HTTP 要求
PATCH /subscriptions/{id}
要求ヘッダー
名前 | 型 | 説明 |
---|---|---|
Authorization | string | ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。 |
要求本文
要求本文で、更新すべきプロパティの値のみを指定します。 要求本文に含まれていない既存のプロパティは、以前の値を維持するか、他のプロパティ値の変更に基づいて再計算されます。
次の表に、更新できるプロパティを示します。
名前 | 型 | 説明 |
---|---|---|
expirationDateTime | DateTimeOffset | サブスクリプションの有効期限が切れる日時を UTC で指定します。 サポートされる最大サブスクリプションの場合、時間の長さはリソースによって異なります。 |
応答
成功した場合、このメソッドは 200 OK
応答コードと、応答本文で subscription オブジェクトを返します。
エラーがどのように返されるかの詳細については、「エラー応答」を参照してください。
例
要求
次の例は要求を示しています。
PATCH https://graph.microsoft.com/beta/subscriptions/{id}
Content-type: application/json
{
"expirationDateTime":"2016-11-22T18:23:45.9356913Z"
}
応答
次の例は応答を示しています。
HTTP/1.1 200 OK
Content-type: application/json
{
"id":"7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
"resource":"me/messages",
"applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
"changeType":"created,updated",
"clientState":"secretClientValue",
"notificationUrl":"https://webhook.azurewebsites.net/api/send/myNotifyClient",
"lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
"expirationDateTime":"2016-11-22T18:23:45.9356913Z",
"creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
"latestSupportedTlsVersion": "v1_2",
"encryptionCertificate": "",
"encryptionCertificateId": "",
"includeResourceData": false,
"notificationContentType": "application/json"
}