Änderungsbenachrichtigungen für Outlook-Ressourcen in Microsoft Graph

  • Artikel

Mit dem Microsoft Graph-API können Sie Änderungen an einer Ressource abonnieren – einschließlich Erstellung, Aktualisierung oder Löschung der Ressource – und Benachrichtigungen über Webhooks erhalten. Ein Abonnement gibt die gewünschten Arten von Änderungen an, die für eine bestimmte Ressource überwacht werden sollen, und enthält eine URL für einen Endpunkt, um Benachrichtigungen über diese Änderungen zu erhalten.

Durch das Einrichten eines Abonnements wird der Aufwand reduziert, der sonst durch das Abfragen und Vergleichen von Ressourcen entsteht, um Änderungen abzuleiten. Optional können Sie in der Abonnementanforderung angeben, dass die geänderten Ressourcendaten verschlüsselt und als Teil einer Benachrichtigung eingeschlossen werden sollen, wodurch ein separater nachfolgender API-Aufruf gespeichert wird, um die Ressourcennutzlast abzurufen.

Die maximale Anzahl der aktiven Abonnements ist für alle Anwendungen bei Outlook auf 1000 Abonnements pro Postfach beschränkt. Sie können Änderungen an Kontakten, Ereignissen oder Nachrichten im Postfach abonnieren.

Abonnieren von Änderungen in Kontakten, Kalendern oder E-Mails

Um Änderungsbenachrichtigungen von Outlook-Ressourcen zu abonnieren, erstellen Sie zuerst ein Abonnement.

Die folgende Outlook-Ressourcen unterstützen Abonnements mit oder ohne Ressourcendaten in der Nutzlast Änderungsbenachrichtigung.

Erstellen eines Abonnements

Damit Sie ein Abonnement erstellen, geben Sie die Outlook-Ressource und den Typ der Änderungen (Erstellung, Aktualisierung oder Löschung) an, für die Sie Benachrichtigungen erhalten möchten. Sehen Sie sich das Beispiel an.

Berechtigungen anfordern

Das Erstellen und Verwalten (Abrufen, Aktualisieren und Löschen) eines Abonnements erfordert einen Lesebereich für die Ressource. Beispiel: Zum Erhalten von Änderungsbenachrichtigungen zu Nachrichten benötigt Ihre App die Mail.Read-Berechtigung. Outlook-Änderungsbenachrichtigungen unterstützen delegierte und Anwendungsberechtigungsbereiche. Beachten Sie die folgenden Einschränkungen:

  • Die delegierte Berechtigung unterstützt das Abonnieren von Objekten in Ordnern, die sich nur im Postfach des angemeldeten Benutzers befinden. Beispielsweise können Sie die delegierte Berechtigung Calendars.Read nicht verwenden, um Ereignisse im Postfach eines anderen Benutzers zu abonnieren.

  • So abonnieren Sie Änderungsbenachrichtigungen über Outlook-Kontakte, -Ereignisse oder -Nachrichten in freigegebenen oder delegierten Ordnern:

    • Verwenden Sie die entsprechende Anwendungsberechtigung, um Änderungen von Elementen in einem Ordner oder Postfach eines beliebigen Benutzers im Mandanten zu abonnieren.
    • Verwenden Sie nicht die Outlook-Freigabeberechtigungen (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared und deren Entsprechungen mit Lese-/Schreibzugriff), da sie das Abonnieren von Änderungsbenachrichtigungen für Elemente in freigegebenen oder delegierten Ordnern nicht unterstützen.

Verwenden Sie je nach Ressource die am wenigsten privilegierte Berechtigung, die in der folgenden Tabelle angegeben ist, um diese API aufzurufen.

Ressource Unterstützte Ressourcenpfade Delegiert (Geschäfts-, Schul- oder Unikonto) Delegiert (persönliches Microsoft-Konto) Anwendung
contact Änderungen an allen persönlichen Kontakten im Postfach eines Benutzers:
/me/contacts
/users/{id}/contacts
Änderungen an Kontakten im contactFolder eines Benutzers:
/users/{id}/contactFolders/{id}/contacts		 Contacts.Read Contacts.Read Contacts.Read
event Änderungen an allen Ereignissen im Postfach eines Benutzers:
/me/events
/users/{id}/events		 Calendars.Read Calendars.Read Calendars.Read
meldung Änderungen an allen Nachrichten im Postfach eines Benutzers:
/me/messages
/users/{id}/messages
Änderungen an Nachrichten im mailFolder eines Benutzers:
/users/{id}/mailFolders/{id}/messages		 Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read

Einschließen von Ressourcendaten in die Benachrichtigungsnutzlast

Wenn Ressourcendaten in eine Änderungsbenachrichtigung eingeschlossen werden sollen, müssen Sie zusätzlich zu den Eigenschaften, die Sie normalerweise beim Erstellen eines Abonnements angeben, die folgenden Eigenschaften angeben:

  • includeResourceData: Legen Sie diese Eigenschaft auf true fest, um Ressourcendaten explizit anzufordern.

  • Ressource: Diese Eigenschaft gibt die Ressourcen-URL an. Stellen Sie sicher, dass Sie den $select-Abfrageparameter verwenden, um für die Outlook-Ressourceneigenschaften explizit anzugeben, dass diese die Nutzdaten der Benachrichtigung einschließen sollen.

    Hinweis

    Schließen Sie in die URL nicht $top, $skip, $orderby, $select=Body,UniqueBody, und $expand andere als singleValueExtendedProperties oder multiValueExtendedProperties ein.

  • encryptionCertificate: Diese Eigenschaft enthält nur den öffentlichen Schlüssel, mit dem Microsoft Graph Ressourcendaten verschlüsselt. Behalten Sie den entsprechenden privaten Schlüssel, um den Inhalt zu entschlüsseln.

  • encryptionCertificateId: Diese Eigenschaft ist Ihre eigene Kennung für das Zertifikat. Verwenden Sie diese ID, um in jeder Änderungsbenachrichtigung zu ermitteln, welches Zertifikat für die Entschlüsselung verwendet werden soll.

Sehen Sie sich ein Beispiel zum Abonnieren von Änderungsbenachrichtigungen mit Ressourcendaten für die Ressource Nachricht an.

Optimieren der Bedingungen für eine Benachrichtigung

Sie können die Bedingungen für eine Benachrichtigung mithilfe des $filter-Abfrageparameters weiter optimieren. Sehen Sie sich das Beispiel an.

Eine gängige Anwendung von $filter besteht darin, bei einer Änderung einer bestimmten Ressourceneigenschaft benachrichtigt zu werden. Beispielsweise können Sie $filter verwenden, um ungelesene Nachrichten in einem Ordner zu abonnieren (die Eigenschaft isRead ist false), und alle Änderungstypen einschließen:

  • Eine Nachricht, die dem Ordner hinzugefügt oder als ungelesen markiert wurde, würde eine Created-Benachrichtigung auslösen.
  • Wenn Sie eine Nachricht lesen oder als im Ordner gelesen markieren, würde eine Deleted-Benachrichtigung auslösen.
  • Eine Änderung an einer Eigenschaft einer Nachricht-Ressource im Ordner, mit Ausnahme von isRead, würde eine Updated-Benachrichtigung auslösen.

Wenn Sie beim Erstellen des Abonnements kein verwenden $filter :

  • Das Hinzufügen einer Nachricht zum Ordner würde zu einer Created-Benachrichtigung führen.
  • Das Lesen einer Nachricht im Ordner, das Markieren der Nachricht als gelesen oder das Ändern einer anderen Eigenschaft einer Nachricht in diesem Ordner würde zu einer Updated-Benachrichtigung führen.
  • Das Löschen der Nachricht würde zu einer Delete-Benachrichtigung führen.

Lebenszyklusbenachrichtigungen abonnieren

Die Outlook-Ressourcen Kontakt, Ereignis und Nachricht unterstützen auch das Abonnieren von Lebenszyklusbenachrichtigungen. Lebenszyklusbenachrichtigungen sind erforderlich, wenn Ihre App ihre Abonnements entfernt oder einige Änderungsbenachrichtigungen verpasst. Apps sollten eine Logik implementieren, um den Verlust zu erkennen und zu beheben und einen kontinuierlichen Änderungsbenachrichtigungsfluss fortzusetzen. Weitere Informationen finden Sie unter Abonnieren von Lebenszyklusbenachrichtigungen.

Gültigkeitsdauer von Abonnements nachverfolgen

Stellen Sie sicher, dass Sie ein Abonnement verlängern, bevor es abläuft. Die maximale Lebensdauer für ein Abonnement ohne Outlook-Ressourcendaten beträgt 4230 Minuten (unter 3 Tage) und 1 Tag mit Ressourcendaten.

Wenn Sie die zuvor erteilte Berechtigung für ein Abonnement verlieren und das Abonnement in der Zwischenzeit abläuft, fordern Sie erneut die Berechtigung an, um ein neues Abonnement zu erstellen.

Nutzdaten der Benachrichtigungen empfangen

Je nach Abonnement können Benachrichtigungen Ressourcendaten enthalten. Abonnements mit Ressourcendaten ermöglichen es Ihnen, die Ressourcennutzlast zusammen mit der Benachrichtigung abzurufen, wodurch der Mehraufwand für einen separaten API-Aufruf zum Abrufen der geänderten Ressourcendaten vermieden wird.

Empfangen von Benachrichtigungen mit Ressourcendaten

Es folgt ein Beispiel für die Nutzdaten einer Benachrichtigung mit Ressourcendaten einer Nachricht-Ressource. Die Eigenschaften resource und resourceData entsprechen der Meldung instance, die die Benachrichtigung ausgelöst hat. Verwenden Sie die Eigenschaft encryptedContent, um die Ressourcendaten zu entschlüsseln.

{
    "value": [
      {
        "subscriptionId": "dfd11b2f-8222-4189-9545-4205c95d6235",
        "subscriptionExpirationDateTime": "2021-12-31T16:16:44.9907405+05:30",
        "changeType": "created",
        "resource": "Users('722effaf-0433-4272-9ac4-d5ec11c3cd77')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA=')",
        "clientState": "<<--SpecifiedClientState-->>",
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
        "encryptedContent": {
          "data": "<<--EncryptedContent-->>",
          "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
          "dataSignature": "Qw/9ubWeUYJPWWXvNiGgct2FkNG2MXTRm/BLUpJM66k=",
          "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
          "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "resourceData": {
          "@odata.type": "#microsoft.graph.message",
          "@odata.id": "Users('722effaf-0433-4272-9ac4-d5ec11c3cd77')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA=')",
          "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAGDUR8n\"",
          "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA="
        }
      }
    ]
    "validationTokens": ["<<--ValidationTokens-->>"]
}

Einzelheiten zum Validieren von Tokens und Entschlüsseln der Nutzlast finden Sie unter Änderungsbenachrichtigungen einrichten, die Ressourcendaten enthalten.

Es folgt ein Beispiel für eine entschlüsselte Nutzlast einer Benachrichtigung. Die entschlüsselte Nutzlast entspricht dem Outlook-Schema Nachricht. Die Nutzlast ähnelt der von einer GET-Nachricht zurückgegebenen Nutzlast. Die Nutzdaten einer Benachrichtigung enthalten jedoch nur die Eigenschaften, die mit einem $select-Parameter in der Eigenschaft Ressource des Abonnements angegeben sind. Nutzdaten einer Benachrichtigung für andere Outlook-Ressourcen wie Kontakt und Ereignis folgen den jeweiligen Schemas.

{
    "receivedDateTime@odata.type":"#DateTimeOffset",
    "receivedDateTime":"2021-12-30T10:53:35Z",
    "subject":"TEST MESSAGE FOR RICH NOTIFICATIONS",
    "bodyPreview":"Hello,\r\n\r\nWhat\u2019s up?\r\n\r\nThanks\r\nMegan",
    "importance@odata.type":"#microsoft.graph.importance",
    "importance":"normal",
    "from": {
        "@odata.type":"#microsoft.graph.recipient",
        "emailAddress": {
            "@odata.type":"#microsoft.graph.emailAddress",
            "name":"Megan Brown",
            "address":"Megan.Brown@microsoft.com"
        }
    }
}

Benachrichtigungen ohne Ressourcendaten empfangen

Benachrichtigungen ohne Ressourcendaten enthalten genügend Informationen, um GET-Aufrufe zu tätigen, um die Ressource zu erhalten. Abonnements für Benachrichtigungen ohne Ressourcendaten erfordern kein Verschlüsselungszertifikat, da die tatsächlichen Ressourcendaten nicht übermittelt werden.

Das nächste Beispiel zeigt die Nutzdaten einer Benachrichtigung, die einer Outlook-Ressource Nachricht entsprechen. Es enthält die Eigenschaften Ressource und ResourceData, die die Ressource darstellen, die die Benachrichtigung ausgelöst hat. Verwenden Sie die Eigenschaften Ressource und @odata.id, um Aufrufe an Microsoft Graph zu tätigen, um die Nutzlast für die Nachricht zu erhalten.

Hinweis

GET Aufrufe geben immer den aktuellen Status der Ressource zurück. Wenn die Ressource zwischen dem Zeitpunkt des Sendens der Benachrichtigung und dem Abrufen der Ressource geändert wird, gibt der Vorgang den Status der Ressource beim Abrufen zurück.

"value": [
 {
   "subscriptionId": "c6126aa3-0ed8-412f-a988-71e6cee627c4",
   "subscriptionExpirationDateTime": "2022-01-02T03:12:18.2257768+05:30",
   "changeType": "created",
   "resource": "Users/622eaaff-0683-4862-9de4-f2ec83c2bd98/Messages/AAMkAGUwNjQ4ZjIxAAA=",
   "resourceData": {
     "@odata.type": "#Microsoft.Graph.Message",
     "@odata.id": "Users/622eaaff-0683-4862-9de4-f2ec83c2bd98/Messages/AAMkAGUwNjQ4ZjIAAA=",
     "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAGDUUXn\"",
     "id": "AAMkAGUwNjQ4ZjIxAAA="
   },
   "clientState": "<<--SpecifiedClientState-->>",
   "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
 }
]

Beispiele

Beispiel 1: Erstellen eines Abonnements zum Abrufen von Änderungsbenachrichtigungen ohne Ressourcendaten, wenn der Benutzer eine neue Nachricht empfängt

Im folgenden Beispiel wird eine Benachrichtigung für eine Nachricht angefordert, die im Postfach des Benutzers erstellt wird.

Anforderung

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages",
    "expirationDateTime": "2021-07-07T21:42:18.2257768+00:00",
    "clientState": "secretClientState"
}

Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "5522bd62-7c96-4530-85b0-00b916f6151a",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientState",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-01T21:42:18.2257768Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": null,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": null,
    "encryptionCertificateId": null,
    "notificationUrlAppId": null
}

Beispiel 2: Erstellen eines Abonnements zum Abrufen von Änderungsbenachrichtigungen mit Ressourcendaten, wenn der Benutzer eine neue Nachricht erhält

Im folgenden Beispiel werden Benachrichtigungen mit Ressourcendaten für eine Nachricht abonniert, die im Postfach des Benutzers erstellt wird. Die Eigenschaften der Nachricht-Ressource, die in die Benachrichtigungsnutzlast eingeschlossen werden soll, werden mithilfe des $select-Abfrageparameters angegeben.

Anforderung

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages?$select=Subject,bodyPreview,importance,receivedDateTime,from",
    "expirationDateTime": "2022-01-01T21:42:18.2257768+00:00",
    "clientState": "secretClientValue",
    "includeResourceData": true,
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId"
}

Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "178eec5f-cf3c-4e7e-8a9c-8640deb5b5c5",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages?$select=Subject,bodyPreview,importance,receivedDateTime,from",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientValue",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-01T12:32:35.1582696Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": true,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId",
    "notificationUrlAppId": null
}

Beispiel 3: Erstellen eines Abonnements zum Abrufen von Änderungsbenachrichtigungen mit Ressourcendaten für eine Nachricht basierend auf einer Bedingung

Im folgenden Beispiel werden Benachrichtigungen mit Ressourcendaten für eine Nachricht abonniert, die im Ordner "Entwürfe" erstellt wird, die eine oder mehrere Anlagen enthält und von hoher Wichtigkeit ist.

Anforderung

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "me/mailfolders('Drafts')/messages?$select=Subject,bodyPreview&$filter=hasAttachments eq true AND importance eq 'High'",
    "expirationDateTime": "2022-01-01T21:42:18.2257768+00:00",
    "clientState": "secretClientValue",
    "includeResourceData": true,
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId"
}

Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "239dbc5f-cf3c-4e7e-8c9c-3340abc5b5c5",
    "resource": "me/mailfolders('Drafts')/messages?$select=Subject,bodyPreview&$filter=hasAttachments eq true AND importance eq 'High'",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientValue",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-20T12:32:35.1582696Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": true,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId",
    "notificationUrlAppId": null
}

Verwandte Inhalte