名前空間: 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 のデータが変更されたときの変更通知を受け取る。 サブスクリプションが作成され、正常に検証されると、Microsoft Graph は、サブスクライブしたリソースに変更があるたびに、少なくとも 1 つの changeNotificationCollection オブジェクトをアプリに送信します。 |
| Get | subscription | サブスクリプション オブジェクトのプロパティとリレーションシップを読み取ります。 |
| Update | subscription | 有効期限を更新してサブスクリプションを更新します。 |
| Delete | なし | サブスクリプション オブジェクトを削除します。 |
| 再認証 | なし | reauthorizationRequired チャレンジを受け取ったら、サブスクリプションを再承認します。 |
| VAPID を取得する | 文字列 | 次の RFC8292にサブスクリプションを作成するために使用する Voluntary Application Server Identification (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 プロパティに記載されている目的の状態に達すると、Web フックは通知を配信します。 たとえば、印刷ジョブが完了した場合や、印刷ジョブ リソースプロパティ 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/) を含めないでください。 サポートされているリソースについては、考えられるリソース パスの値を参照してください。 |
| vapidPublicKey | String | 省略可能。 アプリケーション サーバーの VAPID 公開キー。base64url でエンコードされます (P-256 非圧縮ポイント、65 バイトのプリエンコード)。 サブスクリプション コレクションで getVapidPublicKey 関数を呼び出して取得されます。 ブラウザーはこの値を PushManager.subscribe({ applicationServerKey }) に渡して、プッシュ サブスクリプションをこのサーバー ID にバインドします。
notificationUrl が既知の Web プッシュ サービスの配信元 (*.push.apple.com、fcm.googleapis.com、updates.push.services.mozilla.com など) をターゲットにする場合に必要です。標準の Webhook サブスクリプションで提供されている場合は、400 Bad Request で拒否されます。 詳細については、 RFC 8292 を参照してください。 |
| webPushEncryptionP256dhPublicKey | String | 省略可能。 サブスクライバーの ECDH 公開キー。base64url でエンコードされます(P-256 非圧縮ポイント、65 バイトのプリエンコード)。
PushSubscription.getKey('p256dh') 経由でブラウザーから取得します。 ECDH キー交換時にピア公開キーとして使用され、RFC 8291 ペイロード暗号化用のメッセージごとのコンテンツ暗号化キーを派生させます。
notificationUrl が既知の Web プッシュ サービス配信元を対象とする場合に必要です。標準の Webhook サブスクリプションで提供されている場合、400 Bad Request で拒否されます。 詳細については、 RFC 8291 のセクション 3 を参照してください。 |
| webPushEncryptionSecret | String | 省略可能。 サブスクライバーの認証シークレット。base64url でエンコード (16 バイトの事前エンコード)。
PushSubscription.getKey('auth') 経由でブラウザーから取得します。 RFC 8291 ペイロード暗号化のキー マテリアルを派生させる HKDF 結合ステップの HMAC-SHA-256 ソルトとして使用されます。 書き込み専用: この値は GET 応答で返されません ( nullとして返されます)。 秘密として扱います。
notificationUrl が既知の Web プッシュ サービス配信元を対象とする場合に必要です。標準の Webhook サブスクリプションで提供されている場合、400 Bad Request で拒否されます。 詳細については、 RFC 8291 のセクション 3 を参照してください。 |
サブスクリプション ライフタイム
サブスクリプションのライフタイムには制限があります。 アプリは、有効期限が切れる前にサブスクリプションを更新する必要があります。それ以外の場合は、新しいサブスクリプションを作成する必要があります。 また、アプリはいつでも登録を解除して、変更通知の受信を停止できます。
さらに、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 offerShiftRequest | 360 分 (6 時間) |
| Teams Shifts openShiftChangeRequest | 360 分 (6 時間) |
| Teams シフト シフト | 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 Health Monitoring アラート | 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 分未満 | 6 時間 |
| イベント | 不明 | 不明 |
| グループ | 不明 | 不明 |
| 正常性監視アラート | 不明 | 不明 |
| リスト | 1 分未満 | 6 時間 |
| 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アラート リソースに対して提供される待機時間は、アラートの作成後にのみ適用されます。 ルールがデータからアラートを作成するのにかかる時間は含まれません。 2callRecord リソースに対して提供される待機時間は、通話レコードの最初のバージョンにのみ適用されます。 それ以降のバージョンの通話記録は、記載されている遅延を超えて更新される場合があります。
リレーションシップ
なし。
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",
"vapidPublicKey": "String",
"webPushEncryptionP256dhPublicKey": "String",
"webPushEncryptionSecret": "String"
}