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

名前空間: microsoft.graph

サブスクリプションを使用すると、クライアント アプリは Microsoft Graph のデータの変更に関する変更通知を受信できます。現在、サブスクリプションは次のリソースで有効です。

サポートされている各リソースの使用可能なリソース パスの値については、「 Microsoft Graph API を使用して変更通知を取得する」を参照してください。 ライフサイクル通知を使用する方法については、「 不足しているサブスクリプションと変更通知を減らす」を参照してください。

メソッド

メソッド 戻り値の型 説明
Create subscription subscription Microsoft Graph のデータが変更されたときに変更通知を受信するリスナー アプリケーションに登録します。
サブスクリプションの更新 subscription 有効期限を更新することにより、サブスクリプションを更新します。
サブスクリプションのリスト作成 サブスクリプション アクティブなサブスクリプションのリストを作成します。
サブスクリプションの取得 subscription サブスクリプション オブジェクトのプロパティと関係を読み取ります。
サブスクリプションの削除 なし サブスクリプション オブジェクトを削除します。

プロパティ

プロパティ 説明 サポートされているリソース
applicationId 文字列型 (String) 省略可能。サブスクリプションを作成するときに使用するアプリケーションの識別子。読み取り専用。 すべて
changeType String 必須。登録しているリソース内の、変更通知を上げる変更の種類を示します。サポートされている値は createdupdateddeleted です。コンマ区切りのリストを使用して複数値を結合できます。

注:
  • ドライブ ルート項目とリストの変更通知では updated changeType のみがサポートされます。
  • ユーザーグループの変更通知では、 updateddeleted の changeType がサポートされます。
  • すべて
    clientState String 省略可能。各変更通知内のサービスによって送信される clientState プロパティの値を指定します。最大の長さは 128 文字です。クライアントは、サブスクリプションと共に送信された clientState プロパティの値と、各変更通知と共に受信された clientState プロパティの値を比較することで、その変更通知がサービスから来たことを確認できます。 すべて
    creatorId String 省略可能。 サブスクリプションを作成したユーザーまたはサービス プリンシパルの識別子。 委任されたアクセス許可をアプリで使用してサブスクリプションを作成した場合、このフィールドには、アプリが代理で呼び出しを行っているサインインしているユーザーの ID が含まれます。 アプリがアプリケーション アクセス許可を使用した場合には、このフィールドには、アプリに対応するサービス プリンシパルの ID が含まれます。 読み取り専用です。 すべて
    encryptionCertificate 文字列 省略可能。変更通知のリソース データを暗号化するために使用される公開キーを持つ証明書の base64 エンコード表現。省略可能ですが、includeResourceDatatrue の場合は必須です。 すべて
    encryptionCertificateId String 省略可能。リソース データを復号化するために必要な証明書を識別するのに役立つカスタム アプリ提供の識別子。 すべて
    expirationDateTime DateTimeOffset 必須です。Webhook サブスクリプションの有効期限が切れる日時を指定します。時刻は UTC で指定し、購読するリソースごとに異なるサブスクリプションの作成からの経過時間にすることもできます。サポートされているサブスクリプションの最大期間については、 以下の表 を参照してください。 すべて
    id String 省略可能。サブスクリプションの一意の識別子です。読み取り専用。 すべて
    includeResourceData ブール値 省略可能。true に設定すると、変更通知にはリソース データが含まれます (チャット メッセージのコンテンツなど)。 すべて
    latestSupportedTlsVersion String 省略可能。notificationUrl で指定された通知エンドポイントがサポートするトランスポート層セキュリティ (TLS) の最新バージョンを指定します。可能な値は、v1_0v1_1v1_2v1_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"
    }