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

[アーティクル]
01/04/2024

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

重要

アプリを Azure Fluid Relay サーバーに接続する前に、Azure アカウントで 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 が用意されています。

注意事項

これを 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のインスタンスが作成されたので、それを使用して 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 サービスに正常に接続され、コラボレーションセッション内のメンバーに関するユーザーの詳細が取り込まれました。

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

サービスへの接続

トークン プロバイダー

トークンへのカスタム データの追加

コンテナーの管理

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

その他のリソース

トークンプロバイダー

トークンへのカスタムデータの追加