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

  • [アーティクル]

名前空間: microsoft.graph

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

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

メソッド

メソッド 戻り値の型 説明
List サブスクリプション アクティブなサブスクリプションのリストを作成します。
Create subscription Microsoft Graph のデータが変更されたときに変更通知を受信するリスナー アプリケーションに登録します。
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 最大有効期限
    セキュリティの警告 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 日以内)

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

    遅延

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

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

    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"
}