配置外部连接并部署架构

  • 3 分钟

在本单元中，你将了解如何配置Microsoft Entra应用注册以用于自定义 Graph 连接器。 你还将了解如何创建外部连接并配置用于导入外部内容的架构。

配置Microsoft Entra应用注册

若要将外部内容导入 Microsoft 365，Graph 连接器需要外部连接和架构。 自定义 Graph 连接器使用 Microsoft Graph API 创建外部连接并部署架构。 为了与 Graph API 通信，它使用 Microsoft Entra 应用注册通过 Microsoft 365 进行身份验证。 通常，Graph 连接器是无需用户交互即可运行的应用。 若要允许连接器创建连接、部署架构并引入外部内容，请向其授予以下应用程序权限：

  • ExternalConnection.ReadWrite.OwnedBy – 允许连接器创建连接并部署架构，
  • ExternalItem.ReadWrite.OwnedBy - 允许连接器引入外部项

这两个权限都允许连接器仅访问连接及其拥有的项，这是建议的安全做法。

创建外部连接

自定义 Graph 连接器使用外部连接Microsoft Graph 终结点创建外部连接。 创建连接时，需要指定其 ID、名称和说明。 ID 在 Microsoft 365 租户中必须唯一，并且长度在 3 到 32 个字符之间。 以下代码片段演示如何创建外部连接：

using Microsoft.Graph.Models.ExternalConnectors;

var requestBody = new ExternalConnection
{
  Id = "msgraphdocs",
  Name = "Microsoft Graph documentation",
  Description = "Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it.",
};

await graphClient.External.Connections.PostAsync(requestBody);

部署架构

创建外部连接后，下一步是部署架构。 架构由一个或多个属性组成。 对于每个属性，需要指定其名称和存储的数据类型。 还可以定义是否应将其数据用于全文搜索和排序。 最后，可以添加一个或多个语义标签，以帮助Microsoft 365 了解属性表示的信息。 智能 Microsoft 365 Copilot 副驾驶®要求在其架构中至少定义标题、URL 和 iconUrl 语义标签的外部连接。 以下代码片段演示如何部署架构：

using Microsoft.Graph.Models.ExternalConnectors;

var schema = new Schema
{
  BaseType = "microsoft.graph.externalItem",
  Properties = new()
  {
    new Property
    {
      Name = "title",
      Type = PropertyType.String,
      IsQueryable = true,
      IsSearchable = true,
      IsRetrievable = true,
      Labels = new() { Label.Title }
    },
    new Property
    {
      Name = "iconUrl",
      Type = PropertyType.String,
      IsRetrievable = true,
      Labels = new() { Label.IconUrl }
    },
    new Property
    {
      Name = "url",
      Type = PropertyType.String,
      IsRetrievable = true,
      Labels = new() { Label.Url }
    },
  }
};

await graphClient.External
  .Connections["{externalConnection-id}"]
  .Schema
  .PatchAsync(schema);

部署外部连接架构是一项长时间运行的操作，需要 5 到 15 分钟。 若要了解预配完成且连接何时可供使用，请检索有关连接的信息并检查其状态。 如果连接尚未准备就绪，请等待 1 分钟，然后再次检查其状态。

do {
  var externalConnection = await GraphService.Client.External
    .Connections["{externalConnection-id}"]
    .GetAsync();

  if (externalConnection?.State != ConnectionState.Draft)
  {
    break;
  }

  await Task.Delay(60_000);
}
while (true);