Microsoft Teams でのプレゼンス更新プログラムの変更通知を取得する

  • [アーティクル]

Microsoft Graph の変更通知を使用すると、Microsoft Teams の ユーザー プレゼンス 情報の変更をサブスクライブできます。 変更通知は、GET プレゼンスと POST getPresencesByUserId API を使用して、プレゼンスのポーリングに代わる方法を提供します。

Webhook を使用してユーザーのプレゼンス情報をサブスクライブし、変更が発生したときに通知を受け取ります。 Webhook の一般的な情報については、「Microsoft Graph API変更通知」を参照してください。

アクセス許可

アクセス許可の種類 アクセス許可 (特権の小さいものから大きいものへ) サポートされるバージョン
委任 (職場または学校のアカウント) Presence.Read.All。 V1、ベータ版。
委任 (個人用 Microsoft アカウント) サポートされていません。 サポートされていません。
アプリケーション サポートされていません。 サポートされていません。

プレゼンスでサポートされるリソース

サブスクリプションの有効期限は最大 1 時間です。 サブスクリプションは、有効期限が切れる前に サブスクリプション API を更新 するか、有効期限が切れた後に同じリソースに対して新しいサブスクリプションを作成できます。 プレゼンス サブスクリプションでは、リソース データを含む通知がサポートされており、変更通知と共により詳細な情報を配信できます。 詳細については、「 リソース データを使用して変更通知を設定する」を参照してください。

次の表に、サブスクライブできるプレゼンスの変更の種類を示します。 詳細については、「サブスクリプションの 作成」を参照してください。

プレゼンス サブスクリプションの種類 リソース URL サポートされている変更の種類
シングル ユーザー プレゼンスの変更 communications/presences/{id} 更新あり
一括ユーザー プレゼンスの変更 (最大 650 ユーザー ID) communications/presences?$filter=id in ('{id}', '{id}', ...) 更新あり

プレゼンスの変更をサブスクライブする

プレゼンスの変更をサブスクライブするには、サブスクリプション ペイロード内のリソースを、{id} フィールドを communications/presences/{id} ユーザーのプレゼンスのユーザー ID GUID に置き換える必要がある場所に設定できます。 このサブスクリプションは、ユーザープレゼンスが変更されたときに変更通知を配信します。

例: シングル ユーザー プレゼンス サブスクリプション ペイロード

{
    "changeType": "updated",
    "notificationUrl": "https://webhook.contoso.com/api",
    "lifecycleNotificationUrl": "https://webhook.contoso.com/api",
    "resource": "communications/presences/{id}",
    "expirationDateTime": "2023-09-14T10:00:00.0000000Z",
    "includeResourceData": true,
    "encryptionCertificate": "{encryption certificate}",
    "encryptionCertificateId": "{certificate id}",
    "clientState": "{secret client state}"
}

複数のユーザーのプレゼンスをサブスクライブする

ユーザープレゼンスの一括サブスクリプションは、サブスクリプション リソースの値を に /communications/presences?$filter=id in ('{id}', '{id}',...)設定することで作成できます。ここで、{id} はユーザーのユーザー ID GUID を表します。 1 つのサブスクリプションで最大 650 人のユーザーをサブスクライブできます。 ユーザー ID のプレゼンスの変更によって通知が生成されます。

例: 複数のユーザー プレゼンス サブスクリプション ペイロード

{
    "changeType": "updated",
    "notificationUrl": "https://webhook.contoso.com/api",
    "lifecycleNotificationUrl": "https://webhook.contoso.com/api",
    "resource": "/communications/presences?$filter=id in ('{id}', '{id}',...)",
    "expirationDateTime": "2023-09-14T10:00:00.0000000Z",
    "includeResourceData": true,
    "encryptionCertificate": "{encryption certificate}",
    "encryptionCertificateId": "{certificate id}",
    "clientState": "{secret client state}"
}

プレゼンス イベント通知を受信する

プレゼンス イベントの変更通知は、ユーザーの可用性とアクティビティに変更が加えられたときにトリガーされます。

例: 基本的なプレゼンス通知

{
  "value": [{
    "subscriptionId": "{Subscription id}",
    "clientState": "{secret client state}",
    "changeType": "updated",
    "tenantId": "{Organization/Tenant id}",
    "resource": "communications/presences/{id}",
    "subscriptionExpirationDateTime": "2023-09-14T10:00:00.0000000Z",
    "resourceData": {
      "@odata.id": "users/{User Id}/presence",
      "@odata.type": "#microsoft.graph.presence",
      "id": "{User Id}"
    },
    "organizationId": "{Organization/Tenant id}",
  }]
}

例: リソース データを含むプレゼンス通知

リソース データを含むプレゼンス通知には、ペイロードで次の追加プロパティが暗号化されています。

  • 可用性または基本プレゼンス情報 (使用可能、退席、ビジー)
  • 可用性の補足となるアクティビティまたは情報 (会議中、通話中)

[注]: 可用性とアクティビティは同じ値にすることができます。

可用性とアクティビティの可能な組み合わせの詳細については、「 プレゼンスのプロパティ」を参照してください。

{
  "value": [{
    "subscriptionId": "{Subscription id}",
    "clientState": "{secret client state}",
    "changeType": "updated",
    "tenantId": "{Organization/Tenant id}",
    "resource": "communications/presences/{id}",
    "subscriptionExpirationDateTime": "2023-09-14T10:00:00.0000000Z",
    "resourceData": {
      "@odata.id": "users/{User Id}/presence",
      "@odata.type": "#microsoft.graph.presence",
      "id": "{User Id}"
    },
    "organizationId": "{Organization/Tenant id}",
    "encryptedContent": {
      "data": "{Encrypted content}",
      "dataSignature": "{Encrypted data signature}",
      "dataKey": "{Encrypted data key for encrypting content}",
      "encryptionCertificateId": "{User specified id of encryption certificate}",
      "encryptionCertificateThumbprint": "{Encrpytion certification thumbprint}"
    }
  }],
  "validationTokens": ["{Validation Tokens}"]
}

例: リソース データを使用して復号化された通知

{
    "@odata.id": "users/{User Id}/presence",
    "@odata.type": "#microsoft.graph.presence",
    "id": "{User Id}",
    "availability": "{Availability}",
    "activity": "{Activity}"
}

関連コンテンツ