練習 - 設定外部連線和部署架構

8 分鐘

在此練習中，您會建置自定義 Microsoft Graph 連接器作為主控台應用程式。您可以註冊新的 Microsoft Entra 應用程式註冊，並新增程式代碼來建立外部連線並部署其架構。

建立新的 Graph 連接器專案

從建立新的 Graph 連接器項目開始。雖然您可以手動建立專案和所有必要的檔案，但在此範例中，您會使用 Graph 連接器的 GitHub 存放庫範本。使用範本存放庫的好處是，它會為您建立具有必要檔案和相依性的簡單專案，為您節省時間。

在命令列中：

執行來複製範本存放庫 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 租使用者。
等候腳本完成建立應用程式註冊。此腳本會建立名為 Microsoft Graph 檔的 Entra 應用程式註冊。
當腳本完成時，它會安全地將應用程式註冊資訊儲存在使用者秘密中。

安裝腳本會使用 Microsoft Graph PowerShell SDK，在您的租使用者中建立新的 Microsoft Entra 應用程式註冊。它會使用建立外部連線和內嵌內容所需的Microsoft 圖形 API許可權來設定應用程式註冊。它也會將應用程式註冊設定為秘密，以允許在不進行使用者互動的情況下進行驗證。

提示

若要探索應用程式註冊設定，請在網頁瀏覽器中：

移至位於的 Azure 入口網站https://portal.azure.com。
從導覽中，選取 [Microsoft Entra ID]。
從側邊導覽中，選取 [應用程式註冊]。
從應用程式註冊清單中，選取安裝腳本所建立的應用程式註冊。
探索不同的屬性，例如 API 許可權、 憑證 & 秘密和驗證。

定義外部連線和架構組態

下一個步驟是定義 Graph 連接器應該使用的外部連線和架構。因為連接器的程式代碼需要在數個地方存取外部連線的識別碼，所以請將它儲存在程式代碼中的中央位置。

在程式代碼編輯器中：

開啟 ConnectionConfiguration.cs 檔案。
從屬性傳回的物件中 ExternalConnection ，移除 ActivitySettings 和 SearchSettings 屬性。您在此練習中不需要它們。
請注意屬性所傳回的架 Schema 構屬性。

第一個屬性是 title，它會儲存匯入至 Microsoft 365 之外部專案的標題。項目的標題是全文檢索索引 () IsSearchable = true 的一部分。使用者也可以在關鍵詞查詢中明確地查詢其內容， (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 檔案。
檔案包含兩種方法：和 CreateSchema。 CreateConnection 方法 CreateConnection 會建立外部連接，而 CreateSchema 方法會布建架構。

如果您還記得，布建外部連線架構是長時間執行的作業。不過， CreateSchema 方法中的程式代碼似乎不會等待布建架構。此專案中的 Microsoft Graph 用戶端會使用等候作業完成的自訂中間件。因為此中間件會處理等候作業完成，所以 CreateSchema 函式不需要包含任何其他程序代碼，只需要等候 API 要求。中間件位於 CompleteJobWithDelayHandler.cs 檔案中。

測試程式碼

左側的最後一個步驟是確認程式代碼正常運作。 Program.cs檔案包含應用程式的進入點。它會使用 System.CommandLine 套件來定義您從命令行啟動應用程式所叫用的命令。

在命令列中：

開啟終端機。
將工作目錄變更為項目資料夾。
執行 dotnet build 以建置專案。
執行來 dotnet run -- create-connection啟動應用程式。
等候幾分鐘的時間，建立連線和架構。

練習 - 設定外部連線和部署架構

建立新的 Graph 連接器專案

註冊新的 Microsoft Entra 應用程式註冊

定義外部連線和架構組態

檢閱連線建立程序代碼

測試程式碼

意見反應