サブスクリプション リソースの種類
名前空間: microsoft.graph
サブスクリプションを使用すると、クライアント アプリは Microsoft Graph のデータの変更に関する変更通知を受信できます。現在、サブスクリプションは次のリソースで有効です。
- Microsoft Graph Security API の警告。
- Microsoft Teams での電話または会議の後に作成された callRecord。
- Microsoft Teams の チャネル。
- Microsoft Teams での チャット。
- Microsoft Teams のチームまたはチャネルを介して送信された chatMessage。
- Microsoft 365 グループの会話。
- Microsoft Teams のチームまたはチャネルのconversationMember。
- OneDrive for Business のルート フォルダー driveItem の階層内、またはユーザーの個人用 OneDrive のルート フォルダーまたはサブフォルダー driveItem の階層内にあるコンテンツ。
- Azure Active Directory 内のグループ。
- SharePoint [サイト][]の[リスト][]。
- Outlook のメッセージ、イベント、または[連絡先][]。
- printer (プリンターの印刷ジョブが JobFetchable - つまり印刷用に取得の準備が整った状態のとき) とユニバーサル プリントの printTaskDefinition。詳細については、「クラウド印刷 API からの変更通知をサブスクライブする」を参照してください。
- Microsoft Teams の チーム。
- Microsoft To Do のユーザーの todoTask。*
- Azure Active Directory 内のユーザー。
サポートされている各リソースの使用可能なリソース パスの値については、「 Microsoft Graph API を使用して変更通知を取得する」を参照してください。 ライフサイクル通知を使用する方法については、「 不足しているサブスクリプションと変更通知を減らす」を参照してください。
メソッド
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| Create subscription | subscription | Microsoft Graph のデータが変更されたときに変更通知を受信するリスナー アプリケーションに登録します。 |
| サブスクリプションの更新 | subscription | 有効期限を更新することにより、サブスクリプションを更新します。 |
| サブスクリプションのリスト作成 | サブスクリプション | アクティブなサブスクリプションのリストを作成します。 |
| サブスクリプションの取得 | subscription | サブスクリプション オブジェクトのプロパティと関係を読み取ります。 |
| サブスクリプションの削除 | なし | サブスクリプション オブジェクトを削除します。 |
プロパティ
| プロパティ | 型 | 説明 | サポートされているリソース |
|---|---|---|---|
| applicationId | 文字列型 (String) | 省略可能。サブスクリプションを作成するときに使用するアプリケーションの識別子。読み取り専用。 | すべて |
| changeType | String | 必須。登録しているリソース内の、変更通知を上げる変更の種類を示します。サポートされている値は created、updated、deleted です。コンマ区切りのリストを使用して複数値を結合できます。注: updated changeType のみがサポートされます。 updated と deleted の changeType がサポートされます。 |
すべて |
| clientState | String | 省略可能。各変更通知内のサービスによって送信される clientState プロパティの値を指定します。最大の長さは 128 文字です。クライアントは、サブスクリプションと共に送信された clientState プロパティの値と、各変更通知と共に受信された clientState プロパティの値を比較することで、その変更通知がサービスから来たことを確認できます。 |
すべて |
| creatorId | String | 省略可能。 サブスクリプションを作成したユーザーまたはサービス プリンシパルの識別子。 委任されたアクセス許可をアプリで使用してサブスクリプションを作成した場合、このフィールドには、アプリが代理で呼び出しを行っているサインインしているユーザーの ID が含まれます。 アプリがアプリケーション アクセス許可を使用した場合には、このフィールドには、アプリに対応するサービス プリンシパルの ID が含まれます。 読み取り専用です。 | すべて |
| encryptionCertificate | 文字列 | 省略可能。変更通知のリソース データを暗号化するために使用される公開キーを持つ証明書の 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 | 省略可能。 subscriptionRemoved および missed 通知を含むライフサイクル通知を受信するエンドポイントの URL です。 この URL は HTTPS プロトコルを利用する必要があります。 |
すべて |
| notificationQueryOptions | String | 省略可能。 ターゲット リソースの値を指定するための OData クエリ オプション。 ここで指定したクエリ オプションと一致する状態にリソースが到達すると、クライアントは通知を受け取ります。 サブスクリプション作成ペイロードのこの新しいプロパティと、既存のすべてのプロパティを使うと、Webhook は notificationQueryOptions プロパティに記載されている目的の状態にリソースが到達するたびに通知を送ります。 たとえば、印刷ジョブが完了した場合や、印刷ジョブ リソースプロパティ isFetchable プロパティ値が true などになる場合です。 |
ユニバーサル プリント サービス |
| notificationUrl | 文字列 | 必須です。 変更通知を受信するエンドポイントの URL です。この URL は HTTPS プロトコルを利用する必要があります。 | すべて |
| notificationUrlAppId | String | 省略可能。 サブスクリプション サービスが検証トークンの生成に使用できるアプリ ID。 これにより、クライアントは受信した通知の信頼性を検証できます。 | すべて |
| resource | String | 必須です。 変更の監視対象となるリソースを指定します。 ベース URL (https://graph.microsoft.com/v1.0/) は含めないでください。 サポートされているリソースについては、考えられるリソース パスの値を参照してください。 |
すべて |
リソースの種類別のサブスクリプションの最大の長さ
| Resource | 最大有効期限 |
|---|---|
| セキュリティの 警告 | 43200 分 (30 日以内) |
| Teams callRecord | 4230 分 (3 日以内) |
| Teams チャネル | 60 分 (1 時間) |
| Teams チャット | 60 分 (1 時間) |
| Teams chatMessage | 60 分 (1 時間) |
| Teams conversationMember | 60 分 (1 時間) |
| Teams チーム | 60 分 (1 時間) |
| グループ 会話 | 4230 分 (3 日以内) |
| OneDrive driveItem | 42300 分 (30 日以内) |
| SharePoint リスト | 42300 分 (30 日以内) |
| Outlook メッセージ、イベント、連絡先 | 4230 分 (3 日以内) |
| ユーザー、グループ、その他のディレクトリ リソース | 41760 分 (29 日以内) |
| プレゼンス | 60 分 (1 時間) |
| 印刷 printer | 4230 分 (3 日以内) |
| 印刷 printTaskDefinition | 4230 分 (3 日以内) |
| todoTask | 4230 分 (3 日以内) |
注: 既存のアプリケーションと新規アプリケーションのどちらもサポートされている値を超えてはなりません。 将来的には、最大値を超えるサブスクリプションを作成または更新する要求はすべて失敗します。
リレーションシップ
なし
JSON 表記
以下は、リソースの JSON 表記です。
{
"@odata.type": "#microsoft.graph.subscription",
"id": "String (identifier)",
"resource": "String",
"changeType": "String",
"clientState": "String",
"notificationUrl": "String",
"expirationDateTime": "String (timestamp)",
"applicationId": "String",
"creatorId": "String",
"includeResourceData": "Boolean",
"lifecycleNotificationUrl": "String",
"encryptionCertificate": "String",
"encryptionCertificateId": "String",
"latestSupportedTlsVersion": "String",
"notificationQueryOptions": "String",
"notificationUrlAppId": "String"
}
フィードバック
フィードバックの送信と表示