設定外部連線並部署架構

已完成

在此單元中，您將瞭解如何設定 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 連接器會使用 Graph 端點Microsoft外部連線來建立外部連線。 建立連線時，您必須指定其識別碼、名稱和描述。 標識符在您的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);