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.

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

Abonnements haben eine maximale Ablaufzeit von einer Stunde. 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.

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.

Beispiel: Grundlegende Anwesenheitsbenachrichtigungen

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

Beispiel: Anwesenheitsbenachrichtigungen mit Ressourcendaten

Anwesenheitsbenachrichtigungen mit Ressourcendaten verfügen über die folgenden zusätzlichen Eigenschaften, die in der Nutzlast verschlüsselt sind:

  • Verfügbarkeits- oder Basis-Anwesenheitsinformationen (verfügbar, abwesend, ausgelastet)
  • Aktivität oder Informationen, die die Verfügbarkeit ergänzen (in einer Besprechung, im Anruf)

[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.

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