Anvisningar: Anslut till en Azure Fluid Relay-tjänst

Artikel
10/24/2023

Den här artikeln går igenom stegen för att få din Azure Fluid Relay-tjänst etablerad och redo att användas.

Viktigt!

Innan du kan ansluta din app till en Azure Fluid Relay-server måste du etablera en Azure Fluid Relay-serverresurs på ditt Azure-konto.

Azure Fluid Relay-tjänsten är en molnbaserad fluidtjänst. Du kan ansluta ditt Fluid-program till en Azure Fluid Relay-instans med hjälp av AzureClient i paketet @fluidframework/azure-client . AzureClient hanterar logiken för att ansluta din Fluid-container till tjänsten samtidigt som själva containerobjektet hålls tjänstoberoende. Du kan använda en instans av den här klienten för att hantera flera containrar.

I avsnitten nedan förklaras hur du använder AzureClient i ditt eget program.

Anslut till tjänsten

För att ansluta till en Azure Fluid Relay-instans måste du först skapa en AzureClient. Du måste ange vissa konfigurationsparametrar, inklusive klientorganisations-ID, tjänst-URL och en tokenprovider för att generera JSON-webbtoken (JWT) som ska användas för att auktorisera den aktuella användaren mot tjänsten. Paketet @fluidframework/test-client-utils tillhandahåller en InsecureTokenProvider som kan användas i utvecklingssyfte.

Varning

Bör InsecureTokenProvider endast användas i utvecklingssyfte eftersom den exponerar klientnyckelhemligheten i kodpaketet på klientsidan. Detta måste ersättas med en implementering av ITokenProvider som hämtar token från din egen serverdelstjänst som ansvarar för att signera den med klientnyckeln. Ett exempel på implementering är AzureFunctionTokenProvider. Mer information finns i Så här skriver du en TokenProvider med en Azure-funktion. Observera att fälten id och name är godtyckliga.

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

Nu när du har en instans av AzureClientkan du börja använda den för att skapa eller läsa in Vätskecontainrar!

Tokenprovidrar

AzureFunctionTokenProvider är en implementering av ITokenProvider som säkerställer att din klientnyckelhemlighet inte exponeras i paketkoden på klientsidan. Hämtar AzureFunctionTokenProvider din Azure-funktions-URL som läggs till av /api/GetAzureToken tillsammans med det aktuella användarobjektet. Senare skickar den en GET begäran till din Azure-funktion genom att skicka in tenantId, documentId och userId/userName som valfria parametrar.

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

Lägga till anpassade data i token

Användarobjektet kan också innehålla valfri ytterligare användarinformation. Till exempel:

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

Din Azure-funktion genererar token för den angivna användaren som är signerad med klientorganisationens hemliga nyckel och returnerar den till klienten utan att exponera själva hemligheten.

Hantering av containrar

API:et AzureClient exponerar funktionerna createContainer och getContainer för att skapa respektive hämta containrar. Båda funktionerna har ett containerschema som definierar containerdatamodellen. getContainer För funktionen finns det ytterligare en parameter för containern id för den container som du vill hämta.

I scenariot för att skapa containrar kan du använda följande mönster:

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

Anropet container.attach() är när containern faktiskt ansluts till tjänsten och registreras i dess bloblagring. Den returnerar en id som är den unika identifieraren för den här containerinstansen.

Alla klienter som vill ansluta till samma samarbetssession måste anropa getContainer med samma container id.

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

Mer information om hur du startar inspelningsloggar som genereras av Fluid finns i Loggning och telemetri.

Containern som hämtas tillbaka innehåller enligt initialObjects definitionen i containerschemat. Mer information om hur du upprättar schemat och använder container objektet finns i Datamodellering på fluidframework.com.

Få information om målgruppen

createContainer Anropar och getContainer returnerar två värden: en container – som beskrivs ovan – och ett tjänstobjekt.

Innehåller container datamodellen Fluid och är tjänstagnostisk. All kod som du skriver mot det här containerobjektet som returneras av AzureClient kan återanvändas med klienten för en annan tjänst. Ett exempel är om du har skapat ett prototypscenario med Hjälp av TinyliciousClient. Då kan all kod som interagerar med delade objekt i fluidcontainern återanvändas när du flyttar till med .AzureClient

Objektet services innehåller data som är specifika för Azure Fluid Relay-tjänsten. Det här objektet innehåller ett målgruppsvärde som kan användas för att hantera listan över användare som för närvarande är anslutna till containern.

Följande kod visar hur du kan använda audience objektet för att underhålla en uppdaterad vy över alla medlemmar som för närvarande finns i en container.

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 innehåller två funktioner som returnerar AzureMember-objekt som har ett användar-ID och användarnamn:

getMembers returnerar en karta över alla användare som är anslutna till containern. Dessa värden ändras när en medlem ansluter eller lämnar containern.
getMyself returnerar den aktuella användaren på den här klienten.

audience genererar även händelser för när medlemslistan ändras. membersChanged kommer att utlösas för eventuella ändringar i listan, medan memberAdded och memberRemoved kommer att utlösas för sina respektive ändringar med de clientId värden och member som har ändrats. När någon av dessa händelser utlöses returnerar ett nytt anrop till getMembers den uppdaterade medlemslistan.

Ett exempelobjekt AzureMember ser ut så här:

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

Förutom användar-ID, namn och ytterligare information innehåller AzureMember objekt också en matris med anslutningar. Om användaren är inloggad i sessionen med endast en klient har connections den bara ett värde med klientens ID och om den är i läs-/skrivläge. Men om samma användare är inloggad från flera klienter (dvs. de är inloggade från olika enheter eller har flera webbläsarflikar öppna med samma container), connections innehåller här flera värden för varje klient. I exempeldata ovan kan vi se att en användare med namnet "Test user" och ID "0e662aca-9d7d-4ff0-8faf-9f8672b70f15" för närvarande har containern öppen från två olika klienter. Värdena i fältet additionalDetails matchar värdena som anges i tokengenereringen AzureFunctionTokenProvider .

Dessa funktioner och händelser kan kombineras för att presentera en realtidsvy över användarna i den aktuella sessionen.

Klar! Nu har du anslutit din Fluid-container till Azure Fluid Relay-tjänsten och hämtat tillbaka användarinformation för medlemmarna i din samarbetssession!

Share via