Práticas recomendadas para trabalhar com a API do OneNote no Microsoft GraphBest practices for working with the OneNote API in Microsoft Graph

Este artigo fornece recomendações para trabalhar com APIs do OneNote no Microsoft Graph.This article provides recommendations for working with the OneNote APIs in Microsoft Graph. Essas recomendações são baseadas em respostas a perguntas comuns do Stack Overflow e do Twitter.These recommendations are based on answers to common questions on Stack Overflow and Twitter.

Use $select para selecionar o conjunto mínimo de propriedades de que você precisaUse $select to select the minimum set of properties you need

Quando você consulta um recurso (por exemplo, seções em um bloco de anotações), faz uma solicitação semelhante à seguinte.When you query for a resource (for example, sections inside a notebook), you make a request similar to the following.

GET ~/notebooks/{id}/sections

Isso recupera todas as propriedades das seções.This retrieves all the properties of the sections. No entanto, você pode não precisar de todas as propriedades.However, you might not need all properties. Você pode usar o parâmetro de consulta $select para retornar apenas as propriedades desejadas, conforme mostrado no exemplo a seguir.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

A mesma abordagem se aplica a outras APIs do OneNote.The same approach applies to other OneNote APIs.

Use $expand em vez de várias chamadas à APIUse $expand instead of making multiple API calls

Suponha que você queira recuperar todos os blocos de anotações, seções e grupos de seções do usuário em uma exibição hierárquica.Suppose you want to retrieve all of the user’s notebooks, sections, and section groups in a hierarchical view. Você pode fazer isso seguindo este procedimento:You might accomplish that by doing the following:

  • Chamar GET ~/notebooks para obter a lista de blocos de anotações.Call GET ~/notebooks to get the list of notebooks.

  • Para cada bloco de anotações recuperado, chame GET ~/notebooks/{notebookId}/sections para recuperar a lista de seções.For every retrieved notebook, call GET ~/notebooks/{notebookId}/sections to retrieve the list of sections.

  • Para cada bloco de anotações recuperado, chame GET ~/notebooks/{notebookId}/sectionGroups para recuperar a lista de grupos de seções.For every retrieved notebook, call GET ~/notebooks/{notebookId}/sectionGroups to retrieve the list of section groups.

  • Opcionalmente, iterar de forma repetida em grupos de seções.Optionally recursively iterate through section groups.

Embora isso funcione (com algumas viagens de ida e volta sequenciais extra ao serviço), uma abordagem melhor é usar o parâmetro de consulta $expand.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)

Isso produzirá os mesmos resultados de ida e volta na rede, com melhor desempenho.This will yield the same results in one network roundtrip, with better performance.

Ao obter todas as páginas de um usuário, faça isso para cada seção separadamenteWhen getting all pages for a user, do so for each section separately

Embora o Microsoft Graph exponha um ponto de extremidade para recuperar todas as páginas, essa não é a melhor maneira de obter todas as páginas às quais o usuário tem acesso.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. Quando o usuário tem muitas seções, isso pode causar tempos limite ou mau desempenho.When the user has too many sections, this can lead to timeouts or bad performance. É melhor iterar cada seção, obtendo páginas para cada uma separadamente.It is better to iterate each section, getting pages for each one separately.

Por exemplo, em vez de usar essa chamada (essa API é paginada; portanto, você não poderá buscar todas as páginas de uma só vez):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

É melhor usar a seguinte chamada várias vezes (especialmente se você não precisar de todas as seções):It is better to use the following call several times (especially if you don't need all sections):

GET ~/sections/{id}/pages

Ao obter metadados de página, substitua a ordenação padrão lastModifiedDateTime.When getting page metadata, override the default lastModifiedDateTime ordering. É mais rápido acessar páginas quando não é preciso classificá-las por lastModifiedDateTime.It is faster to get pages when you don't have to sort them by lastModifiedDateTime. Para fazer isso, você pode classificar por qualquer outra propriedade; por exemplo:To do this, you can sort by any other property; for example:

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