Freigeben über

Bewährte Methoden für die Arbeit mit OneNote-APIs in Microsoft Graph.

  • Artikel

Dieser Artikel enthält Vorschläge für die Arbeit mit OneNote-APIs in Microsoft Graph. Diese Empfehlungen basieren auf Antworten auf häufig gestellte Fragen zu Microsoft Q&A.

Verwenden von $select, um die minimale Anzahl der benötigten Eigenschaften auszuwählen

Wenn Sie eine Ressource (z. B. Abschnitte innerhalb eines Notizbuchs) abfragen, verwende Sie eine ähnliche Abfrage wie die folgende.

GET ~/notebooks/{id}/sections

Diese Anforderung ruft alle Eigenschaften der Abschnitte ab. Allerdings benötigen Sie möglicherweise nicht alle Eigenschaften. Sie können den $select-Abfragenparameter verwenden, um nur die gewünschten, Eigenschaften zurückzugeben, wie im folgenden Beispiel gezeigt.

GET ~/notebooks/{id}/sections?$select=id,displayName

Der gleiche Ansatz gilt für andere OneNote-APIs.

Verwenden von $expand, anstatt mehrere API-Aufrufe auszuführen

Nehmen wir an, dass Sie alle Notizbücher, Abschnitte und Abschnittsgruppen des Benutzers in einer hierarchischen Ansicht abrufen möchten. Dazu können Sie folgendermaßen vorgehen:

  • Rufen Sie GET ~/notebooks auf, um die Liste der Notizbücher anzuzeigen.

  • Rufen Sie für jedes abgerufene Notizbuch GET ~/notebooks/{notebookId}/sections auf, um die Liste der Abschnitte anzuzeigen.

  • Rufen Sie für jedes abgerufene Notizbuch GET ~/notebooks/{notebookId}/sectionGroups auf, um die Liste der Abschnittsgruppen anzuzeigen.

  • Optional können Sie die Abschnittsgruppen rekursiv durchlaufen.

Dieser Ansatz funktioniert (mit einigen zusätzlichen sequenziellen Roundtrips zum Dienst). Ein besserer Ansatz ist jedoch die Verwendung des $expand Abfrageparameters.

GET ~/notebooks?$expand=sections,sectionGroups($expand=sections)

Dieser Ansatz führt zu den gleichen Ergebnissen in einem Netzwerkroundtrip mit einer besseren Leistung.

Wenn Sie alle Seiten eines Benutzer abrufen möchten, müssen Sie dies für jeden Abschnitt separat tun.

Microsoft Graph macht einen Endpunkt verfügbar, um alle Seiten abzurufen. Es wird jedoch nicht empfohlen, diesen Endpunkt zu verwenden, um alle Seiten abzurufen, auf die der Benutzer Zugriff hat. Wenn der Benutzer zu viele Abschnitte hat und versucht wird, alle Seiten abzurufen, führt der Aufruf zu einem HTTP-Statuscode 400 und der folgenden Meldung: "Die maximale Anzahl von Abschnitten für diese Anforderung wurde überschritten. Um Seiten für Konten mit einer hohen Anzahl von Abschnitten abzurufen, empfehlen wir, Seiten für einen Abschnitt gleichzeitig abzurufen." Weitere Informationen zu diesem Fehlercode finden Sie unter OneNote-Fehlercodes.

Um alle Seiten abzurufen, auf die ein Benutzer Zugriff hat, besteht die bewährte Methode darin, separate Aufrufe zu tätigen, um die Seiten für jeden Abschnitt abzurufen.

Anstatt diesen Aufruf zu verwenden (diese API ist seitennummeriert, sodass Sie nicht alle Seiten auf einmal abrufenden können):

GET ~/pages

Es ist besser, den folgenden Aufruf mehrmals zu verwenden (insbesondere, wenn Sie nicht alle Abschnitte benötigen):

GET ~/sections/{id}/pages

Wenn Sie Seitenmetadaten erhalten, überschreiben Sie die standardmäßige lastModifiedDateTime-Sortierung. Es ist schneller, Seiten abzurufen, wenn Sie sie nicht nach lastModifiedDateTimesortieren müssen. Zu diesem Zweck können Sie nach einer anderen Eigenschaft sortieren, z. B:

GET ~/sections/{id}/pages?$select=id,title,createdDateTime&$orderby=createdDateTime