Gerar bibliotecas de clientes do Microsoft Graph com o Kiota

  • Artigo

A Microsoft publica SDKs prontos para uso para acessar APIs do Microsoft Graph em muitas linguagens de programação populares. Esses SDKs são uma maneira conveniente de acessar o Microsoft Graph, basta instalar o SDK com o gerenciador de pacotes apropriado e iniciar a codificação. No entanto, devido ao tamanho e ao escopo da API REST do Microsoft Graph, essas bibliotecas são bastante grandes. Para aplicativos em que o tamanho geral da instalação é uma preocupação, esse tamanho grande gera uma preocupação, especialmente se o aplicativo usa apenas um subconjunto do Microsoft Graph. Nesse caso, gerar um cliente de API personalizado com o Kiota que visa apenas as partes do Microsoft Graph usadas pelo aplicativo pode reduzir o tamanho geral da instalação do seu aplicativo.

Considerações sobre como usar clientes gerados versus SDKs da Microsoft

O uso de um cliente gerado pelo Kiota tem algumas vantagens e desvantagens sobre o uso dos SDKs publicados pela Microsoft.

Vantagens

  • Os clientes gerados pelo Kiota usam as mesmas convenções e padrões que o SDK publicado pela Microsoft. Se você já está familiarizado com o uso do SDK da Microsoft, o uso de uma biblioteca gerada oferece uma experiência semelhante.
  • Os clientes gerados são compatíveis com a parte da biblioteca principal do Microsoft Graph do SDK publicado pela Microsoft, para que você possa adicionar uma dependência à biblioteca principal se precisar usar recursos como o iterador de página, solicitações em lote ou carregamentos de arquivos grandes.

Desvantagens

  • O resultado final da geração do cliente com o Kiota são os arquivos de origem, que devem ser adicionados ao seu projeto. Isso aumenta o tamanho geral da base de código.
  • Se seu aplicativo precisar chamar outras APIs do Microsoft Graph no futuro, o cliente deverá ser regenerado para adicionar os modelos necessários e solicitar construtores.

Gerando um cliente

Para gerar um cliente do Microsoft Graph com o Kiota, você deve fornecer uma descrição OpenAPI para o Microsoft Graph. Você pode encontrar descrições do OpenAPI para o Microsoft Graph aqui:

  • API v1.0: https://aka.ms/graph/v1.0/openapi.yaml
  • API beta: https://aka.ms/graph/beta/openapi.yaml

Para reduzir o tamanho geral do cliente gerado, você precisa identificar as APIs do Microsoft Graph usadas pelo aplicativo e usar os --include-path parâmetros ou --exclude-path para o comando kiota gerar apenas os modelos e solicitar construtores para essas APIs.

Por exemplo, considere um aplicativo que usa as APIs Para Fazer para gerenciar tarefas e listas de tarefas de um usuário. Todas as APIs necessárias, como Listar listas de tarefas e Criar tarefa, são acessadas por meio de URLs na URL de solicitação /me/todo .

  • Listar listas de tarefas: GET /me/todo/lists
  • Criar tarefa: POST /me/todo/lists/{listId}/tasks

Nesse caso, você pode usar o --include-path parâmetro para gerar apenas modelos e solicitar construtores para APIs no /me/todo caminho:

kiota generate --openapi https://aka.ms/graph/v1.0/openapi.yaml --include-path /me/todo/** ...

Exemplo

Vamos explorar um exemplo de geração de um cliente para C# para chamar as APIs De Fazer. Usando a biblioteca de clientes .NET do Microsoft Graph, o aplicativo pode obter as listas de tarefas do usuário conectado com o código a seguir.

using Azure.Identity;
using Microsoft.Graph;

var credential = new DeviceCodeCredential();
var graphClient = new GraphServiceClient(credential);

var taskLists = await graphClient.Me.Todo.Lists.GetAsync();

Como alternativa, o aplicativo poderia usar uma biblioteca gerada pelo Kiota para chamar a mesma API. Para um cliente gerado com o seguinte comando:

kiota generate --openapi https://aka.ms/graph/v1.0/openapi.yaml --include-path /me/todo/** --language CSharp --class-name TaskClient --namespace-name MyTaskApp.Client --output ./src/MyTaskApp/Client

O código equivalente se parece com:

using Azure.Identity;
using Microsoft.Kiota.Authentication.Azure;
using Microsoft.Kiota.Http.HttpClientLibrary;
using MyTaskApp.Client;

// The auth provider will only authorize requests to
// the allowed hosts, in this case Microsoft Graph
var allowedHosts = new [] { "graph.microsoft.com" };
var graphScopes = new [] { "User.Read" };

var credential = new DeviceCodeCredential();
var authProvider = new AzureIdentityAuthenticationProvider(credential, allowedHosts, scopes: graphScopes);
var adapter = new HttpClientRequestAdapter(authProvider);
var taskClient = new TaskClient(adapter);

var taskLists = await tasksClient.Me.Todo.Lists.GetAsync();

Usando recursos da biblioteca principal

Obter as listas de tarefas do usuário pode retornar uma resposta de página. As bibliotecas principais do Microsoft Graph fornecem uma página que os desenvolvedores da classe iterador podem usar para página por meio da coleção de listas de tarefas.

Por exemplo, em C#, adicione uma dependência ao Microsoft.Graph.Core (dotnet add package Microsoft.Graph.Core) e use a PageIterator classe para usar a página por meio da coleção.

using MyTaskApp.Client;
using MyTaskApp.Client.Models;
using Microsoft.Graph;

// Using adapter and taskLists from previous example
var pageIterator = PageIterator<TodoTaskList, TodoTaskListCollectionResponse>
    .CreatePageIterator(
        adapter,
        taskLists,
        (taskList) =>
        {
            Console.WriteLine(taskList.DisplayName);
            return true;
        });

await pageIterator.IterateAsync();

Conteúdo relacionado