操作說明：連線到 Azure 流體轉送服務

發行項
11/20/2024

本文將逐步解說步驟，以佈建 Azure 流體轉送服務並準備好使用。

重要

您必須先在 Azure 帳戶上佈建 Azure 流體轉送伺服器資源，才能將應用程式連線至 Azure 流體轉送伺服器。

Azure 流體轉送服務是雲端託管流體服務。您可以使用 @fluidframework/azure-client 套件中的 AzureClient，將 Fluid 應用程式連線到 Azure 流體轉送執行個體。 AzureClient 會處理將流體容器連線至服務的邏輯，同時讓容器物件本身與服務無關。您可以使用此用戶端的一個執行個體來管理多個容器。

下列各節將說明如何在您自己的應用程式中使用 AzureClient。

連線到服務

若要連線到 Azure 流體轉送執行個體，您必須先建立 AzureClient。您必須提供一些設定參數，包括租用戶識別碼、服務 URL 和權杖提供者，以產生 JSON Web 權杖 (JWT)，其會用來針對服務授權目前使用者。 @fluidframework/test-client-utils 套件提供可用於開發用途的 InsecureTokenProvider。

警告

InsecureTokenProvider 應該只用於開發目的，因為使用其會在用戶端程式碼組合中公開租用戶金鑰祕密。必須將其取代為從您自己的後端服務擷取權杖的 ITokenProvider 實作，您自己的後端服務會負責使用租用戶金鑰進行簽署。範例實作是 AzureFunctionTokenProvider。如需詳細資訊，請參閱如何：使用 Azure 函式寫入 TokenProvider。請注意，id 和 name 欄位可隨意自訂。

const user = { id: "userId", name: "userName" };

const config = {
  tenantId: "myTenantId",
  tokenProvider: new InsecureTokenProvider("myTenantKey", user),
  endpoint: "https://myServiceEndpointUrl",
  type: "remote",
};

const clientProps = {
  connection: config,
};

const client = new AzureClient(clientProps);

既然您有 AzureClient 的執行個體，就可以開始使用其來建立或載入流體容器！

權杖提供者

AzureFunctionTokenProvider 是 ITokenProvider 的實作，可確保租用戶金鑰祕密不會在用戶端套件組合程式碼中公開。 AzureFunctionTokenProvider 會採用 /api/GetAzureToken 附加的 Azure 函式 URL，以及目前的使用者物件。稍後，其會傳入 tenantId、documentId 和 userId/userName 作為選擇性參數，向 Azure 函式提出 GET 要求。

const config = {
  tenantId: "myTenantId",
  tokenProvider: new AzureFunctionTokenProvider(
    "myAzureFunctionUrl" + "/api/GetAzureToken",
    { userId: "userId", userName: "Test User" }
  ),
  endpoint: "https://myServiceEndpointUrl",
  type: "remote",
};

const clientProps = {
  connection: config,
};

const client = new AzureClient(clientProps);

將自訂資料新增至權杖

使用者物件也可以保留其他選擇性的使用者詳細資料。例如：

const userDetails = {
  email: "xyz@outlook.com",
  address: "Redmond",
};

const config = {
  tenantId: "myTenantId",
  tokenProvider: new AzureFunctionTokenProvider(
    "myAzureFunctionUrl" + "/api/GetAzureToken",
    { userId: "UserId", userName: "Test User", additionalDetails: userDetails }
  ),
  endpoint: "https://myServiceEndpointUrl",
  type: "remote",
};

您的 Azure 函式會針對使用租用戶秘密金鑰簽署的指定使用者產生權杖，並將其傳回至用戶端，而不需公開秘密本身。

管理容器

AzureClient API 會公開 createContainer 和 getContainer 函式，以分別建立和取得容器。這兩個函式都會採用定義容器資料模型的容器結構描述。針對 getContainer 函式，您所要擷取容器的容器 id 會有額外的參數。

在容器建立案例中，您可以使用下列模式：

const schema = {
  initialObjects: {
    /* ... */
  },
  dynamicObjectTypes: [
    /*...*/
  ],
};
const azureClient = new AzureClient(clientProps);
const { container, services } = await azureClient.createContainer(
  schema
);
const id = await container.attach();

container.attach() 呼叫就是當容器實際連線到服務，並記錄在其 Blob 儲存體中時。其會傳回 id，即這個容器執行個體的唯一識別碼。

任何想要加入相同共同作業工作階段的用戶端都必須使用相同的容器 getContainer 呼叫 id。

const { container, services } = await azureClient.getContainer(
  id,
  schema
);

如需如何開始記錄流體所發出記錄的進一步資訊，請參閱記錄和遙測。

所擷取的容器會保留容器結構描述中所定義的 initialObjects。若要深入了解如何建立結構描述和使用 container 物件，請參閱 fluidframework.com 上的資料模型化。

取得受眾詳細資料

呼叫 createContainer 和 getContainer 會傳回兩個值：container (上述) 和服務物件。

container 包含流體資料模型，且與服務無關。您針對 AzureClient 所傳回的這個容器物件撰寫的任何程式碼，都可供另一個服務的用戶端重複使用。舉例來說，如果您使用 TinyliciousClient 建立案例的原型，則在移動時可以使用 AzureClient，重複使用與流體容器內共用物件互動的所有程式碼。

services 物件包含 Azure 流體轉送服務特有的資料。此物件包含受眾值，可用來管理目前連線至容器的使用者名冊。

下列程式碼示範如何使用 audience 物件，來維護目前容器中所有成員的更新檢視。

const { audience } = containerServices;
const audienceDiv = document.createElement("div");

const onAudienceChanged = () => {
  const members = audience.getMembers();
  const self = audience.getMyself();
  const memberStrings = [];
  const useAzure = process.env.FLUID_CLIENT === "azure";

  members.forEach((member) => {
    if (member.userId !== (self ? self.userId : "")) {
      if (useAzure) {
        const memberString = `${member.userName}: {Email: ${member.additionalDetails ? member.additionalDetails.email : ""},
                        Address: ${member.additionalDetails ? member.additionalDetails.address : ""}}`;
        memberStrings.push(memberString);
      } else {
        memberStrings.push(member.userName);
      }
    }
  });
  audienceDiv.innerHTML = `
            Current User: ${self ? self.userName : ""} <br />
            Other Users: ${memberStrings.join(", ")}
        `;
};

onAudienceChanged();
audience.on("membersChanged", onAudienceChanged);

audience 提供兩個函式，其會傳回具有使用者識別碼和使用者名稱的 AzureMember 物件：

getMembers 會傳回連線至容器的所有使用者的對應。每當成員加入或離開容器時，這些值就會變更。
getMyself 傳回此用戶端上的目前使用者。

audience 也會發出成員名冊何時變更的事件。 membersChanged 會針對任何名冊變更引發，而 memberAddedmemberRemoved 會針對其各自變更引發，其中 clientId 和 member 值已修改。在其中任一事件引發之後，getMembers 的新呼叫會傳回更新的成員名冊。

範例 AzureMember 物件看起來像這樣：

{
  "userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "userName": "Test User",
  "connections": [
    {
      "id": "c699c3d1-a4a0-4e9e-aeb4-b33b00544a71",
      "mode": "write"
    },
    {
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "mode": "write"
    }
  ],
  "additionalDetails": {
    "email": "xyz@outlook.com",
    "address": "Redmond"
  }
}

除了使用者識別碼、名稱和其他詳細資料之外，AzureMember 物件也會保留一組連線。如果使用者登入至只有一個用戶端的工作階段，connections 只會在其中具有一值與用戶端的識別碼，以及是否處於讀取/寫入模式。不過，如果相同使用者是從多個用戶端登入 (亦即，這些使用者會從不同的裝置登入，或已開啟多個瀏覽器索引標籤，其中具有相同的容器)，這裡的 connections 會為每個用戶端保留多個值。在上述範例數據中，我們可以看到名稱為 “Test User” 和 ID “00aa00aa-bb11-cc22-dd33-44ee44ee44ee” 的使用者目前已從兩個不同的客戶端開啟容器。 additionalDetails 欄位中的值會與 AzureFunctionTokenProvider 權杖產生中提供的值相符。

這些函式和事件可以結合，以在目前工作階段中呈現使用者的即時檢視。

恭喜！ 您現在已成功將流體容器連線到 Azure 流體轉送服務，並取回共同作業工作階段中成員的使用者詳細資料！

共用方式為