方法: Azure Fluid Relay サービスに接続する
この記事では、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 サービスに正常に接続され、コラボレーション セッション内のメンバーに関するユーザーの詳細が取り込まれました。