サブスクリプション リソースの種類
名前空間: microsoft.graph
クライアント アプリが Microsoft Graph のデータに対する変更に関する変更通知を受け取るサブスクリプションを表します。
変更通知をサポートするリソースなど、サブスクリプションと変更通知の詳細については、「 リソース データの変更に関する通知を設定する」を参照してください。
メソッド
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| サブスクリプションのリスト作成 | サブスクリプション | アクティブなサブスクリプションのリストを作成します。 |
| Create subscription | subscription | Microsoft Graph のデータが変更されたときに変更通知を受信するリスナー アプリケーションに登録します。 |
| サブスクリプションの取得 | subscription | サブスクリプション オブジェクトのプロパティと関係を読み取ります。 |
| サブスクリプションの更新 | subscription | 更新のサブスクリプションの有効期限をUpdatesし、配信のために notificationUrl を更新します。 |
| サブスクリプションの削除 | なし | サブスクリプション オブジェクトを削除します。 |
| 再認証 | なし | 再認証 Required チャレンジを受け取ったときにサブスクリプションを再認証します。 |
プロパティ
| プロパティ | 種類 | 説明 |
|---|---|---|
| applicationId | String | 省略可能。 サブスクリプションを作成するときに使用するアプリケーションの識別子。 読み取り専用です。 |
| changeType | String | 必須です。 変更通知を発生させるサブスクライブされたリソースの変更の種類を示します。 サポートされている値は created、updated、deleted です。 コンマ区切りのリストを使用して複数値を結合できます。 注: updated changeType のみがサポートされます。 updated と deleted の changeType がサポートされます。 を使用して updated 、ユーザーまたはグループが作成、更新、または論理的に削除されたときに通知を受信します。 ユーザーまたはグループが完全に削除されたときに通知を受信するために使用 deleted します。 |
| clientState | String | 省略可能。 各変更通知内のサービスによって送信される clientState プロパティの値を指定します。 最大の長さは 128 文字です。 クライアントは、サブスクリプションと共に送信された clientState プロパティの値と、各変更通知と共に受信された clientState プロパティの値を比較することで、その変更通知がサービスから来たことを確認できます。 |
| creatorId | String | 省略可能。 サブスクリプションを作成したユーザーまたはサービス プリンシパルの識別子。 アプリが委任されたアクセス許可を使用してサブスクリプションを作成した場合、このフィールドには、アプリの代わりに呼び出されたサインイン ユーザーの ID が含まれます。 アプリがアプリケーションのアクセス許可を使用している場合、このフィールドにはアプリに対応するサービス プリンシパルの ID が含まれます。 読み取り専用です。 |
| encryptionCertificate | String | 省略可能。 変更通知のリソース データを暗号化するために使用される公開キーを持つ証明書の base64 エンコード表現。 省略可能ですが、includeResourceData が true の場合は必須です。 |
| encryptionCertificateId | String | 省略可能。 リソース データを復号化するために必要な証明書を識別するのに役立つカスタム アプリ提供の識別子。 |
| expirationDateTime | DateTimeOffset | 必須です。 webhook サブスクリプションの有効期限が切れる日時を指定します。 時刻は UTC 表示で、登録したリソースごとに異なるサブスクリプション作成からの経過時間にもできます。 サポートされているサブスクリプションの最大期間については、「 サブスクリプションの有効期間」を参照してください。 |
| 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 | 値が 1 時間を超える場合 expirationDateTime は Teams リソースに必要です。それ以外の場合は省略可能です。 、、および missed 通知などsubscriptionRemovedreauthorizationRequired、ライフサイクル通知を受け取るエンドポイントの URL。 この URL は HTTPS プロトコルを利用する必要があります。 詳細については、「 不足しているサブスクリプションを減らし、通知を変更する」を参照してください。 |
| notificationQueryOptions | String | 省略可能。 ターゲット リソースの値を指定するための OData クエリ オプション。 ここで指定したクエリ オプションと一致する状態にリソースが到達すると、クライアントは通知を受け取ります。 サブスクリプション作成ペイロード内のこの新しいプロパティと既存のすべてのプロパティを使用すると、リソースが notificationQueryOptions プロパティに記載されている目的の状態に達するたびに通知が配信されます。 たとえば、印刷ジョブが完了した場合や、印刷ジョブ リソースプロパティ isFetchable プロパティ値が true などになる場合です。 ユニバーサル プリント サービスでのみサポートされます。 詳細については、「 Microsoft Graph を使用してクラウド印刷 API からの変更通知をサブスクライブする」を参照してください。 |
| notificationUrl | String | 必須です。 変更通知を受け取るエンドポイントの URL。 この URL は HTTPS プロトコルを利用する必要があります。 notificationUrl プロパティに含まれるクエリ文字列パラメーターは、Microsoft Graph が変更通知を送信するときに HTTP POST 要求に含まれます。 |
| notificationUrlAppId | String | 省略可能。 サブスクリプション サービスが検証トークンの生成に使用できるアプリ ID。 値を使用すると、クライアントは受信した通知の信頼性を検証できます。 |
| resource | String | 必須です。 変更を監視するリソースを指定します。 ベース URL (https://graph.microsoft.com/v1.0/) は含めないでください。 サポートされているリソースについては、考えられるリソース パスの値を参照してください。 |
サブスクリプション ライフタイム
サブスクリプションのライフタイムには制限があります。 アプリは、有効期限が切れる前にサブスクリプションを更新する必要があります。それ以外の場合は、新しいサブスクリプションを作成する必要があります。 また、アプリはいつでも登録を解除して、変更通知の受信を停止できます。
次の表は、Microsoft Graph のリソースあたりのサブスクリプションの最大有効期限を示しています。
| Resource | 最大有効期限 |
|---|---|
| セキュリティの警告 | 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 日間) |
| グループ会話 | 4,230 分 (3 日以内) |
| OneDrive driveItem | 42,300 分 (30 日以内) |
| SharePoint リスト | 42,300 分 (30 日以内) |
| Outlook メッセージ、イベント、連絡先 | 4,230 分 (3 日以内) |
| ユーザー、グループ、その他のディレクトリ リソース | 41,760 分 (29 日以内) |
| オンライン会議 | 4,230 分 (3 日以内) |
| プレゼンス | 60 分 (1 時間) |
| 印刷 printer | 4,230 分 (3 日以内) |
| 印刷 printTaskDefinition | 4,230 分 (3 日以内) |
| todoTask | 4,230 分 (3 日以内) このリソースの Webhook はグローバル エンドポイントでのみ使用でき、国内クラウドでは使用できません。 |
| baseTask (非推奨) | 4,230 分 (3 日以内) |
注: 既存のアプリケーションと新規アプリケーションのどちらもサポートされている値を超えてはなりません。 将来的には、最大値を超えるサブスクリプションを作成または更新する要求はすべて失敗します。
遅延
次の表は、サービスで発生するイベントと変更通知の配信との間で予想される待ち時間を示しています。
| リソース | 平均遅延時間 | 最大遅延時間 |
|---|---|---|
| アラート1 | 3 分未満 | 5 分 |
| calendar | 1 分未満 | 3 分 |
| callRecord | 15 分未満 | 60 分 |
| callRecording | 10 秒未満 | 60 分 |
| callTranscript | 10 秒未満 | 60 分 |
| channel | 10 秒未満 | 60 分 |
| チャット | 10 秒未満 | 60 分 |
| chatMessage | 10 秒未満 | 1 分 |
| contact | 1 分未満 | 3 分 |
| 会話 | 不明 | 不明 |
| conversationMember | 10 秒未満 | 60 分 |
| driveItem | 1 分未満 | 5 分 |
| イベント | 不明 | 不明 |
| グループ | 不明 | 不明 |
| リスト | 1 分未満 | 5 分 |
| メッセージ | 1 分未満 | 3 分 |
| onlineMeeting | 10 秒未満 | 1 分 |
| プレゼンス | 10 秒未満 | 1 分 |
| printer | 1 分未満 | 5 分 |
| printTaskDefinition | 1 分未満 | 5 分 |
| team | 10 秒未満 | 60 分 |
| todoTask | 2 分未満 | 15 分 |
| ユーザー | 2 分未満 | 15 分 |
1 アラート リソースに対して提供される待機時間は、 アラート が作成された後にのみ適用されます。 ルールがデータからアラートを作成するのにかかる時間は含まれません。
リレーションシップ
なし。
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",
"notificationQueryOptions": "String",
"notificationUrl": "String",
"notificationUrlAppId": "String",
"resource": "String"
}
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示