Gerar bibliotecas de cliente do Microsoft Graph com o Kiota

A Microsoft publica SDKs prontos para usar para acessar as 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 começar a codificar. 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 se destina apenas às partes do Microsoft Graph usadas pelo seu aplicativo pode reduzir o tamanho geral da instalação do seu aplicativo.

Considerações sobre o uso de clientes gerados versus SDKs da Microsoft

Usar um cliente gerado pelo Kiota tem algumas vantagens e desvantagens em relação ao 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á estiver 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, portanto, você pode adicionar uma dependência à biblioteca principal se precisar usar recursos como o iterador de página, solicitações em lote ou uploads 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. No entanto, isso provavelmente é mínimo em comparação com o tamanho geral do SDK completo do Microsoft Graph.
  • Se o aplicativo precisar chamar outras APIs do Microsoft Graph no futuro, o cliente deverá ser regenerado para adicionar os modelos necessários e os construtores de solicitações.

Gerar um cliente

Para gerar um cliente do Microsoft Graph com o Kiota, você deve fornecer uma descrição do OpenAPI para o Microsoft Graph. Você pode encontrar descrições de 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 seu aplicativo e usar os --include-path parâmetros ou --exclude-path para o comando Kiota generate para gerar apenas os modelos e construtores de solicitação para essas APIs.

Por exemplo, considere um aplicativo que usa as APIs To Do para gerenciar as tarefas pendentes e as 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 da /me/todo solicitação.

  • 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 de APIs /me/todo no 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 To Do. Usando a biblioteca de cliente .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 pode 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 paginada. As bibliotecas principais do Microsoft Graph fornecem uma classe de iterador de página que os desenvolvedores podem usar para paginar a coleção de listas de tarefas.

Por exemplo, em C#, adicione uma dependência a Microsoft.Graph.Core (dotnet add package Microsoft.Graph.Core) e use a PageIterator classe para paginar a 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

  • Last updated on