サブスクリプションリソースの種類

2024-10-31

名前空間: microsoft.graph

クライアントアプリが Microsoft Graph のデータに対する変更に関する変更通知を受け取るサブスクリプションを表します。

変更通知をサポートするリソースなど、サブスクリプションと変更通知の詳細については、「リソースデータの変更に関する通知を設定する」を参照してください。

メソッド

メソッド	戻り値の型	説明
List	サブスクリプション	アクティブなサブスクリプションのリストを作成します。
Create	subscription	Microsoft Graph のデータが変更されたときに変更通知を受信するリスナーアプリケーションに登録します。 susbcription が作成され、正常に評価されると、Microsoft Graph は、サブスクライブされたリソースに変更があるたびに、少なくとも 1 つの changeNotificationCollection オブジェクトをアプリに送信します。
Get	subscription	サブスクリプションオブジェクトのプロパティと関係を読み取ります。
Update	subscription	更新のサブスクリプションの有効期限をUpdatesし、配信のために notificationUrl を更新します。
Delete	なし	サブスクリプションオブジェクトを削除します。
再認証	なし	再認証 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	`expirationDateTime`の値が 1 時間を超える場合は Teams リソースに必要です。それ以外の場合は省略可能です。 `subscriptionRemoved`、`reauthorizationRequired`、`missed`通知など、ライフサイクル通知を受信するエンドポイントの 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	最大有効期限
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 日以内)
ユーザー、グループ、その他のディレクトリリソース	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 日以内)

注: 既存のアプリケーションと新規アプリケーションのどちらもサポートされている値を超えてはなりません。将来的には、最大値を超えるサブスクリプションを作成または更新する要求はすべて失敗します。

遅延

次の表は、サービスで発生するイベントと変更通知の配信との間で予想される待ち時間を示しています。

リソース	平均遅延時間	最大遅延時間
aiInteraction	10 秒未満	60 分
アラート¹	3 分未満	5 分
承認	10 秒未満	40 秒
calendar	1 分未満	3 分
callRecord²	30 分未満	150 分
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 分
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 分
ユーザー	不明	不明

¹ アラートリソースに対して提供される待機時間は、 アラート が作成された後にのみ適用されます。ルールがデータからアラートを作成するのにかかる時間は含まれません。 ² 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",
  "notificationQueryOptions": "String",
  "notificationUrl": "String",
  "notificationUrlAppId": "String",
  "resource": "String"
}

次の方法で共有

サブスクリプション リソースの種類

メソッド

プロパティ

サブスクリプション ライフタイム

遅延

リレーションシップ

JSON 表記

フィードバック

その他のリソース

サブスクリプションリソースの種類

サブスクリプションライフタイム