Práticas recomendadas para trabalhar com a API do OneNote no Microsoft Graph

Este artigo fornece recomendações para trabalhar com APIs do OneNote no Microsoft Graph. Essas recomendações se baseiam em respostas a perguntas comuns nas P&R da Microsoft.

Use $select para selecionar o conjunto mínimo de propriedades de que você precisa

Quando você consulta um recurso (por exemplo, seções em um bloco de anotações), faz uma solicitação semelhante à seguinte.

GET ~/notebooks/{id}/sections

Esta solicitação recupera todas as propriedades das seções. No entanto, você pode não precisar de todas as propriedades. Você pode usar o parâmetro de consulta $select para retornar apenas as propriedades desejadas, conforme mostrado no exemplo a seguir.

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

A mesma abordagem se aplica a outras APIs do OneNote.

Use $expand em vez de várias chamadas à API

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. Você pode fazer isso seguindo este procedimento:

• Chamar GET ~/notebooks para obter a lista de blocos de anotações.

• Para cada bloco de anotações recuperado, chame GET ~/notebooks/{notebookId}/sections para recuperar a lista de seções.

• Para cada bloco de anotações recuperado, chame GET ~/notebooks/{notebookId}/sectionGroups para recuperar a lista de grupos de seções.

• Opcionalmente, iterar de forma repetida em grupos de seções.

Essa abordagem funcionará (com algumas viagens de ida e volta sequenciais extras para o serviço); No entanto, uma abordagem melhor é usar o $expand parâmetro Query.

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

Essa abordagem produz os mesmos resultados em uma viagem de ida e volta da rede, com melhor desempenho.

Ao obter todas as páginas de um usuário, faça isso para cada seção separadamente

O Microsoft Graph expõe um ponto de extremidade para recuperar todas as páginas; No entanto, não recomendamos usar esse ponto de extremidade para obter todas as páginas às quais o usuário tem acesso. Quando o usuário tem muitas seções e é feita uma tentativa de obter todas as páginas, a chamada resulta em um código 400 de status HTTP e a seguinte mensagem: "O número máximo de seções foi excedido para esta solicitação. Para obter páginas para contas com um alto número de seções, recomendamos obter páginas para uma seção por vez." Para obter mais informações sobre esse código de erro, consulte códigos de erro do OneNote.

Para obter todas as páginas às quais um usuário tem acesso, a prática recomendada é fazer chamadas separadas para obter as páginas de cada seção.

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):

GET ~/pages

É melhor usar a seguinte chamada várias vezes (especialmente se você não precisar de todas as seções):

GET ~/sections/{id}/pages

Ao obter metadados de página, substitua a ordenação padrão lastModifiedDateTime. É mais rápido obter páginas quando você não precisa classificá-las por lastModifiedDateTime. Para fazer isso, você pode classificar por qualquer outra propriedade; por exemplo:

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