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

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

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

アクセス許可

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

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

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

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

プレゼンスの変更をサブスクライブするには、サブスクリプション ペイロード内のリソースを、{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}"
}

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

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

基本的なプレゼンス通知

基本的な通知は、変更されたリソースの ID についてサブスクライバーに通知します。 この情報を受け取ったら、別の GET 呼び出しを行ってデータの詳細を取得する必要があります。 基本的なプレゼンス通知の場合は、変更されたユーザーのプレゼンスに関する情報を受け取りますが、ユーザーのプレゼンスの詳細に関するデータはありません。 GET プレゼンス API を使用して、ユーザーの可用性とアクティビティの状態を検出できます。

ペイロードの例

{
  "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}",
  }]
}

リッチ プレゼンス通知

リッチ通知は、リソースに対して発生した変更についてサブスクライバーに通知します。 リッチ プレゼンス通知の場合、サブスクライバーは、ユーザー Availability と Activity が で encryptedContent.data変更されたときに通知されます。 リッチ通知のサブスクライブとデータの暗号化解除については、「リソース データを 含む変更通知を設定する」を参照してください。

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

ペイロードの例

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

関連コンテンツ

• プレゼンス
• Webhook を使用して通知を変更する
• Microsoft Graph API の変更通知