Microsoft Teams でのプレゼンス更新の変更通知を受け取る

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

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

この API は、次の国内クラウド展開で使用できます。

アクセス許可

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

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

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

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

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

includeResourceData を true に設定し、encryptionCertificateとencryptionCertificateIdがリッチ通知をサブスクライブするための適切な値を指定します。

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

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

リッチ プレゼンス通知

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

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

ペイロードの例

{
  "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 の変更通知