Поделиться через

Создание клиентских библиотек Microsoft Graph с помощью Kiota

  • Статья

Корпорация Майкрософт публикует готовые к использованию пакеты SDK для доступа к API Microsoft Graph на многих популярных языках программирования. Эти пакеты SDK являются удобным способом доступа к Microsoft Graph. Просто установите пакет SDK с помощью соответствующего диспетчера пакетов и начните кодирование. Однако из-за размера и области REST API Microsoft Graph эти библиотеки довольно велики. Для приложений, где общий размер установки является проблемой, этот большой размер вызывает беспокойство, особенно если приложение использует только подмножество Microsoft Graph. В этом случае создание пользовательского клиента API с помощью Kiota, предназначенного только для частей Microsoft Graph, используемых приложением, может уменьшить общий размер установки приложения.

Рекомендации по использованию созданных клиентов и пакетов SDK Майкрософт

Использование клиента, созданного Kiota, имеет ряд преимуществ и недостатков по сравнению с использованием пакетов SDK, опубликованных Корпорацией Майкрософт.

Преимущества

  • Клиенты, созданные Kiota, используют те же соглашения и шаблоны, что и опубликованный корпорацией Майкрософт пакет SDK. Если вы уже знакомы с использованием пакета Microsoft SDK, использование созданной библиотеки обеспечивает аналогичный интерфейс.
  • Созданные клиенты совместимы с частью основной библиотеки Microsoft Graph в пакете SDK, опубликованном Корпорацией Майкрософт, поэтому вы можете добавить зависимость в основную библиотеку, если вам нужно использовать такие функции, как итератор страницы, пакетные запросы или отправка больших файлов.

Недостатки

  • Конечным результатом создания клиента с помощью Kiota являются исходные файлы, которые необходимо добавить в проект. Это увеличивает общий размер базы кода. Однако это, вероятно, минимальный размер по сравнению с общим размером полного пакета SDK Microsoft Graph.
  • Если в будущем приложению потребуется вызывать другие API Microsoft Graph, необходимо повторно создать клиент для добавления необходимых моделей и построителей запросов.

Создание клиента

Чтобы создать клиент Microsoft Graph с Kiota, необходимо предоставить описание OpenAPI для Microsoft Graph. Описания OpenAPI для Microsoft Graph можно найти здесь:

  • API версии 1.0: https://aka.ms/graph/v1.0/openapi.yaml
  • API бета-версии: https://aka.ms/graph/beta/openapi.yaml

Чтобы уменьшить общий размер созданного клиента, необходимо определить API Microsoft Graph, используемые приложением, и использовать --include-path параметры или --exclude-path для команды Kiota generate , чтобы создать только модели и построитель запросов для этих API.

Например, рассмотрим приложение, которое использует API To Do для управления задачами и списками задач пользователя To Do. Доступ ко всем необходимым API- интерфейсам, таким как списки задач списка и создание задачи, осуществляется через URL-адреса в URL-адресе /me/todo запроса.

  • Список задач: GET /me/todo/lists
  • Создать задачу: POST /me/todo/lists/{listId}/tasks

В этом случае параметр можно использовать --include-path только для создания моделей и запроса построителей API по /me/todo пути:

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

Пример

Рассмотрим пример создания клиента для C# для вызова API To Do. С помощью клиентской библиотеки Microsoft Graph .NET приложение может получить списки задач пользователя, выполнившего вход, с помощью следующего кода.

using Azure.Identity;
using Microsoft.Graph;

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

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

Кроме того, приложение может использовать созданную Kiota библиотеку для вызова того же API. Для клиента, созданного с помощью следующей команды:

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

Эквивалентный код выглядит следующим образом:

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

Использование функций из основной библиотеки

Получение списков задач пользователя может вернуть ответ со страницами. Основные библиотеки Microsoft Graph предоставляют класс итератора страницы , который разработчики могут использовать для просмотра коллекции списков задач.

Например, в C# добавьте зависимость в Microsoft.Graph.Core (dotnet add package Microsoft.Graph.Core), а затем используйте PageIterator класс для перебора коллекции.

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

Связанные материалы