使用英语阅读

通过


使用 Kiota 生成Microsoft Graph 客户端库

Microsoft发布随时可用的 SDK,用于使用许多常用编程语言访问Microsoft Graph API。 这些 SDK 是访问 Microsoft Graph 的便捷方式,只需使用适当的包管理器安装 SDK,然后开始编码。 但是,由于Microsoft图形 REST API 的大小和范围,这些库相当大。 对于整体安装大小是一个问题的应用程序,这种大大小引起了人们的关注,尤其是当应用程序仅使用Microsoft Graph 的子集时。 在这种情况下,使用 Kiota 生成自定义 API 客户端,该客户端仅面向应用程序使用的 Microsoft Graph 部分,可以减少应用的整体安装大小。

使用生成的客户端与Microsoft SDK 的注意事项

与使用 Microsoft 发布的 SDK 相比较,使用 Kiota 生成的客户端有一些优点和缺点。

优点

  • Kiota 生成的客户端使用与Microsoft发布的 SDK 相同的约定和模式。 如果已经熟悉使用 Microsoft SDK,则使用生成的库可提供类似的体验。
  • 生成的客户端与Microsoft发布的 SDK 的 Microsoft Graph 核心库部分兼容,因此,如果需要使用 页面迭代器批处理请求大型文件上传等功能,可以将依赖项添加到核心库。

缺点

  • 使用 Kiota 生成客户端的最终结果是源文件,必须将其添加到项目中。 这会增加基本代码的整体大小。 但是,与完整 Microsoft Graph SDK 的总体大小相比,这可能最小。
  • 如果应用程序将来需要调用其他Microsoft Graph API,则必须重新生成客户端以添加所需的模型和请求生成器。

生成客户端

若要使用 Kiota 生成 Microsoft Graph 客户端,必须提供 Microsoft Graph 的 OpenAPI 说明。 可在此处找到 Microsoft Graph 的 OpenAPI 说明:

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

为了减小生成的客户端的整体大小,需要标识应用使用的 Microsoft Graph API,并使用 --include-path Kiota generate 命令的 或 --exclude-path 参数来仅生成这些 API 的模型和请求生成器。

例如,假设有一个应用程序使用 “To Do API ”来管理用户的“To Do”任务和任务列表。 所有必需的 API(如 列出任务列表创建任务)都通过请求 URL 下的 /me/todo URL 进行访问。

  • 列出任务列表: GET /me/todo/lists
  • 创建任务: POST /me/todo/lists/{listId}/tasks

在这种情况下,可以使用 --include-path 参数仅生成模型,并在路径下 /me/todo 请求 API 的生成器:

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

示例

让我们探讨一个示例,为 C# 生成客户端来调用待办 API。 使用 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();