Microsoft Teamsでのプレゼンス更新プログラムの変更通知を取得する
Microsoft Graph の変更通知を使用すると、Microsoft Teamsの ユーザー プレゼンス 情報の変更をサブスクライブできます。 変更通知は、GET プレゼンスと POST getPresencesByUserId API を使用して、プレゼンスのポーリングに代わる方法を提供します。
Webhook を使用してユーザーのプレゼンス情報をサブスクライブし、変更が発生したときに通知を受け取ります。 Webhook の一般的な情報については、「Microsoft Graph API変更通知」を参照してください。
注:
2024 年 6 月 30 日より、アクティブな会議通話に発生した変更を取得するには、 リッチ通知をサブスクライブすることをお勧めします。
アクセス許可
| アクセス許可の種類 | アクセス許可 (特権の小さいものから大きいものへ) | サポートされるバージョン |
|---|---|---|
| 委任 (職場または学校のアカウント) | Presence.Read.All。 | V1、ベータ版。 |
| 委任 (個人用 Microsoft アカウント) | サポートされていません。 | サポートされていません。 |
| アプリケーション | サポートされていません。 | サポートされていません。 |
プレゼンスでサポートされるリソース
1 人のユーザーが、最大有効期限が 1 時間の一意のアプリケーションごとに 1 つのプレゼンス サブスクリプションを作成できます。 サブスクリプションは、有効期限が切れる前に サブスクリプション API を更新 するか、有効期限が切れた後に同じリソースに対して新しいサブスクリプションを作成できます。 プレゼンス サブスクリプションでは、リソース データを含む通知がサポートされており、変更通知と共により詳細な情報を配信できます。 詳細については、「 リソース データを使用して変更通知を設定する」を参照してください。
次の表に、サブスクライブできるプレゼンスの変更の種類を示します。 詳細については、「サブスクリプションの 作成」を参照してください。
| プレゼンス サブスクリプションの種類 | リソース URL | サポートされている変更の種類 |
|---|---|---|
| シングル ユーザー プレゼンスの変更 | communications/presences/{id} |
更新あり |
| 一括ユーザー プレゼンスの変更 (最大 650 ユーザー ID) | communications/presences?$filter=id in ('{id}', '{id}', ...) |
更新あり |
プレゼンスの変更をサブスクライブする
プレゼンスの変更をサブスクライブするには、サブスクリプション ペイロード内のリソースを、{id} フィールドを communications/presences/{id} ユーザーのプレゼンスのユーザー ID GUID に置き換える必要がある場所に設定できます。 このサブスクリプションは、ユーザープレゼンスが変更されたときに変更通知を配信します。
を にtrue設定includeResourceDataし、および に適切な値をencryptionCertificateencryptionCertificateId指定して、リッチ通知をサブスクライブします。
例: シングル ユーザー プレゼンス サブスクリプション ペイロード
{
"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}"
}