名前空間: microsoft.graph
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
注意
この機能を baseTask または baseTaskList と共に使用する既存のアプリは、これらのリソースに基づいて構築された To Do API セットが 2022 年 5 月 31 日に非推奨になったので、更新する必要があります。 その API セットは、2022 年 8 月 31 日にデータを戻すことを停止します。 todoTask 上に構築された API セットを使用してください。
クライアント アプリが Microsoft Graph のデータに対する変更に関する 変更通知を 受け取るサブスクリプションを表します。
変更通知をサポートするリソースなど、サブスクリプションと変更通知の詳細については、「 リソース データの変更に関する通知を設定する」を参照してください。
メソッド
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| List | subscription | アクティブなサブスクリプションを一覧表示します。 |
| Create | subscription | リスナー アプリケーションをサブスクライブして、Microsoft Graph データが変更されたときに変更通知を受け取ります。 susbcription が作成され、正常に評価されると、Microsoft Graph は、サブスクライブされたリソースに変更があるたびに、少なくとも 1 つの changeNotificationCollection オブジェクトをアプリに送信します。 |
| Get | subscription | サブスクリプション オブジェクトのプロパティとリレーションシップを読み取ります。 |
| Update | subscription | 有効期限を更新してサブスクリプションを更新します。 |
| 削除 | なし | サブスクリプション オブジェクトを削除します。 |
| 再認証 | なし | 再認証 Required チャレンジを受け取ったときにサブスクリプションを再認証します。 |
| VAPID を取得する | 文字列 | RFC8292に従ってサブスクリプションを作成するために使用する任意のアプリケーション サーバー識別 (VAPID) 公開キーを取得します。 |
プロパティ
| プロパティ | 型 | 説明 |
|---|---|---|
| applicationId | String | 省略可能。 サブスクリプションを作成するときに使用するアプリケーションの識別子。 読み取り専用です。 |
| changeType | String | 必須です。 変更通知を発生させるサブスクライブされたリソースの変更の種類を示します。 サポートされている値は created、updated、deleted です。 コンマ区切りのリストを使用して複数値を結合できます。 注: |
| clientState | String | 省略可能。 各変更通知でサービスによって送信される clientState プロパティの値を指定します。 最大の長さは、255 文字です。 クライアントは、サブスクリプションで送信された clientState プロパティの値と、各変更通知で受信した clientState プロパティの値を比較することで、変更通知がサービスから送信されたことをチェックできます。 |
| creatorId | String | 省略可能。 サブスクリプションを作成したユーザーまたはサービス プリンシパルの識別子。 アプリが委任されたアクセス許可を使用してサブスクリプションを作成した場合、このフィールドには、アプリの代わりに呼び出されたサインイン ユーザーの ID が含まれます。 アプリがアプリケーションのアクセス許可を使用している場合、このフィールドにはアプリに対応するサービス プリンシパルの ID が含まれます。 読み取り専用です。 |
| encryptionCertificate | 文字列 | 省略可能。 変更通知のリソース データを暗号化するために使用される公開キーを持つ証明書の base64 エンコード表現。 省略可能ですが、includeResourceData が true の場合は必須です。 |
| encryptionCertificateId | String | 省略可能。 リソース データを復号化するために必要な証明書を識別するのに役立つカスタム アプリ提供の識別子。
includeResourceData がtrueされている場合は必須です。 |
| expirationDateTime | DateTimeOffset | 必須です。 webhook サブスクリプションの有効期限が切れる日時を指定します。 時刻は UTC 表示で、登録したリソースごとに異なるサブスクリプション作成からの経過時間にもできます。 要求時刻の 45 分後の値は、要求時間の 45 分後に自動的に設定されます。 サポートされているサブスクリプションの最大期間については、「 サブスクリプションの有効期間」を参照してください。 |
| id | String | 省略可能。 サブスクリプションの一意の識別子です。 読み取り専用。 |
| includeResourceData | ブール値 | 省略可能。
true に設定すると、変更通知にはリソース データが含まれます (チャット メッセージのコンテンツなど)。 |
| latestSupportedTlsVersion | String | 省略可能。
notificationUrl で指定された通知エンドポイントがサポートするトランスポート層セキュリティ (TLS) の最新バージョンを指定します。 使用可能な値: v1_0、v1_1、v1_2、v1_3。
通知エンドポイントが現在推奨されているバージョン (TLS 1.2) より低いバージョンをサポートしているサブスクライバーの場合、セット タイムラインでこのプロパティを指定すると、TLS 1.2 へのアップグレードを完了する前に、非推奨バージョンの TLS を一時的に使用できます。 これらのサブスクライバーの場合、タイムラインごとにこのプロパティを設定しないと、サブスクリプション操作は失敗します。 通知エンドポイントが TLS 1.2 を既にサポートしているサブスクライバーの場合、このプロパティの設定は省略可能です。 このような場合、Microsoft Graph の既定では、プロパティが [ v1_2] になります。 |
| lifecycleNotificationUrl | String |
expirationDateTimeの値が 1 時間を超える場合は Teams リソースに必要です。それ以外の場合は省略可能です。
subscriptionRemoved、reauthorizationRequired、missed通知など、ライフサイクル通知を受信するエンドポイントの URL。 この URL は HTTPS プロトコルを利用する必要があります。 詳細については、「 不足しているサブスクリプションを減らし、通知を変更する」を参照してください。 |
| notificationContentType | 文字列 | 省略可能。 サポートされているリソースの種類に対して必要な Microsoft Graph 変更通知のコンテンツ タイプ。 既定のコンテンツ タイプは application/json です。 |
| notificationQueryOptions | String | 省略可能。 ターゲット リソースの値を指定するための OData クエリ オプション。 クライアントは、リソースがここで指定したクエリ オプションに一致する状態に達すると通知を受け取ります。 サブスクリプション作成ペイロード内のこの新しいプロパティと既存のすべてのプロパティを使用すると、リソースが notificationQueryOptions プロパティに記載されている目的の状態に達するたびに通知が配信されます。 たとえば、印刷ジョブが完了した場合や、印刷ジョブ リソースプロパティ isFetchable プロパティ値が true などになる場合です。 ユニバーサル プリント サービスでのみサポートされます。 詳細については、「 Microsoft Graph を使用してクラウド印刷 API からの変更通知をサブスクライブする」を参照してください。 |
| notificationUrl | 文字列 | 必須です。 変更通知を受け取るエンドポイントの URL。 この URL は HTTPS プロトコルを利用する必要があります。 notificationUrl プロパティに含まれるクエリ文字列パラメーターは、Microsoft Graph が変更通知を送信するときに HTTP POST 要求に含まれます。 |
| notificationUrlAppId | String | 省略可能。 サブスクリプション サービスが検証トークンの生成に使用できるアプリ ID。 値を使用すると、クライアントは受信した通知の信頼性を検証できます。 |
| resource | String | 必須です。 変更を監視するリソースを指定します。 ベース URL (https://graph.microsoft.com/beta/) は含めないでください。 サポートされているリソースについては、考えられるリソース パスの値を参照してください。 |
サブスクリプション ライフタイム
サブスクリプションのライフタイムには制限があります。 アプリは、有効期限が切れる前にサブスクリプションを更新する必要があります。それ以外の場合は、新しいサブスクリプションを作成する必要があります。 また、アプリはいつでも登録を解除して、変更通知の受信を停止できます。
さらに、expirationDateTime を要求時刻の 45 分以下に設定した要求は、要求時刻の 45 分後に自動的に設定されます。
次の表は、Microsoft Graph のリソースあたりのサブスクリプションの最大有効期限を示しています。
| Resource | 最大有効期限 |
|---|---|
| Copilot aiInteraction | 4,320 分 (3 日間) |
| セキュリティの警告 | 43,200 分 (30 日以内) |
| Teams の承認 | 43,200 分 (30 日以内) |
| Teams callRecord | 4,230 分 (3 日以内) |
| Teams callRecording | 4,320 分 (3 日間) |
| Teams callTranscript | 4,320 分 (3 日間) |
| Teams チャネル | 4,320 分 (3 日間) |
| Teams チャット | 4,320 分 (3 日間) |
| Teams chatMessage | 4,320 分 (3 日間) |
| Teams conversationMember | 4,320 分 (3 日間) |
| Teams onlineMeeting | 4,320 分 (3 日間) |
| Teams チーム | 4,320 分 (3 日間) |
| Teams teamsAppInstallation | 4,320 分 (3 日間) |
| Teams Shifts オファーShiftRequest | 360 分 (6 時間) |
| Teams Shifts openShiftChangeRequest | 360 分 (6 時間) |
| Teams Shifts シフト | 360 分 (6 時間) |
| Teams Shifts swapShiftsChangeRequest | 360 分 (6 時間) |
| Teams Shifts timeOffRequest | 360 分 (6 時間) |
| グループ会話 | 4,230 分 (3 日以内) |
| OneDrive driveItem | 42,300 分 (30 日以内) |
| SharePoint リスト | 42,300 分 (30 日以内) |
| Outlook メッセージ、イベント、連絡先 | 10,080 分 (7 日以内) リソース データを含むサブスクリプション (リッチ通知サブスクリプション) の場合、サブスクリプションの有効期間は 1440 分 (1 日以下) です。 |
| ユーザー、グループ、その他のディレクトリ リソース | 41,760 分 (29 日以内) |
| オンライン会議 | 4,230 分 (3 日以内) |
| プレゼンス | 60 分 (1 時間) |
| 印刷 printer | 4,230 分 (3 日以内) |
| 印刷 printTaskDefinition | 4,230 分 (3 日以内) |
| todoTask | 4,230 分 (3 日以内) このリソースの Webhook はグローバル エンドポイントでのみ使用でき、国内クラウドでは使用できません。 |
| Microsoft Entra正常性監視アラート | 42,300 分 (30 日以内) |
| baseTask (非推奨) | 4,230 分 (3 日以内) |
注: 既存のアプリケーションと新規アプリケーションのどちらもサポートされている値を超えてはなりません。 将来的には、最大値を超えるサブスクリプションを作成または更新する要求はすべて失敗します。
遅延
次の表は、サービスで発生するイベントと変更通知の配信との間で予想される待ち時間を示しています。
| リソース | 平均遅延時間 | 最大遅延時間 |
|---|---|---|
| aiInteraction | 10 秒未満 | 60 分 |
| アラート1 | 3 分未満 | 5 分 |
| 承認 | 10 秒未満 | 40 秒 |
| calendar | 1 分未満 | 3 分 |
| callRecord2 | 30 分未満 | 150 分 |
| callRecording | 10 秒未満 | 60 分 |
| callTranscript | 10 秒未満 | 60 分 |
| channel | 10 秒未満 | 60 分 |
| チャット | 10 秒未満 | 60 分 |
| chatMessage | 10 秒未満 | 1 分 |
| contact | 1 分未満 | 3 分 |
| 会話 | 不明 | 不明 |
| conversationMember | 10 秒未満 | 60 分 |
| driveItem | 1 分未満 | 60 分 |
| イベント | 不明 | 不明 |
| グループ | 不明 | 不明 |
| 正常性監視アラート | 不明 | 不明 |
| リスト | 1 分未満 | 60 分 |
| message | 1 分未満 | 3 分 |
| offerShiftRequest | 1 分未満 | 60 分 |
| onlineMeeting | 10 秒未満 | 1 分 |
| openShiftChangeRequest | 1 分未満 | 60 分 |
| プレゼンス | 10 秒未満 | 1 分 |
| printer | 1 分未満 | 5 分 |
| printTaskDefinition | 1 分未満 | 5 分 |
| シフト | 1 分未満 | 60 分 |
| swapShiftsChangeRequest | 1 分未満 | 60 分 |
| team | 10 秒未満 | 60 分 |
| teamsAppInstallation | 10 秒未満 | 60 分 |
| timeOffRequest | 1 分未満 | 60 分 |
| todoTask | 2 分未満 | 15 分 |
| ユーザー | 不明 | 不明 |
1 アラート リソースに対して提供される待機時間は、 アラート が作成された後にのみ適用されます。 ルールがデータからアラートを作成するのにかかる時間は含まれません。 2 callRecord リソースに対して提供される待機時間は、 呼び出 しレコードの最初のバージョンにのみ適用されます。 後続のバージョンの呼び出しレコードは、指定された待機時間を超えて更新される可能性があります。
リレーションシップ
なし。
JSON 表記
次の JSON 表現は、リソースの種類を示しています。
{
"@odata.type": "#microsoft.graph.subscription",
"applicationId": "String",
"changeType": "String",
"clientState": "String",
"creatorId": "String",
"encryptionCertificate": "String",
"encryptionCertificateId": "String",
"expirationDateTime": "String (timestamp)",
"id": "String (identifier)",
"includeResourceData": "Boolean",
"latestSupportedTlsVersion": "String",
"lifecycleNotificationUrl": "String",
"notificationContentType": "String",
"notificationQueryOptions": "String",
"notificationUrl": "String",
"notificationUrlAppId": "String",
"resource": "String"
}