Compartir a través de

Generación de bibliotecas cliente de Microsoft Graph con Kiota

  • Artículo

Microsoft publica SDK listos para usar para acceder a las API de Microsoft Graph en muchos lenguajes de programación populares. Estos SDK son una manera cómoda de acceder a Microsoft Graph, simplemente instalar el SDK con el administrador de paquetes adecuado y empezar a codificar. Sin embargo, debido al tamaño y el ámbito de la API REST de Microsoft Graph, estas bibliotecas son bastante grandes. En el caso de las aplicaciones en las que el tamaño de instalación general es un problema, este tamaño grande genera una preocupación, especialmente si la aplicación solo usa un subconjunto de Microsoft Graph. En este caso, generar un cliente de API personalizado con Kiota que tenga como destino solo las partes de Microsoft Graph que usa la aplicación puede reducir el tamaño de instalación general de la aplicación.

Consideraciones para usar clientes generados frente a SDK de Microsoft

El uso de un cliente generado por Kiota tiene algunas ventajas y desventajas con respecto al uso de los SDK publicados por Microsoft.

Ventajas

  • Los clientes generados por Kiota usan las mismas convenciones y patrones que el SDK publicado por Microsoft. Si ya está familiarizado con el uso del SDK de Microsoft, el uso de una biblioteca generada proporciona una experiencia similar.
  • Los clientes generados son compatibles con la parte de la biblioteca principal de Microsoft Graph del SDK publicado por Microsoft, por lo que puede agregar una dependencia a la biblioteca principal si necesita usar características como el iterador de página, las solicitudes por lotes o las cargas de archivos grandes.

Desventajas

  • El resultado final de la generación de cliente con Kiota son los archivos de origen, que se deben agregar al proyecto. Esto aumenta el tamaño general de la base de código. Sin embargo, es probable que esto sea mínimo en comparación con el tamaño general del SDK de Microsoft Graph completo.
  • Si la aplicación necesita llamar a otras API de Microsoft Graph en el futuro, el cliente debe regenerarse para agregar los modelos necesarios y los generadores de solicitudes.

Generación de un cliente

Para generar un cliente de Microsoft Graph con Kiota, debe proporcionar una descripción de OpenAPI para Microsoft Graph. Puede encontrar descripciones de OpenAPI para Microsoft Graph aquí:

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

Para reducir el tamaño general del cliente generado, debe identificar las API de Microsoft Graph que usa la aplicación y usar los --include-path parámetros o --exclude-path en el comando Kiota generate para generar solo los modelos y los generadores de solicitudes para esas API.

Por ejemplo, considere una aplicación que usa las API de tareas pendientes para administrar las tareas y listas de tareas pendientes de un usuario. Se accede a todas las API necesarias, como Listas de listas de tareas y Crear tarea, a través de direcciones URL en la dirección URL de la /me/todo solicitud.

  • Enumerar listas de tareas: GET /me/todo/lists
  • Crear tarea: POST /me/todo/lists/{listId}/tasks

En este caso, puede usar el --include-path parámetro para generar solo modelos y generadores de solicitudes para LAS API en la /me/todo ruta de acceso:

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

Ejemplo

Vamos a explorar un ejemplo de generación de un cliente para C# para llamar a las API de tareas pendientes. Con la biblioteca cliente de .NET de Microsoft Graph, la aplicación podría obtener las listas de tareas del usuario que inició sesión con el código siguiente.

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, la aplicación podría usar una biblioteca generada por Kiota para llamar a la misma API. Para un cliente generado con el siguiente 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

El código equivalente tiene el siguiente aspecto:

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

Uso de características de la biblioteca principal

Obtener las listas de tareas del usuario podría devolver una respuesta paginada. Las bibliotecas principales de Microsoft Graph proporcionan una clase de iterador de página que los desarrolladores pueden usar para paginar la colección de listas de tareas.

Por ejemplo, en C#, agregue una dependencia a Microsoft.Graph.Core (dotnet add package Microsoft.Graph.Core) y, a continuación, use la PageIterator clase para paginar la colección.

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

Contenido relacionado