Outlook Streaming-Benachrichtigungen REST-API-Verweis (Vorschauversion)

  • Artikel

Gilt für: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Hinweis

Diese Version der Dokumentation deckt die Streaming-Benachrichtigungs-API in der Vorschauversion ab. Die Funktionen der Vorschauversion können vor der Fertigstellung geändert werden und können den Code, der sie verwendet, unterbrechen. Aus diesem Grund sollten Sie in der Regel nur eine Produktionsversion einer API in Ihrem Produktivcode verwenden. Falls verfügbar, ist v2.0 derzeit die bevorzugte Version.

Die Outlook Streaming Benachrichtigungen REST API sendet Benachrichtigungen über eine direkte Verbindung, damit Client-Anwendungen über Änderungen an den Postfachdaten des Benutzers informiert werden. Die Daten können in den Mail-, Kalender-, Kontakt- oder Aufgabendaten des Benutzers enthalten sein, die durch Azure Active Directory in Office 365 oder in Microsoft-Konten speziell in diesen Domänen gesichert sind: Hotmail.com, Live.com, MSN.com, Outlook.com und Passport.com.

Hinweis

Zur Vereinfachung des Verweises verwendet der Rest dieses Artikels Outlook.com, um diese Microsoft-Konto-Domänen mit einzuschließen.

Übersicht

Der Office 365 Streaming-Benachrichtigungsdienst stellt eine direkte Verbindung zu einem Client her und liefert Benachrichtigungen über Datenänderungen, die von einer Client-App angefordert werden.

Wenn eine App Benachrichtigungen für eine Art von Änderungsereignis auf einer bestimmten Ressource abonniert (z. B. Nachrichten im Posteingang des Benutzers), wird eine langlebige Verbindung zwischen dem Office 365-Server und dem Client hergestellt. Wenn ein auslösendes Ereignis eintritt (z. B. eine neue Nachricht im Posteingang), sendet der Office 365-Dienst eine Benachrichtigung an den Client. Der Client analysiert die Benachrichtigung und ergreift Maßnahmen entsprechend seiner Geschäftslogik, wie z.B. das Abrufen der neuen Nachricht und das Aktualisieren der ungelesenen Anzahl.

Vergleich von Streaming- und Push-Benachrichtigungen

Mail-, Kalender- und CRM-Apps verwenden normalerweise Benachrichtigungen, um ihren lokalen Cache, die entsprechenden Client-Ansichten oder das Backend-System bei Änderungen zu aktualisieren. Outlook unterstützt sowohl Streaming als auch Push- Benachrichtigungen. Benachrichtigungen. Für Push-Benachrichtigungen muss der Client einen Listener-Webdienst bereitstellen, um Benachrichtigungen vom Office 365-Server zu erhalten, während für Streaming-Benachrichtigungen nur eine direkte Verbindung zwischen dem Client und dem Office 365-Server erforderlich ist. Sobald eine Verbindung mit dem Server hergestellt ist, bleibt die Verbindung für einen bestimmten Zeitraum offen. Während dieser Zeit sendet der Client einmalig eine langlebige GetNotifications Anfrage. Wenn ein auslösendes Ereignis eintritt, kann der Server einfach eine Benachrichtigung als Teil des Antwortstreams senden. Dies wird so lange fortgesetzt, bis die Verbindung unterbrochen wird, der Client die Verbindung abbricht oder ein Problem im Netzwerk auftritt.

Verwenden Sie die REST-API für Streaming-Benachrichtigungen

Authentifizierung

Um Benachrichtigungen zu abonnieren, abzurufen und zu schließen, geben Sie die entsprechenden Bereiche für die Arten von Ressourcen an, über die Sie benachrichtigt werden möchten.

Minimal benötigter Bereich

Einer der folgenden Lese- / Schreibbereiche für die Zielressource:

Wie andere Outlook-REST-APIssollten Sie für jede Anforderung an die Outlook-Streaming-Benachrichtigungs-API ein gültiges Zugriffstoken angeben. Um ein Zugriffstoken zu erhalten, müssen Sie sich registriert und Ihre App identifiziert und die entsprechende Autorisierung erhalten haben.

Sie können mehr über einige optimierte Registrierungs- und Autorisierungs-Optionen für Sie herausfinden. Beachten Sie dies, wenn Sie mit den spezifischen Operationen in der Benachrichtigungs-API fortfahren.

Version der API

Derzeit befindet sich diese API im Vorschau-Status und ist nur im Beta-REST-API-Endpunkt verfügbar:

https://outlook.office.com/api/beta/

Ziel-Benutzer

API-Anfragen der Streaming-Benachrichtigungen werden immer im Namen des aktuellen Benutzers ausgeführt.

Streaming-Benachrichtigungs-Operationen

Änderungen in meiner Mail, meinem Kalender, meinen Kontakten oder Aufgaben abonnieren

Abonniert Streaming-Benachrichtigungen, wenn sich E-Mails, Kalenderereignisse, Kontakte oder Aufgaben in einem Office 365- oder Outlook.com-Postfach ändern. Dies ist der erste Schritt für einen Client, um Benachrichtigungen für eine Ressource (eine Entität oder Entitätensammlung) zu erhalten.

POST https://outlook.office.com/api/beta/me/subscriptions

Geben Sie im Anfragetext die folgenden erforderlichen Eigenschaften für eine Streaming-Abonnement-Anforderung an. Weitere Informationen finden Sie unter  Benachrichtigungsentitäten.

  • odata.type - Enthält "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription".

  • ChangeType  - Gibt die Art der zu überwachenden Ereignisse für diese Ressource an. Siehe ChangeType für die unterstützten Arten.

  • Ressource  - Gibt die Ressource an, die überwacht werden und Benachrichtigungen erhalten soll. Sie können optionale Abfrageparameter verwenden, $filter oder $select die Bedingungen für eine Benachrichtigung verfeinern oder spezifische Eigenschaften in eine umfangreiche Benachrichtigung aufnehmen. Im Folgenden sind die unterstützten Ressourcen aufgeführt:

    • Ein normaler Ordner oder Suchordner für Nachrichten, Ereignisse, Kontakte oder Aufgaben. Als Beispiele dienen:

      https://outlook.office.com/api/beta/me/mailfolders('inbox')/messages

      https://outlook.office.com/api/beta/me/taskfolders('{folder_id}')/tasks

    • Oder eine Entitätssammlung auf oberster Ebene mit Nachrichten, Ereignissen, Kontakten oder Aufgaben wie z.B.:

      https://outlook.office.com/api/beta/me/messages

      https://outlook.office.com/api/beta/me/events

      https://outlook.office.com/api/beta/me/contacts

      https://outlook.office.com/api/beta/me/tasks

Wenn die Abonnementsanforderung erfolgreich war, wird eine Abonnements-ID zurückgegeben. Standardmäßig läuft diese Abo-ID in 90 Minuten ab, es sei denn, der Client startet das Abhören von Benachrichtigungen über eine Verbindung. Solange die Verbindung besteht, wird das Abonnement automatisch verlängert.

Stichprobe für die Anforderung eines Abonnements

Die folgende Anforderung erstellt ein Streaming-Abonnement für erstellte, aktualisierte und gelöschte Änderungen für den Posteingang des Benutzers.

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
   ChangeType: "Created,Updated,Deleted"
}

Stichprobe für die Antwort auf ein Abonnement

Eine erfolgreiche Antwort gibt HTTP 201 zurück und enthält die Abonnements-ID. Nachfolgend sehen Sie ein Antwortbeispiel:

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('RUM4OEJFNUIQUQ4MQ==')",
    "Id":"RUM4OEJFNUIQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Bedingungen für Benachrichtigung verfeinern

Sie können Benachrichtigungen auf eine Teilmenge von Elementen beschränken, indem Sie eine $filter Klausel verwenden. Der folgende Abonnementantrag erzeugt z.B. ein Abonnement, das nur dann eine Benachrichtigung auslöst, wenn Änderungen an Nachrichten mit dem Betreff-Feld "Nachträge" vorgenommen werden.

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
   ChangeType: "Created,Updated,Deleted"
}

Eine erfolgreiche Abonnement-Antwort sieht so aus:

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('MjcwOUQ2MjEtQUQ4MQ==')",
    "Id":"MjcwOUQ2MjEtQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Rich-Streaming-Benachrichtigungen abonnieren

Ein Abonnement, das nur für eine Ressourcensammlung eingerichtet wurde, gibt die ID einer geänderten Ressourceninstanz zurück. Sie müssen die Eigenschaften dieser Instanz separat abrufen. Die erste Abonnement-Anfrage oben ist ein Beispiel für diese Art von Abonnement. Der Benachrichtigungsstrom im nächsten Abschnitt zeigt nur die Ressourcen-ID an, die in einer Benachrichtigung zurückgegeben wird.

Sie können alternativ einen $select Parameter in der Abonnementanfrage verwenden, die Eigenschaften angeben, an denen Sie Interesse haben, und diese Eigenschaftswerte auch in Streaming-Benachrichtigungen zurückgeben lassen.

Das Folgende ist ein Beispiel, das Streaming-Benachrichtigungen anfordert, die die Eigenschaft Subject umfassen, wenn ein Ereignis erzeugt wurde:

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
    @odata.type:"#Microsoft.OutlookServices.StreamingSubscription",
    Resource: "https://outlook.office.com/api/beta/me/events?$select=Subject",
    ChangeType: "Created"
}

Nach erfolgreichem Abonnieren von Rich-Streaming-Benachrichtigungen, hören Sie Benachrichtigungen zu, um die Themen- Eigenschaft in Rich-Benachrichtigungs-Nutzlastenzu erhalten.

Benachrichtigungen abhören

Der Client erstellt eine ausstehende POST-Verbindung für die angegebenen Abonnements, um den Server aufzufordern, Streaming-Benachrichtigungen zu starten.

POST https://outlook.office.com/api/beta/Me/GetNotifications

Diese POST-Anfrage wird erst abgeschlossen, wenn die angegebene ConnectionTimeoutinMinutes erreicht ist und der Server den JSON-Blob in der Antwort beendet, oder wenn es andere Probleme gibt und entweder der Client oder der Server die Verbindung schließt.

Solange die Verbindung geöffnet ist, werden alle Abonnements, die die Verbindung nutzen, automatisch erneuert. Wenn die Verbindung beendet wird, verfallen diese Abonnements ebenfalls in 90 Minuten, es sei denn, der Client baut eine neue Verbindung für diese Abonnements auf.

Stellen Sie sicher, dass Ihr Code, der diese POST-Anfrage erzeugt, den Rückgabestatuscode HTTP 404 Not foundverarbeitet, der zurückgegeben wird, wenn ein bestimmtes Abonnement tatsächlich abgelaufen ist. Wenn das passiert, fordern Sie ein neues Abonnement an, bevor Sie erneut seinen Benachrichtigungen zuhören.

Benötigte Textparameter Typ Beschreibung
ConnectionTimeoutInMinutes int32 Die Anzahl der Minuten, die die Verbindung am Leben bleiben soll.
KeepAliveNotificationIntervalInSeconds int32 Das Intervall, in dem der Server Keep-Alive-Benachrichtigungen sendet, um dem Client mitzuteilen, dass die Verbindung offen bleibt.
SubscriptionIds Sammlung (Zeichenfolge) IDs der Abonnements, die über diese Verbindung benachrichtigt werden.

Stichprobe für Abhör-Anforderungen

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg=="
   ]
}

Sie können dieselbe langlebige Verbindung verwenden, um Benachrichtigungen für mehrere Abonnements abzuhören, indem Sie mehr als eine Abonnement-ID in die POST-Anfrage aufnehmen.

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg==",
       "Dc4NS04MTg2LUYwRjFFNUVFNTNDRgN0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtN=="
   ]
}

Stichprobe für Benachrichtigungsstrom

Sobald der Dienst eingerichtet ist, erhält der Client den Beginn der Benachrichtigungen JSON blob.

{
    {"@odata.context":"https://outlook.office.com/api/beta/metadata#Notifications", 
    "value": [

Der Server sendet in festgelegten Intervallen eine Keep-Alive-Benachrichtigung, um die Verbindung offen und aktiv zu halten. Der Client stellt dieses Intervall in der KeepAliveNotificationIntervalInSeconds Eigenschaft ein. Das Format der Keep-Alive-Benachrichtigung ist wie folgt:

{
    "@odata.type": "#Microsoft.OutlookServices.KeepAliveNotification",
    "Status": "OK"
}

Wenn eine verfolgte Änderung auf dem Server auftritt, sendet der Server eine Benachrichtigung an den Client über die Verbindung. In jeder Benachrichtigung setzt der Server die Eigenschaft SubscriptionExpirationDateTime und erneuert sie immer wieder, solange die vorherige Benachrichtigung erfolgreich war.

{ 
    "@odata.type": "#Microsoft.OutlookServices.Notification",
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    "SubscriptionExpirationDateTime": "2016-09-09T18:36:42.3454926Z",
    "SequenceNumber": 9, 
    "ChangeType": "Created", 
    "Resource": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
    "ResourceData": { 
        "@odata.type": "#Microsoft.OutlookServices.Message", 
        "@odata.id": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
        "@odata.etag": "W/\"CQAAABYAAAB+0z/4Ly/1ToDr5FGl5k99AAABl5Do\"", 
        "Id": "AAMkADdlAA=" 
    } 
}

Wenn Ihre Anwendung mehreren Benachrichtigungen über dieselbe langlebige Verbindung zuhört, können Sie das Feld SubscriptionId verwenden, um festzustellen, welches Abonnement die Benachrichtigung gesendet hat.

Hinweis

Die zweite und die danach folgende Benachrichtigung vom Server hat ein führendes Komma vor der öffnenden eckigen Klammer, um die Benachrichtigung zu einer gültigen JSON zu machen.

,{
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    ...
}

Beispiel für die Nutzlast einer Rich-Benachrichtigung

Wenn Ihr Abonnementantrag bestimmte Eigenschaften angibt, die zurückgegeben werden sollen, umfassen die Benachrichtigungs-Nutzlasten die Werte dieser Eigenschaften. Wenn Sie das obige Beispiel verwenden, um Rich-Benachrichtigungenzu abonnieren, kann eine Rich-Benachrichtigungs-Nutzlast mit der Eigenschaft Subject wie folgt aussehen:

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Notifications",
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "QjQzNzAwBQQ==",
      "SubscriptionExpirationDateTime": "2017-01-18T00:57:28.6134733Z",
      "SequenceNumber": 1,
      "ChangeType": "Created",
      "Resource": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
      "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Event",
        "@odata.id": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

Schließen Sie die Verbindung

Wenn das in der ConnectionTimeoutInMinutes Eigenschaft angegebene Zeitlimit erreicht ist, schließt der Server die Verbindung und sendet das Ende des JSON-Blobs wie folgt.

    ]
}

Die Verbindung kann unter anderen Umständen unterbrochen werden, z.B. bei Netzwerkproblemen und Änderungen am Server wie Neustarts. Der Client kann anhand der Keep-Alive-Benachrichtigungen feststellen, ob die Verbindung noch aktiv ist oder abgebrochen wurde. Im letzteren Fall sollte der Client versuchen, die Verbindung mit der vorhandenen Abonnement-ID wiederherzustellen. Wenn die Abonnement-ID abgelaufen ist, sollte eine neue Abonnement-Anfrage gestellt werden, um die Verbindung wieder herzustellen.

Wenn der Client kein Abonnement mehr hören möchte, kann er die POST-Anfrage abbrechen und die Verbindung aufgeben. Wenn der Server das nächste Mal versucht, eine Benachrichtigung zu senden, erhält er einen Fehler, entdeckt den Abbruch der Verbindung, stoppt die Keep-Alive-Benachrichtigungen und schließt die Verbindung.

Benachrichtigungs-Entitäten und Aufzählungen

Abonnement

Stellt das Basisabonnement dar. Dies ist eine abstrakte Basisklasse.

Basistyp: Entität

Eigenschaft Typ Beschreibung Beschreibbar? Filterbar
Ressource Zeichenfolge Gibt die Ressource an, die auf Änderungen überwacht wird. Ja Nicht zutreffend
ChangeType ChangeType Gibt die Art der Ereignisse an, die eine Benachrichtigung auslösen werden. Siehe ChangeType für die unterstützten Arten. Ja Nicht zutreffend

Benachrichtigung

Stellt eine an den Client gesendete Benachrichtigung dar.

Basistyp: Entität

Eigenschaft Typ Beschreibung Beschreibbar? Filterbar
SubscriptionId Zeichenfolge Eindeutiger Bezeichner für das Abonnement. Nein Nicht zutreffend
SequenceNumber int32 Gibt den Sequenzwert der Änderungs-Benachrichtigung an. Nein Nicht zutreffend
ChangeType Zeichenfolge Gibt die Art des Ereignisses an, das die Benachrichtigung ausgelöst hat. Siehe ChangeType für die unterstützten Arten. Nein Nicht zutreffend
Ressource Zeichenfolge Gibt das Ressourcenelement an, das auf Änderungen überwacht wird Nein Nicht zutreffend
ResourceData Entität Identifiziert die Entität, die sich geändert hat. Dies ist eine Navigationseigenschaft Nein Nicht zutreffend

ChangeType

Eine Aufzählung, die die Arten von Ereignissen angibt, die bei unterstützten Ressourcen auftreten, die eine Benachrichtigung auslösen können.

Unterstützte Werte:

  • Anerkennung
  • Erstellt
  • Gelöscht
  • Entgangen. Eine Missed Benachrichtigung erfolgt, wenn der Benachrichtigungsdienst die angeforderte Benachrichtigung nicht senden kann.
  • Aktualisiert

Nächste Schritte

Egal, ob Sie bereit sind, eine App zu erstellen oder einfach nur mehr darüber erfahren möchten, wir haben alles im Griff.

Oder erfahren Sie mehr über die Verwendung der Office 365-Plattform: