Freigeben über

Abrufen von Änderungsbenachrichtigungen für Anwesenheitsupdates in Microsoft Teams

  • Artikel

Änderungsbenachrichtigungen in Microsoft Graph ermöglichen Es Ihnen, Änderungen an Benutzerpräsenzinformationen in Microsoft Teams zu abonnieren. Änderungsbenachrichtigungen bieten eine Alternative zum Abrufen von Anwesenheitsinformationen mithilfe der GET-Anwesenheits - und POST-APIs getPresencesByUserId .

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

Hinweis

Ab dem 30. Juni 2024 wird empfohlen, umfangreiche Benachrichtigungen zu abonnieren, um Änderungen an einem aktiven Besprechungsanruf zu erhalten.

Berechtigungen

Berechtigungstyp Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten) Unterstützte Versionen
Delegiert (Geschäfts-, Schul- oder Unikonto) Presence.Read.All. V1, Beta.
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Nicht unterstützt Nicht unterstützt

Unterstützte Ressourcen für Anwesenheitsinformationen

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

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

Anwesenheitsabonnementtyp Ressourcen-URL Unterstützte Änderungstypen
Änderungen an der Anwesenheit einzelner Benutzer communications/presences/{id} Aktualisiert
Massenänderungen an der Anwesenheit von Benutzern (maximal 650 Benutzer-IDs) communications/presences?$filter=id in ('{id}', '{id}', ...) Aktualisiert

Abonnieren von Anwesenheitsänderungen

Um Anwesenheitsänderungen zu abonnieren, können Sie die Ressource in der Abonnementnutzlast auf communications/presences/{id} festlegen, wobei 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 auf fest includeResourceDatatrue , und geben Sie geeignete Werte für encryptionCertificate und encryptionCertificateId an, um umfangreiche Benachrichtigungen zu abonnieren.

Beispiel: Einzelbenutzer-Anwesenheitsabonnementnutzlasten

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

Abonnieren der Anwesenheit mehrerer Benutzer

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

Beispiel: Nutzlasten des Abonnements für mehrere Benutzerpräsenzen

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

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

Grundlegende Anwesenheitsbenachrichtigungen

Grundlegende Benachrichtigungen benachrichtigen Abonnenten über die Identität der Ressource, die sich geändert hat. Wenn Sie diese Informationen erhalten, sollten Sie einen separaten GET-Aufruf durchführen, um die Details der Daten abzurufen. Für grundlegende Anwesenheitsbenachrichtigungen erhalten Sie Informationen darüber, welche Anwesenheit des Benutzers geändert wurde, aber keine Daten über die Details der Anwesenheit des Benutzers. Sie können die GET-Anwesenheits-APIs verwenden, um den Status der Verfügbarkeit und Aktivität des Benutzers zu ermitteln.

Nutzlastbeispiel

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

Umfangreiche Anwesenheitsbenachrichtigungen

Umfangreiche Benachrichtigungen benachrichtigen Abonnenten über die Änderungen, die an einer Ressource vorgenommen wurden. Bei rich presence-Benachrichtigungen werden Abonnenten benachrichtigt, wenn sich und des Benutzers AvailabilityActivity in encryptedContent.dataändern. Informationen zum Abonnieren umfangreicher Benachrichtigungen und zum Entschlüsseln von Daten finden Sie unter Einrichten von Änderungsbenachrichtigungen, die Ressourcendaten enthalten.

Hinweis

Verfügbarkeit und Aktivität können denselben Wert aufweisen.

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

Nutzlastbeispiel

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