Erhalten von Änderungsbenachrichtigungen für Anwesenheitsupdates in Microsoft Teams

Änderungsbenachrichtigungen in Microsoft Graph ermöglichen es Ihnen, Änderungen an Benutzeranwesenheitsinformationen in Microsoft Teams zu abonnieren. Änderungsbenachrichtigungen bieten eine Alternative zum Abrufen der Anwesenheit mithilfe der GET Presence und POST getPresencesByUserId-APIs .

Verwenden Sie Webhooks, um die Anwesenheitsinformationen der Benutzer zu abonnieren und Benachrichtigungen zu erhalten, wenn Änderungen auftreten. Allgemeine Informationen zu Webhooks finden Sie unter Microsoft Graph-API-Änderungsbenachrichtigungen.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Berechtigungen

Unterstützte Ressourcen für die Anwesenheit

Ein einzelner Benutzer kann ein Anwesenheitsabonnement pro einzigartiger Anwendung mit einer maximalen Ablaufzeit von einer Stunde erstellen. Ein Abonnement kann über die Abonnement-API aktualisieren verlängert werden, bevor es abläuft, oder es kann nach Ablauf ein neues Abonnement für dieselbe Ressource erstellt werden. Präsenzabonnements unterstützen Benachrichtigungen mit Ressourcendaten, sodass detailliertere Informationen zusammen mit Änderungsbenachrichtigungen übermittelt werden können. Weitere Informationen finden Sie unter Änderungsbenachrichtigungen mit Ressourcendaten einrichten.

In der folgenden Tabelle sind die Arten von Anwesenheitsänderungen aufgeführt, die Sie abonnieren können. Weitere Informationen finden Sie unter Erstellen eines Abonnements.

Abonnieren von Anwesenheitsänderungen

Um Anwesenheitsänderungen zu abonnieren, können Sie die Ressource in der Abonnementnutzlast so festlegen, dass communications/presences/{id} das Feld {id} durch die Benutzer-ID-GUID der Anwesenheit des Benutzers ersetzt werden muss. Dieses Abonnement sendet Änderungsbenachrichtigungen, wenn sich die Anwesenheit des Benutzers ändert.

Legen Sie includeResourceData die entsprechenden Werte für encryptionCertificate und encryptionCertificateId abonnieren Sie umfassende Benachrichtigungen.true

Beispiel: Nutzlasten für ein Einzelbenutzer-Anwesenheitsabonnement

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

Anwesenheit mehrerer Benutzer abonnieren

Massenabonnements für die Anwesenheit von Benutzern können erstellt werden, indem Sie den Wert der Abonnementressource auf /communications/presences?$filter=id in ('{id}', '{id}',...)festlegen, wobei {id} die GUID einer Benutzer-ID von Benutzern darstellt. In einem einzigen Abonnement können maximal 650 Benutzer abonniert werden. Bei Anwesenheitsänderungen für Benutzer-IDs wird eine Benachrichtigung generiert.

Beispiel: Abonnementnutzlasten für mehrere Benutzer

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

Empfangen von Benachrichtigungen über Anwesenheitsereignisse

Änderungsbenachrichtigungen für Anwesenheitsereignisse werden ausgelöst, wenn Änderungen an der Verfügbarkeit und Aktivität eines Benutzers vorgenommen werden.

Grundlegende Anwesenheitsbenachrichtigungen

Allgemeine Benachrichtigungen informieren Abonnenten über die Identität der Ressource, die sich geändert hat. Wenn Sie diese Informationen erhalten, sollten Sie einen separaten GET-Aufruf ausführen, um die Details der Daten abzurufen. Bei einfachen Anwesenheitsbenachrichtigungen erhalten Sie Informationen darüber, welche Anwesenheit des Benutzers sich geändert hat, aber keine Daten über die Details der Anwesenheit des Benutzers. Sie können die GET-Anwesenheits-APIs verwenden, um den Verfügbarkeits- und Aktivitätsstatus des Benutzers zu ermitteln.

Beispiel für eine Nutzlast

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

Umfassende Anwesenheitsbenachrichtigungen

Umfassende Benachrichtigungen informieren Abonnenten über Änderungen, die an einer Ressource vorgenommen wurden. Bei umfangreichen Anwesenheitsbenachrichtigungen werden Abonnenten benachrichtigt, wenn die des Availability Benutzers und Activity Änderungen in encryptedContent.data. Informationen zum Abonnieren von Rich-Benachrichtigungen und zum Entschlüsseln von Daten finden Sie unter Einrichten von Änderungsbenachrichtigungen, die Ressourcendaten enthalten.

Weitere Informationen zu möglichen Kombinationen von Verfügbarkeit und Aktivität finden Sie unter Anwesenheitseigenschaften.

Beispiel für eine Nutzlast

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

Beispiel: Entschlüsselte Benachrichtigungen mit Ressourcendaten

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

Verwandte Inhalte

• Anwesenheit
• Ändern von Benachrichtigungen über Webhooks
• Microsoft Graph-API-Änderungsbenachrichtigungen