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

  • Artigo

Este artigo fornece recomendações para trabalhar com APIs do OneNote no Microsoft Graph. Essas recomendações são baseadas em respostas a perguntas comuns no Microsoft Q&A e no Twitter.

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

Isso 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.

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.

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

Isso gera os mesmos resultados em uma 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

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. Quando o usuário tem muitas seções, isso pode causar tempos limite ou mau desempenho. É melhor iterar cada seção, obtendo páginas para cada uma separadamente.

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 acessar páginas quando não é preciso 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