Procedure: Verbinding maken naar een Azure Fluid Relay-service

Artikel
10/24/2023

In dit artikel worden de stappen beschreven voor het inrichten en voorbereiden van uw Azure Fluid Relay-service.

Belangrijk

Voordat u uw app kunt verbinden met een Azure Fluid Relay-server, moet u een Azure Fluid Relay-serverresource inrichten in uw Azure-account.

Azure Fluid Relay-service is een in de cloud gehoste Fluid-service. U kunt uw Fluid-toepassing verbinden met een Azure Fluid Relay-exemplaar met behulp van de AzureClient in het @fluidframework/azure-clientpakket . AzureClient verwerkt de logica van het verbinden van uw Fluid-container met de service terwijl het containerobject zelf serviceneutraal blijft. U kunt één exemplaar van deze client gebruiken om meerdere containers te beheren.

In de onderstaande secties wordt uitgelegd hoe u deze kunt gebruiken AzureClient in uw eigen toepassing.

Verbinding maken naar de service

Als u verbinding wilt maken met een Azure Fluid Relay-exemplaar, moet u eerst een AzureClient. U moet enkele configuratieparameters opgeven, waaronder de tenant-id, service-URL en een tokenprovider om het JSON-webtoken (JWT) te genereren dat wordt gebruikt om de huidige gebruiker te autoriseren voor de service. Het pakket @fluidframework/test-client-utils biedt een InsecureTokenProvider die kan worden gebruikt voor ontwikkelingsdoeleinden.

Let op

De InsecureTokenProvider sleutel mag alleen worden gebruikt voor ontwikkelingsdoeleinden, omdat hiermee het tenantsleutelgeheim wordt weergegeven in de codebundel aan de clientzijde. Dit moet worden vervangen door een implementatie van ITokenProvider waarmee het token wordt opgehaald uit uw eigen back-endservice die verantwoordelijk is voor het ondertekenen van het token met de tenantsleutel. Een voorbeeld van een implementatie is AzureFunctionTokenProvider. Zie Instructies voor meer informatie: Een TokenProvider schrijven met een Azure-functie. Houd er rekening mee dat de id velden name willekeurig zijn.

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 u een instantie van AzureClienthebt, kunt u deze gaan gebruiken om Fluid-containers te maken of te laden.

Tokenproviders

De AzureFunctionTokenProvider is een implementatie van ITokenProvider die ervoor zorgt dat uw tenantsleutelgeheim niet wordt weergegeven in de bundelcode aan de clientzijde. De AzureFunctionTokenProvider url van uw Azure-functie wordt samen met het huidige gebruikersobject toegevoegd /api/GetAzureToken . Later wordt er een GET aanvraag naar uw Azure-functie verzonden door de tenantId, documentId en userId/userName als optionele parameters door te geven.

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

Aangepaste gegevens toevoegen aan tokens

Het gebruikersobject kan ook optionele aanvullende gebruikersgegevens bevatten. Voorbeeld:

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

Uw Azure-functie genereert het token voor de opgegeven gebruiker die is ondertekend met behulp van de geheime sleutel van de tenant en retourneert deze naar de client zonder het geheim zelf weer te geven.

Containers beheren

De AzureClient API maakt respectievelijk createContainer- en getContainer-functies beschikbaar om containers te maken en op te halen. Beide functies nemen een containerschema op dat het containergegevensmodel definieert. Voor de getContainer functie is er een extra parameter voor de container id van de container die u wilt ophalen.

In het scenario voor het maken van containers kunt u het volgende patroon gebruiken:

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

De container.attach() aanroep is wanneer de container daadwerkelijk wordt verbonden met de service en wordt vastgelegd in de blobopslag. Deze retourneert een id unieke id voor deze containerinstantie.

Elke client die aan dezelfde samenwerkingssessie wil deelnemen, moet worden aangeroepen getContainer met dezelfde container id.

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

Zie Logboekregistratie en telemetrie voor meer informatie over het vastleggen van logboeken die door Fluid worden verzonden.

De container die wordt opgehaald, houdt de initialObjects zoals gedefinieerd in het containerschema vast. Zie Gegevensmodellering op fluidframework.com voor meer informatie over het instellen van het schema en het gebruik van het container object.

Details van doelgroep ophalen

Roept twee waarden aan createContainer en getContainer retourneert deze: een container -- hierboven beschreven - en een services-object.

Het container bevat het Fluid-gegevensmodel en is service-agnostisch. Code die u schrijft op basis van dit containerobject dat door de AzureClient container wordt geretourneerd, kan opnieuw worden gebruikt met de client voor een andere service. Een voorbeeld is dat als u een prototype hebt gemaakt van uw scenario met TinyliciousClient, al uw code die communiceert met de gedeelde objecten in de Fluid-container, opnieuw kan worden gebruikt wanneer u overstapt op gebruik AzureClient.

Het services object bevat gegevens die specifiek zijn voor de Azure Fluid Relay-service. Dit object bevat een doelgroepwaarde die kan worden gebruikt voor het beheren van het rooster van gebruikers die momenteel zijn verbonden met de container.

De volgende code laat zien hoe u het audience object kunt gebruiken om een bijgewerkte weergave te onderhouden van alle leden die zich momenteel in een container bevinden.

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 biedt twee functies die AzureMember-objecten retourneren die een gebruikers-id en gebruikersnaam hebben:

getMembers retourneert een kaart van alle gebruikers die zijn verbonden met de container. Deze waarden worden telkens gewijzigd wanneer een lid lid wordt of de container verlaat.
getMyself retourneert de huidige gebruiker op deze client.

audience verzendt ook gebeurtenissen voor wanneer het rooster van leden wordt gewijzigd. membersChanged zal worden geactiveerd voor wijzigingen in de rooster, terwijl memberAdded en memberRemoved worden geactiveerd voor hun respectieve wijzigingen met de clientId en member waarden die zijn gewijzigd. Nadat een van deze gebeurtenissen is geactiveerd, retourneert een nieuwe aanroep getMembers het bijgewerkte ledenrooster.

Een voorbeeldobject AzureMember ziet er als volgt uit:

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

Naast de gebruikers-id, naam en aanvullende details AzureMember bevatten objecten ook een matrix met verbindingen. Als de gebruiker is aangemeld bij de sessie met slechts één client, connections heeft deze slechts één waarde met de id van de client en of deze zich in de lees-/schrijfmodus bevindt. Als dezelfde gebruiker echter is aangemeld vanaf meerdere clients (dat wil gezegd, ze zijn aangemeld vanaf verschillende apparaten of meerdere browsertabbladen hebben geopend met dezelfde container), connections worden hier meerdere waarden voor elke client opgeslagen. In de bovenstaande voorbeeldgegevens zien we dat een gebruiker met de naam Testgebruiker en id 0e662aca-9d7d-4ff0-8faf-9f8672b70f15 momenteel de container heeft geopend vanaf twee verschillende clients. De waarden in het veld additionalDetails komen overeen met de waarden die zijn opgegeven in de AzureFunctionTokenProvider tokengeneratie.

Deze functies en gebeurtenissen kunnen worden gecombineerd om een realtime weergave van de gebruikers in de huidige sessie te presenteren.

Gefeliciteerd. U hebt uw Fluid-container nu verbonden met de Azure Fluid Relay-service en gebruikersgegevens opgehaald voor de leden in uw samenwerkingssessie.