Bewährte Methoden für die Arbeit mit OneNote-APIs in Microsoft Graph.Best practices for working with the OneNote API in Microsoft Graph

Dieser Artikel enthält Vorschläge für die Arbeit mit OneNote-APIs in Microsoft Graph.This article provides recommendations for working with the OneNote APIs in Microsoft Graph. Diese Empfehlungen basieren auf den Antworten auf häufig gestellte Fragen auf Stack Overflow und Twitter.These recommendations are based on answers to common questions on Stack Overflow and Twitter.

Verwenden von $select, um die minimale Anzahl der benötigten Eigenschaften auszuwählenUse $select to select the minimum set of properties you need

Wenn Sie eine Ressource (z. B. Abschnitte innerhalb eines Notizbuchs) abfragen, verwende Sie eine ähnliche Abfrage wie die folgende.When you query for a resource (for example, sections inside a notebook), you make a request similar to the following.

GET ~/notebooks/{id}/sections

Es werden alle Eigenschaften der Abschnitte abgerufen.This retrieves all the properties of the sections. Allerdings benötigen Sie möglicherweise nicht alle Eigenschaften.However, you might not need all properties. Sie können den $select-Abfragenparameter verwenden, um nur die gewünschten, Eigenschaften zurückzugeben, wie im folgenden Beispiel gezeigt.You can use the $select query parameter to return just the properties that you want, as shown in the following example.

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

Der gleiche Ansatz gilt für andere OneNote-APIs.The same approach applies to other OneNote APIs.

Verwenden von $expand, anstatt mehrere API-Aufrufe auszuführenUse $expand instead of making multiple API calls

Nehmen wir an, dass Sie alle Notizbücher, Abschnitte und Abschnittsgruppen des Benutzers in einer hierarchischen Ansicht abrufen möchten.Suppose you want to retrieve all of the user’s notebooks, sections, and section groups in a hierarchical view. Dazu können Sie folgendermaßen vorgehen:You might accomplish that by doing the following:

  • Rufen Sie GET ~/notebooks auf, um die Liste der Notizbücher anzuzeigen.Call GET ~/notebooks to get the list of notebooks.

  • Rufen Sie für jedes abgerufene Notizbuch GET ~/notebooks/{notebookId}/sections auf, um die Liste der Abschnitte anzuzeigen.For every retrieved notebook, call GET ~/notebooks/{notebookId}/sections to retrieve the list of sections.

  • Rufen Sie für jedes abgerufene Notizbuch GET ~/notebooks/{notebookId}/sectionGroups auf, um die Liste der Abschnittsgruppen anzuzeigen.For every retrieved notebook, call GET ~/notebooks/{notebookId}/sectionGroups to retrieve the list of section groups.

  • Optional können Sie die Abschnittsgruppen rekursiv durchlaufen.Optionally recursively iterate through section groups.

Dies ist zwar (mit ein paar zusätzlichen sequenziellen Roundtrips zum Dienst) möglich, besserer wäre es jedoch, den $expand-Parameter zu verwenden.While this will work (with a few extra sequential roundtrips to the service), a better approach is to use the $expand query parameter.

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

Dadurch werden dieselben Ergebnisse mit einer besseren Leistung in einer Netzwerkschleife erzielt.This will yield the same results in one network roundtrip, with better performance.

Wenn Sie alle Seiten eines Benutzer abrufen möchten, müssen Sie dies für jeden Abschnitt separat tun.When getting all pages for a user, do so for each section separately

Obgleich Microsoft Graph über einen Endpunkt verfügt, um alle Seiten abzurufen, ist dies nicht die beste Möglichkeit, um alle Seiten, auf die der Benutzer Zugriff hat, anzuzeigen.While Microsoft Graph exposes an endpoint to retrieve all pages, this isn't the best way to get all the pages the user has access to. Wenn der Benutzer zu viele Abschnitte besitzt, kann dies zu Timeouts oder Verschlechterung der Leistung führen.When the user has too many sections, this can lead to timeouts or bad performance. Es ist besser, jeden Abschnitt einzeln zu durchlaufen und die Seiten für jeden Abschnitt einzeln abzurufen.It is better to iterate each section, getting pages for each one separately.

Anstatt diesen Aufruf zu verwenden (diese API ist seitennummeriert, sodass Sie nicht alle Seiten auf einmal abrufenden können):For example, instead of using this call (this API is paged, so you won't be able to fetch the pages all at once):

GET ~/pages

Ist es besser, den folgenden Aufruf mehrmals zu verwenden (insbesondere, wenn Sie nicht alle Abschnitte benötigen):It is better to use the following call several times (especially if you don't need all sections):

GET ~/sections/{id}/pages

Wenn Sie Seitenmetadaten erhalten, überschreiben Sie die standardmäßige lastModifiedDateTime-Sortierung.When getting page metadata, override the default lastModifiedDateTime ordering. Seiten können schneller abgerufen werden, wenn Sie nicht nach lastModifiedDateTime sortiert werden müssen.It is faster to get pages when you don't have to sort them by lastModifiedDateTime. Zu diesem Zweck können Sie nach einer anderen Eigenschaft sortieren, z. B:To do this, you can sort by any other property; for example:

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