Abonnieren Sie Webhooks, um Änderungsbenachrichtigungen zu erhalten

  • Artikel

Gilt für: Consumer Notizbücher auf OneDrive

Halten Sie sich über Änderungen, die Ihre Benutzer in OneNote vornehmen, auf dem Laufenden, indem Sie sich für Webhooks anmelden.

Wenn Sie über eine Webanwendung oder einen Webservice verfügen, der einen öffentlichen Endpunkt anzeigt, können Sie nahezu in Echtzeit Benachrichtigungen erhalten, wenn Änderungen an den persönlichen OneNote-Notebooks Ihrer Benutzer auf OneDrive vorgenommen werden.

Benachrichtigungen werden gesendet, wenn eine Änderung in einem Notizbuch vorgenommen wird, das einem Ihrer Benutzer gehört. Dazu gehören Änderungen auf jeder Ebene der Notebook-Hierarchie, einschließlich Änderungen am Seiteninhalt.

Benachrichtigungen enthalten keine detaillierten Informationen über Änderungen oder Benutzer. Sie warnen Sie, wenn eine Änderung vorgenommen wird, damit Ihr Event-Handler nach bestimmten Details fragen kann. Der Webhooks-Dienst unterstützt keine feinkörnigen Abonnements für bestimmte Arten von Änderungen oder Ressourcen.

Benachrichtigungen werden als POST-Anforderungen gesendet, die ein JSON-Objekt enthalten, wie im folgenden Beispiel gezeigt.

{
  "value":[
    {
      "subscriptionId":"client-id-of-your-registered-application",
      "userId":"id-of-the-user-who-owns-the-changed-resource" 
    }
  ]
}

Ihr Dienst muss auf die Benachrichtigung umgehend mit einem der folgenden HTTP-Statuscodes reagieren:

  • 200 OK
  • 202 Akzeptiert
  • 204 kein Inhalt

Wenn wir die Antwort nicht erhalten, versuchen wir es ein paar Mal mit exponentiellem Backoff und verwerfen schließlich die Nachricht.

Weitere Informationen zu Benachrichtigungen

  • Die Benachrichtigungen werden auf den Inhalt Ihrer Benutzer ausgerichtet, unabhängig davon, wer die Änderung vorgenommen hat. Es werden keine Benachrichtigungen über Änderungen an Inhalten gesendet, die mit Ihren Benutzern geteilt werden. Wenn also Bob (nicht Ihr Benutzer) eine Änderung an einem Notizbuch von Alice (Ihrem Benutzer) vornimmt, erhalten Sie eine Benachrichtigung mit der Benutzer-ID von Alice. Sie erhalten keine Benachrichtigung, wenn Alice Bobs Notizbuch ändert.

  • Die userId in der Benachrichtigung entspricht der ID, die über den X-AuthenticatedUserId Header der OneNote-API-Antworten zurückgegeben wird.

  • Änderungen, die innerhalb kurzer Zeit vorgenommen werden, können in einer einzigen Meldung zusammengefasst werden.

  • Die Benachrichtigung erfolgt in der Regel innerhalb weniger Minuten nach der Änderung. Diese Latenz stellt sicher, dass Änderungen für die API verfügbar sind, auch wenn die Änderung möglicherweise sofort im Client verfügbar ist.

Benachrichtigungs-Workflow

Ein typischer High-Level-Benachrichtigungs-Workflow läuft in etwa so ab:

  1. Änderungen werden an einem Notebook vorgenommen, das einem Ihrer Benutzer gehört.
  2. OneNote sendet eine oder mehrere POST-Anfragen an Ihre registrierte Callback-URL. Jede POST-Anforderung repräsentiert eine oder mehrere Änderungen.
  3. Ihr Dienst antwortet auf jede POST-Anfrage mit einem 200, 202 oder 204 HTTP-Statuscode.
  4. Die Benachrichtigungen lösen einen Ereignisbehandler in Ihrer Callback-API aus.
  5. Sie fragen den OneNote-Service nach detaillierten Änderungen ab.

Die Abfrage nach dem Zeitstempel der letzten Änderung ist der beste Weg, um sicherzustellen, dass Sie alle Änderungen erfassen. Speichern Sie den Zeitstempel der letzten Zeitänderung lastModifiedTime aus den Ergebnissen und verwenden Sie ihn in Ihrer nächsten Änderungsabfrage.

Diese Anfrage verwendet die Eigenschaft lastModifiedTime, um alle Seiten zurückzusenden, die sich seit Ihrem gespeicherten Zeitstempel geändert haben:

GET ../me/notes/pages?filter=lastModifiedTime%20ge%20{stored-iso-8601-timestamp}

Nachdem Sie nach Änderungen gefragt haben, aktualisieren Sie Ihren gespeicherten Zeitstempel mit der neuesten lastModifiedTime.

Hinweis

Der Webhooks-Dienst ist nicht als Sync-Mechanismus gedacht. Sie sollten regelmäßig nach Änderungen fragen, falls eine Benachrichtigung nicht gesendet oder empfangen werden kann.

So abonnieren Sie den Webhooks-Service

Um den OneNote Webhooks-Dienst zu abonnieren, müssen Sie dies tun:

  • Registrieren Sie eine Callback-URL, die ein öffentlicher Endpunkt ist (HTTP oder HTTPS) wo Sie HTTP-POST-Anfragen vom OneNote-Webhooks-Dienst erhalten. Der Webhooks-Dienst folgt nicht den HTTP-Redirects.

  • Fordern Sie die folgenden Berechtigungen für Ihre Anwendung an:

    • wl.offline_access (Microsoft-Account-Berechtigung)
    • office.onenote, office.onenote_update_by_app, oder office.onenote_update für die OneNote-API, je nachdem, was Ihre Anwendung tut.office.onenote_create

Wenn Sie bereit sind, sich anzumelden, kontaktieren Sie uns unter @onenotedev. Jemand aus unserem Team wird mit Ihnen zusammenarbeiten, um Sie einzurichten.

Wenn sich Ihre Benutzer bei Ihrer Anwendung registrieren, sollten Sie in ihrem Namen die OneNote-API aufrufen (zum Beispiel: GET ../me/notes/notebooks). Dieser Anruf führt zu Folgendem:

  • Stellen Sie sicher, dass OneNote den Benutzer für Rückrufbenachrichtigungen registriert.
  • Ermöglicht das Abrufen und Speichern der Benutzerkennung, die im X-AuthenticatedUserId Antwort-Header zurückgegeben wird.

Ablaufmodell

Für Webhook-Benachrichtigungen registrieren wir die IDs Ihrer Benutzer. Jede Interaktion eines Nutzers verlängert die Registrierung des Nutzers um sechs Monate.

Eine Registrierung wird nach einem Zeitraum von sechs Monaten, in dem Sie die OneNote-API nicht im Namen des Benutzers aufgerufen haben, inaktiv. Sie erhalten keine Benachrichtigungen für inaktive Benutzer, einschließlich Benutzer, die Ihre Anwendung deinstallieren oder deren Berechtigungen widerrufen.

Da Änderungsbenachrichtigungen keine Angaben über den Benutzer oder die Änderung enthalten, wird das potenzielle Risiko für die Privatsphäre des Benutzers gemindert. Inaktive Benutzer werden neu registriert, wenn Sie die OneNote-API in ihrem Namen aufrufen.

Siehe auch