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

名前空間: microsoft.graph

サブスクリプションは、Microsoft Graph 上のデータの変更に関する変更通知の受信をクライアント アプリに許可します。

現在、サブスクリプションは次のリソースに対して有効になっています。

メモ アスタリスク (*) でマークされたリソースへのサブスクリプションは、エンドポイントでのみサポートされます /beta

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

メソッド

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

プロパティ

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

注:
  • ドライブ ルート項目とリストの変更通知では updated changeType のみがサポートされます。
  • ユーザーグループの変更通知では、 updateddeleted の changeType がサポートされます。 を使用して updated 、ユーザーまたはグループが作成、更新、または論理的に削除されたときに通知を受信します。 ユーザーまたはグループが完全に削除されたときに通知を受信するために使用 deleted します。
  • 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 省略可能。 、、および missed 通知などsubscriptionRemovedreauthorizationRequired、ライフサイクル通知を受け取るエンドポイントの URL。 この URL は HTTPS プロトコルを利用する必要があります。
    notificationQueryOptions String 省略可能。 ターゲット リソースの値を指定するための OData クエリ オプション。 ここで指定したクエリ オプションと一致する状態にリソースが到達すると、クライアントは通知を受け取ります。 サブスクリプション作成ペイロードのこの新しいプロパティと、既存のすべてのプロパティを使うと、Webhook は notificationQueryOptions プロパティに記載されている目的の状態にリソースが到達するたびに通知を送ります。 たとえば、印刷ジョブが完了した場合や、印刷ジョブ リソースプロパティ isFetchable プロパティ値が true などになる場合です。

    ユニバーサル プリント サービスでのみサポートされます。 詳細については、「Microsoft Graph を使用してクラウド印刷 API からの変更通知をサブスクライブする」を参照してください。
    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"
    }