Verwenden von Webhooks für E-Mail-, Kalender- und Kontakt-REST-BenachrichtigungenUse webhooks for mail, calendar and contacts REST notifications

Wir freuen uns über die Einführung der Outlook-Benachrichtigungen-REST-API für E-Mail, Kalender und Kontakte in Office 365 und Outlook.com. Die Outlook-Benachrichtigungen-REST-API verwendet einen Webhook-Mechanismus zum Übermitteln von Benachrichtigungen an Clients. Ein Client in diesem Zusammenhang ist tatsächlich ein Drittanbieter-Webdienst, der eine eigene Benachrichtigungs-URL konfiguriert, an die Office 365 per Push diese Benachrichtigungen übermittelt. E-Mail- und Kalender-Apps verwenden normalerweise Benachrichtigungen für die Aktualisierung des lokalen Cache und den entsprechenden Clientansichten bei Änderungen. Darüber hinaus verwenden CRM-Apps in der Regel Benachrichtigungen, um die eigenen Systeme entsprechend den an relevanten Unterhaltungen vorgenommenen Änderungen zu aktualisieren.We are excited about the release of the Outlook Notifications REST API for mail, calendar, and contacts in Office 365 and Outlook.com. The Outlook Notifications REST API uses a webhook mechanism to deliver notifications to clients. A client, in this context, is actually a third-party web service that configures its own notification URL to which Office 365 pushes these notifications. Mail and calendaring apps typically use notifications to update their local cache and corresponding client views upon changes. Additionally, CRM apps usually use notifications to update their systems with changes to relevant conversations.

Beim Verwenden der Outlook-Benachrichtigungen-REST-API kann eine App nun Benachrichtigungen zu einer bestimmten Ressource (z. B. Nachrichten im Posteingang) abonnieren, um über Änderungen an der Ressource informiert zu werden. Sobald der Outlook-Benachrichtigungsdienst die Abonnementanforderung akzeptiert, übermittelt er die Benachrichtigungen per Push über Webhooks an die in dem Abonnement angegebene Benachrichtigungs-URL. Die App führt dann Aktionen gemäß der Geschäftslogik aus (z. B. Abrufen neuer Nachrichten, Aktualisieren der Anzahl ungelesener Nachrichten, Entfernen gelöschter Nachrichten aus der Clientansicht).Using the Outlook Notifications REST API, an app can now subscribe to notifications of a specific resource (such as messages in the Inbox) to get informed about changes to the resource. Once the Outlook notifications service accepts the subscription request, it pushes notifications through webhooks to the notification URL specified in the subscription. The app then takes action according to its business logic (e.g. fetches new messages, update unread count, remove deleted messages from the client view, etc.).

Apps müssen ihre Abonnements verlängern, bevor diese ablaufen. Abonnements können auch jederzeit gekündigt werden, um keine weiteren Benachrichtigungen zu erhalten.Apps need to renew their subscriptions before they expire. They can also unsubscribe at any time to stop getting notifications.

Im Folgenden wird der Abonnementprozess beschrieben.Let's take a look at the subscription process.

Erstellen eines AbonnementsCreating a subscription

Um Benachrichtigungen für eine bestimmte Entitätssammlung zu erhalten, muss in einem ersten Schritt ein Abonnement erstellt werden. Der Abonnementprozess läuft wie folgt ab:Creating a subscription is the first step needed to start receiving notifications for a specific entity collection. The subscription process is as follows:

  1. Der Client sendet eine Abonnementanforderung (POST) für eine bestimmte Entitätssammlung.Client sends a subscription (POST) request for a specific entity collection.
  2. Der Outlook-Benachrichtigungsdienst überprüft die Anforderung, überprüft die Benachrichtigungs-URL und sendet die Antwort an den Client.Outlook notifications service verifies the request, validates the notification URL and sends response to the client.
    1. Erfolg: Der Dienst erstellt ein Abonnement mit eindeutiger ID und sendet die entsprechende Antwort.Success: creates subscription with unique ID and sends corresponding response.
    2. Fehler: Der Dienst sendet eine Fehlerantwort mit Fehlercode und Details.Failure: sends error response with error code and details.
  3. Der Client muss die Abonnement-ID speichern, um eine Benachrichtigung mit dem entsprechenden Abonnement korrelieren zu können.Client must store the subscription ID in order to correlate notification with corresponding subscription.

Merkmale von AbonnementsCharacteristics of subscriptions

  • Abonnements können für Entitätssammlungen (z. B. Nachrichten, Ereignisse und Kontakte) ausgeführt werden.Subscriptions can be performed for entity collections (such as messages, events, and contacts).
    • Bestimmte Ordner einschließlich Suchordner:Specific folder including search folders:
      • https://outlook.office.com/api/v2.0/me/mailfolders('inbox')/messages
    • Sammlung auf oberster Ebene:Top level collection:
      • https://outlook.office.com/api/v2.0/me/events
      • https://outlook.office.com/api/v2.0/me/messages
  • Ein Abonnement bleibt während der Gültigkeitsdauer bestehen. Dies ist ein Vorteil gegenüber unseren älteren SOAP-API-Exchange-Webdiensten (EWS), in denen Abonnements aufgrund von Problemen auf Serverseite wie Anwendungspoolabstürzen oder Serverausfällen verloren gehen können.A subscription persists throughout its lifetime. This is an advantage over our older SOAP API Exchange Web Services (EWS) where subscriptions can be lost because of problems on the server side such as application pool crashes or server failover.
  • Zum Erstellen eines Abonnement sind Lesebereiche der Ressource erforderlich. Es ist z. B. erforderlich, dass mail.read Benachrichtigungen über Nachrichten im Posteingang erhält.Creating a subscription requires read scope to the resource; e.g. mail.read is required to get notifications on Inbox messages.
  • Abonnements funktionieren für normale Order wie Posteingang sowie für Suchordner.Subscriptions work on regular folders such as Inbox as well as search folders.
  • Abonnements laufen ab. Der aktuelle maximale Ablaufzeitpunkt ist 3 Tage ab dem Zeitpunkt der Erstellung. Apps müssen ihre Abonnements vor dem Ablaufzeitpunkt erneuern, andernfalls ist ein erneutes Abonnieren erforderlich.Subscriptions expire. The current maximum expiration time is 3 days from time of creation. Apps need to renew their subscriptions before expiration time otherwise they will need to re-subscribe.

Überprüfung der Benachrichtigungs-URLNotification URL validation

Der Outlook-Benachrichtigungsdienst überprüft die Benachrichtigungs-URL in einer Abonnementanforderung vor dem Erstellen eines neuen Abonnements. Der Überprüfungsprozess läuft wie folgt ab:The Outlook notifications service validates the notification URL in a subscription request before creating a new subscription which occurs as follows:

  1. Der Outlook-Benachrichtigungsdienst sendet eine POST-Anforderung an die Benachrichtigungs-URL:Outlook notifications service sends a POST to the notification URL:

     POST https://{notificationUrl}?validationtoken={TokenDefinedByService}
     ClientState: {Data sent in ClientState value in subscription request (if any)}
    
  2. Der Webhooks-Dienst muss innerhalb von 5 Sekunden eine 200-Antwort mit dem validationtoken-Wert im Textbereich vom Typ plain/text bereitstellen. Das Überprüfungstoken ist eine zufällige Zeichenfolge, die vom Webhook verworfen werden sollte, nachdem es in der Antwort bereitgestellt wurde.Webhooks service must provide a 200 response with the validationtoken value in its body as type plain/text within 5 seconds. The validation token is a random string that should be discarded by the webhook after providing it in the response.

Beispiel für Anforderung zum Erstellen eines AbonnementsSample create subscription request

POST https://outlook.office.com/api/v2.0/me/subscriptions  HTTP/1.1
Content-Type: application/json
{
  "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
  "Resource": "https://outlook.office.com/api/v2.0/me/mailfolders('inbox')/messages",
  "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",  
  "ChangeType": "Created, Updated, Deleted",
  "SubscriptionExpirationDateTime": "2015-11-20T23:05:01.9420124Z"
  "ClientState": "MySecretClientStateString"
}

Die @odata.type, Resource-, NotificationURL- und ChangeType-Eigenschaften sind erforderlich, während die übrigen optional sind. Informationen zu Eigenschaftsdefinitionen und -werten finden Sie unter https://msdn.microsoft.com/office/office365/APi/notify-rest-operations.The @odata.type, Resource, NotificationURL and ChangeType properties are required while the rest are optional. Refer to https://msdn.microsoft.com/office/office365/APi/notify-rest-operations for property definitions and values.

Beispiel für Antwort auf Anforderung zum Erstellen eines AbonnementsSample create subscription response

Abonnementantwort ist eine Wiedergabe der Anforderung mit den folgenden zusätzlichen Eigenschaften und Werten:Subscription response is a replay of the request with the following additional properties and values:

  • Id – Eindeutiger Bezeichner pro Abonnement. Client muss diesen Bezeichner zum Abstimmen mit den Benachrichtigungen speichern.Id - A unique identifier per subscription. Client needs to store this identifier to match it with notifications.
  • SubscriptionExpirationDateTime Die tatsächliche Ablaufzeitdauer, falls nicht in der Anforderung angegeben, oder die in der Anforderung angegebene Ablaufdauer war größer als 3 Tage.SubscriptionExpirationDateTime The actual expiration time in case it was not specified in the request, or the time specified in the request was greater than three days.
  • ChangeType fügt zwei Arten von Benachrichtigungen hinzu: Acknowledgment und Missed. Diese werden im Abschnitt „Benachrichtigung“ erläutert.ChangeType adds two notification types: Acknowledgment and Missed. They will be explained in the notification section.

Die oben genannte Beispielanforderung generiert eine Antwort, die wie folgt aussieht:For example, the sample request above generates a response like the following:

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Subscriptions/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('user@contoso.com')/subscriptions('NDc0MEE4...QQ==')",
  "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
  "ChangeType": "Created, Updated, Deleted, Acknowledgment, Missed",
  "ClientState": "MySecretClientStateString",
  "Id": "NDc0MEE4...QQ==",
  "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  "Resource": "https://outlook.office.com/api/v2.0/me/folders('inbox')/messages",
  "SubscriptionExpirationDateTime": "2015-11-20T23:05:01.9420124Z"
}

Verlängern eines AbonnementsRenewing a subscription

Der Client kann ein Abonnement mit einem bestimmten Ablaufdatum (von bis zu drei Tagen ab dem Zeitpunkt der Anforderung) verlängern. Die SubscriptionExpirationDateTime-Eigenschaft ist optional. Wenn kein Wert angegeben ist, wird das Abonnement um 3 Tage ab dem Zeitpunkt der Anforderung erneuert.The client can renew a subscription to the specified expiration date (up to three days from the time of request). The SubscriptionExpirationDateTime property is optional. If no value is specified, it renews to 3 days from the time of the request.

Beispiel für Anforderung zum Erneuern eines AbonnementsSample renew subscription request

PATCH https://outlook.office.com/api/v2.0/me/subscriptions('NDc0MEE4...QQ==') 

{
  "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
  "SubscriptionExpirationDateTime": "2015-11-22T23:16:31.3604491Z"
}

Beispiel für Antwort auf Anforderung zum Erneuern eines AbonnementsSample renew subscription response

Die Antwort auf Anforderung zum Erneuern eines Abonnements ist eine Wiedergabe der Anforderung zum Erstellen eines Abonnements mit dem neuen Ablaufzeitpunkt.THe renew response is a replay of the create subscription response with the new expiration date-time.

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Subscriptions/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('user@contoso.com')/subscriptions('NDc0MEE4...QQ==')",
"@odata.type": "#Microsoft.OutlookServices.PushSubscription",
  "ChangeType": "Created, Updated, Deleted, Acknowledgment, Missed",
  "ClientState": "MySecretClientStateString",
  "Id": "NDc0MEE4...QQ==",
  "Resource": "https://outlook.office.com/api/v2.0/me/folders('inbox')/messages",
  "SubscriptionExpirationDateTime": "2015-11-22T23:16:31.3604491Z"
}

Kündigen eines AbonnementsUnsubscribe

Der Client kündigt ein Abonnement, indem das Abonnement unter Verwendung der ID gelöscht wird.The client unsubscribes from a subscription by deleting the subscription using its ID.

DELETE https://outlook.office.com/api/v2.0/me/subscriptions('NDc0MEE4...QQ==')

Eine erfolgreiche Antwort wird mit einem HTTP-204 No Content-Antwortcode angegeben.A successful response is indicated by an HTTP 204 No Content response code.

BenachrichtigungenNotifications

Sobald ein Abonnement eingerichtet wurde, erhält der Client Benachrichtigungen über Änderungen im Zusammenhang mit der entsprechenden Ressource über ein Webhook an die Benachrichtigungs-URL gemäß dem angegebenen Änderungstyp des Clients (z. B. Changed).Once a subscription is established, the client will start receiving notifications for changes related to the corresponding resource via a webhook to its notification URL, according to the client's specified change type (such as Changed).

Wahrscheinlich haben Sie festgestellt, dass die Abonnementantwort über zwei weitere Änderungstypen verfügt: Missed und Acknowledgment. Dies sind spezielle Typen von Benachrichtigungen, die wie folgt verwendet werden:You have probably noticed that the subscription response has two additional change types - Missed and Acknowledgment. They are special types of notifications that are used as follows:

  • Die Benachrichtigungsdienste senden eine Missed-Benachrichtigung, wenn der Dienst die angeforderten Benachrichtigungen nicht senden kann. Obwohl dies für Clients hilfreich ist, um diese Benachrichtigung zu verarbeiten, wird dieses Thema in späteren erweiterten Artikeln erläutert.The notifications services send a Missed notification if the service is unable to send out the requested notifications. Although it is good for clients to handle this notification, its discussion will be part of advanced topics in a later post.
  • Acknowledgement-Benachrichtigung ist veraltet, da sie durch den Überprüfungsvorgang der Benachrichtigungs-URL ersetzt wurde. Wir arbeiten daran, diese aus der Abonnementantwort zu entfernen.Acknowledgement notification has been deprecated because it was replaced by the notification URL validation process. We are in the process of removing it from the subscription response.

StrukturStructure

Jede Benachrichtigung weist unabhängig vom Typ die folgende Struktur auf:Each notification has the following structure, regardless of its type:

  • ClientState-Header: NUR, wenn der Client die ClientState-Eigenschaft in der Abonnementanforderung angegeben hat.ClientState header: ONLY if the client specified the ClientState property in the subscription request.
  • SubscriptionId: Die ID für das Abonnement, zu dem diese Benachrichtigung gehört.SubscriptionId: The ID for the subscription to which this notification belongs.
  • SubscriptionExpirationDateTime: Die Ablaufzeit für das Abonnement.SubscriptionExpirationDateTime: The expiration time for the subscription.
  • ChangeType: Der Ereignistyp, der die Benachrichtigung ausgelöst hat. (Z. B. Created bei Erhalt einer E-Mail oder Update, wenn eine Nachricht als gelesen markiert wird.)ChangeType: The event type that caused the notification (e.g. Created on mail receive, or Update on marking a message read, etc.).
  • SequenceNumber: Dient zur Identifizierung, wenn der Client eine Benachrichtigung verpasst hat. Der Umgang der Sequenznummer auf dem Client wird später im Rahmen der erweiterten Themen erläutert.SequenceNumber: To help identify if a notification was missed by the client. Handling sequence number on the client will be discussed as part of advanced topics in a later post.

Darüber hinaus verfügt eine Benachrichtigung, die mit einer Ressourcenänderung einhergeht (z. B. Empfangen, Lesen oder Löschen einer Nachricht), eine zusätzliche ResourceData-Eigenschaft, die die ID des Elements enthält, das geändert wurde. Ein Client kann diese ID verwenden, um dieses Element entsprechend der Geschäftslogik zu behandeln (z. B. dieses Element abzurufen, den Ordner zu synchronisieren).Additionally, a notification related to a resource change (such as receiving, reading or deleting a message) has an additional ResourceData property that contains the ID of the item that was changed. A client can use this ID to handle this item according to its business logic (e.g. fetch this item, sync its folder, etc.).

BeispielbenachrichtigungenSample notifications

Benachrichtigung über das Empfangen von E-MailsReceive email notification

Wenn der Benutzer eine neue Nachricht im Posteingang empfängt, sendet der Benachrichtigungsdienst eine Benachrichtigung mit einem ChangeType-Element, das auf Created festgelegt ist.When the user receives a new message in the Inbox, the notifications service sends a notification with ChangeType set to Created.

{
  "value": [
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "NDc0MEE4...QQ==",
      "SubscriptionExpirationDateTime": "2015-11-20T23:16:31.3604491Z",
      "SequenceNumber": 8,
      "ChangeType": "Created",
      "Resource": "https://outlook.office365.com/api/v2.0/Users('user@contoso.com')/Messages('AAMkAGY1...AAA=')",
      "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Message",
        "@odata.id": "https://outlook.office365.com/api/v2.0/Users('user@contoso.com')/Messages('AAMkAGY1...AAA=')",
        "@odata.etag": "W/\"CQAAABYAAABU4oDY3YDWSanCtdlMJCDOAADe14EA\"",
        "Id": "AAMkAGY1...AAA="
      }
    }
  ]
}

Benachrichtigung über das Lesen von E-MailsRead email notification

Wenn der Benutzer eine Nachricht als gelesen markiert hat, sendet der Benachrichtigungsdienst eine Benachrichtigung mit einem ChangeType-Element, das auf Updated festgelegt ist.When the user marks a message read, the notifications services sends a notification with the ChangeType set to Updated.

{
  "value": [
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "NDc0MEE4...QQ==",
      "SubscriptionExpirationDateTime": "2015-11-20T23:16:31.3604491Z",
      "SequenceNumber": 2,
      "ChangeType": "Updated",
      "Resource": "https://outlook.office365.com/api/v2.0/Users('user@contoso.com')/Messages('AAMkAGY1...AAA=')",
      "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Message",
        "@odata.id": "https://outlook.office365.com/api/v2.0/Users('user@contoso.com')/Messages('AAMkAGY1...AAA=')",
        "@odata.etag": "W/\"CQAAABYAAABU4oDY3YDWSanCtdlMJCDOAADe14EA\"",
        "Id": "AAMkAGY1...AAA="
    }
  ]
}

Verpasste BenachrichtigungenMissed notification

{
  "value": [
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "NDc0MEE4...QQ==",
      " SubscriptionExpirationDateTime": "2015-11-20T23:16:31.3604491Z ",
      "SequenceNumber": 1,
      "ChangeType": "Missed"
    }
  ]
}

Nächste SchritteNext steps

Wir freuen uns wirklich über die Outlook-Benachrichtigungen-REST-API und Webhooks für E-Mail, Kalender und Kontakte. Testen Sie sie, und und senden Sie uns Ihr Feedback an UserVoice. Dies hilft uns dabei, unsere APIs zu verbessern und somit angenehme Erfahrungen in Apps zu gewährleisten.We are really excited about the Outlook Notification REST API and webhooks for mail, calendar and contacts. Try them out and send us feedback on UserVoice. This will help us improve our APIs and let you create delightful experiences in your apps.