Postupy: Připojení ke službě Azure Fluid Relay

Článek
10/24/2023

Tento článek vás provede postupem, jak zřizovat službu Azure Fluid Relay a připravit ji k použití.

Důležité

Než budete moct připojit aplikaci k serveru Azure Fluid Relay, musíte zřídit prostředek serveru Azure Fluid Relay na svém účtu Azure.

Služba Azure Fluid Relay je služba Fluid Relay hostovaná v cloudu. Aplikaci Fluid můžete připojit k instanci Azure Fluid Relay pomocí AzureClient v balíčku @fluidframework/azure-client . AzureClient zpracovává logiku připojování kontejneru Fluid ke službě a přitom udržuje samotný objekt kontejneru nezávislý na službě. Ke správě více kontejnerů můžete použít jednu instanci tohoto klienta.

V následujících částech se dozvíte, jak se používá AzureClient ve vaší vlastní aplikaci.

Připojení ke službě

Pokud se chcete připojit k instanci Azure Fluid Relay, musíte nejprve vytvořit .AzureClient K vygenerování webového tokenu JSON (JWT), které se použijí k autorizaci aktuálního uživatele vůči službě, musíte zadat několik parametrů konfigurace, včetně ID tenanta, adresy URL služby a zprostředkovatele tokenu. Balíček @fluidframework/test-client-utils poskytuje insecureTokenProvider, který lze použít pro účely vývoje.

Upozornění

Tato InsecureTokenProvider možnost by se měla používat jenom pro účely vývoje, protože jeho použití zveřejňuje tajný klíč tenanta ve vaší sadě kódu na straně klienta. Musí se nahradit implementací ITokenProvider, která načte token z vaší vlastní back-endové služby, která je zodpovědná za podepsání pomocí klíče tenanta. Příkladem implementace je AzureFunctionTokenProvider. Další informace naleznete v tématu Postupy: Zápis TokenProvider pomocí funkce Azure Functions. Všimněte si, že id pole a name pole jsou libovolná.

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);

Teď, když máte instanci AzureClient, můžete ho začít používat k vytváření nebo načítání kontejnerů Fluid!

Zprostředkovatelé tokenů

AzureFunctionTokenProvider je implementace ITokenProvider , která zajišťuje, že tajný klíč tenanta není vystavený v kódu balíčku na straně klienta. Přebírá AzureFunctionTokenProvider adresu URL funkce Azure, která je připojená společně s aktuálním objektem /api/GetAzureToken uživatele. Později provede GET požadavek na funkci Azure Functions předáním ID tenanta, documentId a userId/userName jako volitelných parametrů.

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);

Přidání vlastních dat do tokenů

Objekt uživatele může obsahovat také volitelné další podrobnosti o uživateli. Příklad:

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",
};

Vaše funkce Azure Functions vygeneruje token pro daného uživatele, který je podepsaný pomocí tajného klíče tenanta, a vrátí ho klientovi bez vystavení samotného tajného klíče.

Správa kontejnerů

Rozhraní AzureClient API zveřejňuje funkce createContainer a getContainer pro vytváření a získávání kontejnerů. Obě funkce přebírají schéma kontejneru, které definuje datový model kontejneru. getContainer Pro funkci je k dispozici další parametr kontejneruid, který chcete načíst.

Ve scénáři vytváření kontejneru můžete použít následující vzor:

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

Volání container.attach() je, když se kontejner skutečně připojí ke službě a zaznamená se do úložiště objektů blob. Vrátí id jedinečný identifikátor této instance kontejneru.

Každý klient, který se chce připojit ke stejné relaci pro spolupráci, musí volat getContainer se stejným kontejnerem id.

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

Další informace o tom, jak začít zaznamenávat protokoly generované fluidem, najdete v tématu Protokolování a telemetrie.

Načítaný kontejner bude obsahovat initialObjects kontejner definovaný ve schématu kontejneru. Další informace o vytvoření schématu a použití objektu container najdete v tématu Modelování dat na fluidframework.com.

Získání podrobností o cílové skupině

createContainer Volání a getContainer vrácení dvou hodnot: a container -- popsané výše - a objekt služeb.

Obsahuje container datový model Fluid a je nezávislý na službách. Veškerý kód, který zapíšete proti tomuto objektu kontejneru vráceného objektem, AzureClient je opakovaně použitelný s klientem pro jinou službu. Příkladem je, že jste svůj scénář prototypovali pomocí TinyliciousClient, pak veškerý kód, který komunikuje se sdílenými objekty v kontejneru Fluid, můžete znovu použít při přechodu na použití AzureClient.

Objekt services obsahuje data specifická pro službu Azure Fluid Relay. Tento objekt obsahuje hodnotu cílové skupiny, kterou lze použít ke správě seznamu uživatelů, kteří jsou aktuálně připojeni ke kontejneru.

Následující kód ukazuje, jak můžete pomocí objektu audience udržovat aktualizované zobrazení všech členů aktuálně v kontejneru.

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 poskytuje dvě funkce, které vrátí objekty AzureMember s ID uživatele a uživatelským jménem:

getMembers vrátí mapu všech uživatelů připojených k kontejneru. Tyto hodnoty se změní, kdykoli se člen připojí nebo opustí kontejner.
getMyself vrátí aktuálního uživatele v tomto klientovi.

audience generuje také události, pro které se změní seznam členů. membersChangedse aktivuje pro všechny změny seznamu, zatímco memberAdded u příslušných změn clientId se aktivují změny a member hodnoty, které memberRemoved byly změněny. Po spuštění některé z těchto událostí se nové volání getMembers vrátí aktualizovaný seznam členů.

Ukázkový AzureMember objekt vypadá takto:

{
  "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"
  }
}

Kromě ID uživatele, jména a dalších podrobností AzureMember objekty obsahují také pole připojení. Pokud je uživatel přihlášený k relaci pouze s jedním klientem, connections bude mít v něm pouze jednu hodnotu s ID klienta a zda je v režimu čtení a zápisu. Pokud je ale stejný uživatel přihlášený z více klientů (to znamená, že jsou přihlášeni z různých zařízení nebo mají otevřených více karet prohlížeče se stejným kontejnerem), connections bude zde obsahovat více hodnot pro každého klienta. V příkladu výše uvedených dat vidíme, že uživatel s názvem Test User (Testovací uživatel) a ID 00aa-bb11-cc22-dd33-44e4ee4e4e4ee4ee" má v současné době otevřený kontejner ze dvou různých klientů. Hodnoty v poli additionalDetails odpovídají hodnotám zadaným v generování tokenu AzureFunctionTokenProvider .

Tyto funkce a události lze kombinovat a prezentovat tak zobrazení uživatelů v reálném čase v aktuální relaci.

Gratulujeme! Teď jste úspěšně připojili kontejner Fluid ke službě Azure Fluid Relay a načtěte podrobnosti o uživateli pro členy ve spolupráci.

Sdílet prostřednictvím