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. Estas recomendações baseiam-se em respostas a perguntas comuns sobre o Microsoft Q&A.

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

Este pedido obtém todas as propriedades das secçõ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.

Esta abordagem funcionará (com algumas viagens de ida e volta sequenciais adicionais ao serviço); no entanto, uma abordagem melhor é utilizar o $expand parâmetro de consulta.

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

Esta abordagem produz os mesmos resultados numa ida e volta de 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 final para obter todas as páginas; no entanto, não recomendamos a utilização deste ponto final para obter todas as páginas às quais o utilizador tem acesso. Quando o utilizador tem demasiadas secções e é feita uma tentativa de obter todas as páginas, a chamada resulta num código 400 de estado HTTP e na seguinte mensagem: "O número máximo de secções foi excedido para este pedido. Para obter páginas para contas com um número elevado de secções, recomendamos que obtenha páginas para uma secção de cada vez." Para obter mais informações sobre este código de erro, consulte Códigos de erro do OneNote.

Para obter todas as páginas a que um utilizador tem acesso, a melhor prática é fazer chamadas separadas para obter as páginas de cada secçã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 utilizar a seguinte chamada várias vezes (especialmente se não precisar de todas as secçõ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 não tem de as ordenar por lastModifiedDateTime. Para fazer isso, você pode classificar por qualquer outra propriedade; por exemplo:

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