Compartilhar via

Gerar bibliotecas de cliente do Microsoft Graph com a Kiota

  • Artigo

A Microsoft publica SDKs prontos a utilizar para aceder às APIs do Microsoft Graph em muitas linguagens de programação populares. Estes SDKs são uma forma conveniente de aceder ao Microsoft Graph, basta instalar o SDK com o gestor de pacotes adequado e começar a codificar. No entanto, devido ao tamanho e âmbito da API REST do Microsoft Graph, estas bibliotecas são bastante grandes. Para aplicações em que o tamanho geral da instalação é uma preocupação, este tamanho grande suscita uma preocupação, especialmente se a aplicação utilizar apenas um subconjunto do Microsoft Graph. Neste caso, gerar um cliente de API personalizado com o Kiota que visa apenas as partes do Microsoft Graph utilizadas pela sua aplicação pode reduzir o tamanho de instalação geral da sua aplicação.

Considerações sobre a utilização de clientes gerados vs. SDKs da Microsoft

A utilização de um cliente gerado pela Kiota tem algumas vantagens e desvantagens em utilizar os SDKs publicados pela Microsoft.

Vantagens

  • Os clientes gerados pela Kiota utilizam as mesmas convenções e padrões que o SDK publicado pela Microsoft. Se já estiver familiarizado com a utilização do SDK da Microsoft, utilizar uma biblioteca gerada proporciona uma experiência semelhante.
  • Os clientes gerados são compatíveis com a parte principal da biblioteca do Microsoft Graph do SDK publicado pela Microsoft, pelo que pode adicionar uma dependência à biblioteca principal se precisar de utilizar funcionalidades como o iterador de páginas, pedidos em lote ou carregamentos de ficheiros grandes.

Desvantagens

  • O resultado final da geração de clientes com o Kiota são os ficheiros de origem, que têm de ser adicionados ao seu projeto. Isto aumenta o tamanho geral da base de código. No entanto, isto é provavelmente mínimo em comparação com o tamanho geral do SDK completo do Microsoft Graph.
  • Se a sua aplicação precisar de chamar outras APIs do Microsoft Graph no futuro, o cliente tem de ser regenerado para adicionar os modelos necessários e os construtores de pedidos.

Gerar um cliente

Para gerar um cliente do Microsoft Graph com a Kiota, tem de fornecer uma descrição de OpenAPI para o Microsoft Graph. 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, tem de identificar as APIs do Microsoft Graph utilizadas pela sua aplicação e utilizar os --include-path parâmetros ou --exclude-path para o comando De geração kiota para gerar apenas os modelos e os construtores de pedidos para essas APIs.

Por exemplo, considere uma aplicação que utiliza as APIs To Do para gerir as tarefas e listas de tarefas do To Do de um utilizador. Todas as APIs necessárias, como Listar listas de tarefas e Criar tarefa, são acedidas através de URLs no URL do /me/todo pedido.

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

Neste caso, pode utilizar o --include-path parâmetro para gerar apenas modelos e construtores de pedidos 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 To Do. Com a biblioteca de cliente .NET do Microsoft Graph, a aplicação pode obter as listas de tarefas do utilizador com sessão iniciada com o seguinte código.

using Azure.Identity;
using Microsoft.Graph;

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

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

Em alternativa, a aplicação pode utilizar uma biblioteca gerada por 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 tem o seguinte aspeto:

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();

Utilizar funcionalidades da biblioteca principal

Obter as listas de tarefas do utilizador pode devolver uma resposta paginada. As bibliotecas principais do Microsoft Graph fornecem uma página que os programadores da classe iterador podem utilizar para percorrer a coleção de listas de tarefas.

Por exemplo, em C#, adicione uma dependência ao Microsoft.Graph.Core () edotnet add package Microsoft.Graph.Core, em seguida, utilize a PageIterator classe para a página através 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