方法: Azure Fluid Relay サービスに接続する

この記事では、Azure Fluid Relay サービスをプロビジョニングして、すぐに使用できるようにするための手順について説明します。

Azure Fluid Relay サービスは、クラウドでホストされる Fluid サービスです。 @fluidframework/azure-client パッケージの AzureClient を使用して、Fluid アプリケーションを Azure Fluid Relay インスタンスに 接続できます。 AzureClient では、コンテナー オブジェクト自体はサービスに依存しない状態のまま、Fluid コンテナーをサービスに接続するロジックを処理します。 このクライアントの 1 つのインスタンスを使用して、複数のコンテナーを管理できます。

以下のセクションでは、お使いのアプリケーションで AzureClient を使用する方法について説明します。

サービスへの接続

Azure Fluid Relay インスタンスに接続するには、最初に AzureClientを作成する必要があります。 現在のユーザーをサービスに対して承認するために使用される JSON Web トークン (JWT) を生成するには、テナント ID、サービス URL、トークン プロバイダーなど、いくつかの構成パラメーターを指定する必要があります。 @fluidframework/test-client-utils パッケージには、開発目的で使用できる InsecureTokenProvider が用意されています。

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のインスタンスが作成されたので、それを使用して Fluid コンテナーを作成するか、または読み込むことができます。

トークン プロバイダー

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 関数は、テナントのシークレット キーを使用して署名された特定のユーザーのトークンを生成し、シークレット自体を公開せずにクライアントに返します。

コンテナーの管理

この API は AzureClient 、それぞれコンテナーを作成および取得するために 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 を返します。

同じコラボレーション セッションに参加するクライアントは、同じコンテナー id で getContainer を呼び出す必要があります。

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

Fluid によって出力されるログの記録を開始する方法の詳細については、「ログとテレメトリ」を参照してください。

取り込まれるコンテナーは、コンテナー スキーマで定義されている initialObjects を保持します。 スキーマを確立し、container オブジェクトを使用する方法の詳細については、fluidframework.com の「データ モデリング」を参照してください。

対象ユーザーの詳細の取得

createContainer上記の -- とサービス オブジェクトの container 2 つの値を呼び出してgetContainer返します。

container には Fluid データ モデルが含まれており、これはサービスに依存しません。 AzureClient によって返されるこのコンテナー オブジェクトに対して記述したコードは、クライアントで別のサービスに再利用できます。 たとえば、TinyliciousClient を使用してシナリオをプロトタイプ化した場合、Fluid コンテナー内の共有オブジェクトと対話するすべてのコードを、使用 AzureClientに移行するときに再利用できます。

services オブジェクトには、Azure Fluid Relay サービスに固有のデータが含まれます。 このオブジェクトには、現在コンテナーに接続しているユーザーの名簿を管理するために使用できる audience 値が含まれます。

次のコードは、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 には、ユーザー ID とユーザー名を持つ AzureMember オブジェクトを返す 2 つの関数が用意されています。

• getMembers は、コンテナーに接続されているすべてのユーザーのマップを返します。 これらの値は、メンバーがコンテナーに参加する場合またはコンテナーから離れる場合にいつでも変更されます。
• getMyself は、このクライアント上の現在のユーザーを返します。

audience では、メンバーの名簿が変更された場合のイベントも生成されます。 membersChanged は名簿の変更に対して発生しますが、memberAdded と memberRemoved は、clientId および member の値の変更によるそれぞれの変更に対して発生します。 これらのイベントが発生すると、getMembers に対する新しい呼び出しによって、更新されたメンバー名簿が返されます。

サンプルのAzureMember オブジェクトは、次のようになります：

{
  "userId": "0e662aca-9d7d-4ff0-8faf-9f8672b70f15",
  "userName": "Test User",
  "connections": [
    {
      "id": "c699c3d1-a4a0-4e9e-aeb4-b33b00544a71",
      "mode": "write"
    },
    {
      "id": "0e662aca-9d7d-4ff0-8faf-9f8672b70f15",
      "mode": "write"
    }
  ],
  "additionalDetails": {
    "email": "xyz@outlook.com",
    "address": "Redmond"
  }
}

オブジェクトは、ユーザー ID、名前、その他の詳細と共に、 AzureMember 接続の配列も保持します。 ユーザーが 1 つのクライアントのみを使用してセッションにログインしている場合、connectionsには、クライアントの ID を含む 1 つの値のみが含まれ、読み取り/書き込みモードになります。 ただし、同じユーザーが複数のクライアントからログインしている場合 (つまり、異なるデバイスからログインしている場合、または同じコンテナーで複数のブラウザー タブがオープンしている場合)、connections はクライアントごとの複数の値を保持します。 上記のデータ例では、名前が "Test User" で、ID が "0e662aca-9d7d-4ff0-8faf-9f8672b70f15" のユーザーが、現在 2 つの異なるクライアントからコンテナーを開いていることがわかります。 additionalDetails フィールドの値は、トークン生成で AzureFunctionTokenProvider 指定された値と一致します。

これらの関数とイベントを組み合わせて、現在のセッション内のユーザーのリアルタイム ビューを表示できます。

おめでとうございます。 これで、Fluid コンテナーが Azure Fluid Relay サービスに正常に接続され、コラボレーション セッション内のメンバーに関するユーザーの詳細が取り込まれました。