练习 - 配置外部连接并部署架构

8 分钟

在本练习中，你将生成一个自定义 Microsoft Graph 连接器作为控制台应用程序。注册新的Microsoft Entra应用注册，并添加代码以创建外部连接并部署其架构。

创建新的 Graph 连接器项目

首先，通过创建新的 Graph 连接器项目。虽然你可以手动创建项目和所有必要的文件，但在此示例中，你将模板 GitHub 存储库用于 Graph 连接器。使用模板存储库的好处是，它可以创建一个包含所需文件和依赖项的简单项目，从而节省时间。

在命令行中：

通过运行克隆模板存储库 git clone https://github.com/microsoft/learn-microsoft-graph-connectors-dotnet.git

提示

如果尚未安装 git 或没有 GitHub 帐户，则可以将存储库下载为 ZIP 文件。将 ZIP 文件解压缩到计算机上的文件夹以继续练习。
将工作目录更改为克隆的存储库。
在代码编辑器中打开新创建的项目。

在代码编辑器中：

打开 ConnectionConfiguration.cs 文件。在 getter 返回的对象中 ExternalConnection ：
1. 将 Id 属性的值更改为 msgraphdocs。
2. 将 Name 属性的值更改为 Microsoft Graph documentation。
3. 将 Description 属性的值更改为 Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it。
保存所做的更改。

提示

README.md生成的项目中的文件包含有关项目中不同文件和文件夹的详细信息。花点时间阅读并熟悉项目结构。

注册新的Microsoft Entra应用注册

创建的项目包含一个安装脚本，用于创建和配置新的Microsoft Entra应用注册。 Graph 连接器使用此应用注册向 Microsoft 365 进行身份验证。

在命令行中：

将工作目录更改为项目文件夹。
运行安装脚本： .\setup.ps1
出现提示时，请使用工作帐户登录到 Microsoft 365 租户。
等待脚本完成应用注册的创建。该脚本创建名为“Entra”的应用注册 ，Microsoft Graph 文档。
脚本完成后，它会安全地将应用注册信息存储在用户机密中。

安装脚本使用 Microsoft Graph PowerShell SDK 在租户中创建新的Microsoft Entra应用注册。它使用创建外部连接和引入内容所需的Microsoft 图形 API权限配置应用注册。它还使用机密配置应用注册，以允许在没有用户交互的情况下进行身份验证。

提示

若要浏览应用注册配置，请在 Web 浏览器中：

在转到 Azure 门户https://portal.azure.com。
在导航中，选择“Microsoft Entra ID”。
在侧边导航栏中，选择“应用注册”。
从应用注册列表中，选择由安装脚本创建的应用注册。
探索不同的属性，例如 API 权限、 证书 & 机密和 身份验证。

定义外部连接和架构配置

下一步是定义 Graph 连接器应使用的外部连接和架构。由于连接器的代码需要在多个位置访问外部连接的 ID，因此请将其存储在代码的中心位置。

在代码编辑器中：

打开 ConnectionConfiguration.cs 文件。
从属性返回 ExternalConnection 的对象中删除 ActivitySettings 和 SearchSettings 属性。本练习不需要它们。
请注意属性返回的 Schema 架构属性。

第一个属性是 title，它存储导入到 Microsoft 365 的外部项的标题。项的标题是全文索引 (IsSearchable = true) 的一部分。用户还可以在 () 关键字 (keyword) 查询中显式查询IsQueryable = true其内容。还可以检索标题并将其显示在搜索结果中， IsRetrievable = true () 。属性 title 表示项的标题，使用 Title 语义标签进行指示。

接下来是 url 属性，用于存储外部项的原始 URL。用户使用此 URL 从搜索结果导航到外部项，或从 Microsoft 365 导航到 Copilot。 URL 是智能 Microsoft 365 Copilot 副驾驶®所需的属性之一，这就是为什么使用Url语义标签映射它的原因。

最后，还有属性， iconUrl 用于存储每个项的图标的 URL。智能 Microsoft 365 Copilot 副驾驶®需要此属性，并且需要使用语义标签映射IconUrl此属性。

智能 Microsoft 365 Copilot 副驾驶®要求 Graph 连接器至少定义这三个属性，并使用相应的语义标签指定它们。
在数组中 Properties ，添加名为 description的新属性：
```
new Property
{
  Name = "description",
  Type = PropertyType.String,
  IsQueryable = true,
  IsSearchable = true,
  IsRetrievable = true
}
```
属性 description 存储外部项内容的摘要。其定义类似于标题。但是，说明没有语义标签，这就是为什么你不定义它的原因。

完整代码如下所示：

using System.Text.Json;
using Microsoft.Graph.Models;
using Microsoft.Graph.Models.ExternalConnectors;

static class ConnectionConfiguration
{
  private static Dictionary<string, object>? _layout;
  private static Dictionary<string, object> Layout
  {
    get
    {
      if (_layout is null)
      {
        var adaptiveCard = File.ReadAllText("resultLayout.json");
        _layout = JsonSerializer.Deserialize<Dictionary<string, object>>(adaptiveCard);
      }

      return _layout!;
    }
  }

  public static ExternalConnection ExternalConnection
  {
    get
    {
      return 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."
      };
    }
  }

  public static Schema Schema
  {
    get
    {
      return 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 = "url",
            Type = PropertyType.String,
            IsRetrievable = true,
            Labels = new() { Label.Url }
          },
          new Property
          {
            Name = "iconUrl",
            Type = PropertyType.String,
            IsRetrievable = true,
            Labels = new() { Label.IconUrl }
          },
          new Property
          {
            Name = "description",
            Type = PropertyType.String,
            IsQueryable = true,
            IsSearchable = true,
            IsRetrievable = true
          }
        }
      };
    }
  }
}

Save your changes

查看连接创建代码

Graph 连接器项目生成器创建用于创建外部连接并预配其架构的代码。无需进行任何更改即可使用它。在执行此操作之前，请先了解它的工作原理。代码位于 ConnectionService.cs 文件中。

在代码编辑器中：

打开 ConnectionService.cs 文件。
该文件包含两种方法： CreateConnection 和 CreateSchema。方法 CreateConnection 创建外部连接，方法 CreateSchema 预配架构。

如果回想一下，预配外部连接架构是一项长时间运行的操作。但是， CreateSchema 方法中的代码似乎并没有在等待预配架构。此项目中的 Microsoft Graph 客户端使用等待操作完成的自定义中间件。由于此中间件处理等待操作完成，因此 CreateSchema 函数不需要包含任何其他代码，只需等待 API 请求。中间件位于 CompleteJobWithDelayHandler.cs 文件中。

测试代码

最后一步是验证代码是否正常工作。 Program.cs 文件包含应用程序的入口点。它使用 System.CommandLine 包来定义通过从命令行启动应用程序来调用的命令。

在命令行中：

打开终端。
将工作目录更改为项目文件夹。
运行 dotnet build 以生成项目。
通过运行 dotnet run -- create-connection启动应用。
等待几分钟，以创建连接和架构。

练习 - 配置外部连接并部署架构

创建新的 Graph 连接器项目

注册新的Microsoft Entra应用注册

定义外部连接和架构配置

查看连接创建代码

测试代码

反馈