Procedura: Connettersi a un servizio di inoltro fluido di Azure

Articolo
10/24/2023

Questo articolo illustra i passaggi per eseguire il provisioning del servizio Inoltro fluido di Azure e pronto per l'uso.

Importante

Prima di poter connettere l'app a un server di inoltro fluido di Azure, è necessario effettuare il provisioning di una risorsa del server di Inoltro fluido di Azure nell'account Azure.

Il servizio Inoltro fluido di Azure è un servizio Fluido ospitato nel cloud. È possibile connettere l'applicazione Fluid a un'istanza di Inoltro fluido di Azure usando AzureClient nel pacchetto @fluidframework/azure-client . AzureClient gestisce la logica di connessione del contenitore Fluid al servizio mantenendo l'oggetto contenitore stesso indipendente dal servizio. È possibile usare un'istanza di questo client per gestire più contenitori.

Le sezioni seguenti illustrano come usare AzureClient nella propria applicazione.

Connessione al servizio

Per connettersi a un'istanza di Inoltro fluido di Azure, è prima necessario creare un oggetto AzureClient. È necessario specificare alcuni parametri di configurazione, tra cui l'ID tenant, l'URL del servizio e un provider di token per generare il token JSON Web (JWT) che verrà usato per autorizzare l'utente corrente al servizio. Il pacchetto @fluidframework/test-client-utils fornisce un InsecureTokenProvider che può essere usato a scopo di sviluppo.

Attenzione

Deve InsecureTokenProvider essere usato solo a scopo di sviluppo perché l'uso espone il segreto della chiave tenant nel bundle di codice lato client. Deve essere sostituito con un'implementazione di ITokenProvider che recupera il token dal proprio servizio back-end responsabile della firma con la chiave del tenant. Un'implementazione di esempio è AzureFunctionTokenProvider. Per altre informazioni, vedere Procedura: Scrivere un tokenProvider con una funzione di Azure. Si noti che i id campi e name sono arbitrari.

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

Ora che è disponibile un'istanza di AzureClient, è possibile iniziare a usarla per creare o caricare contenitori Fluid.

Provider di token

AzureFunctionTokenProvider è un'implementazione di ITokenProvider che garantisce che il segreto della chiave del tenant non venga esposto nel codice bundle lato client. AzureFunctionTokenProvider accetta l'URL della funzione di Azure aggiunto insieme /api/GetAzureToken all'oggetto utente corrente. Successivamente, effettua una GET richiesta alla funzione di Azure passando tenantId, documentId e userId/userName come parametri facoltativi.

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

Aggiunta di dati personalizzati ai token

L'oggetto utente può anche contenere altri dettagli utente facoltativi. Ad esempio:

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

La funzione di Azure genererà il token per l'utente specificato firmato usando la chiave privata del tenant e lo restituirà al client senza esporre il segreto stesso.

Gestione dei contenitori

L'API AzureClient espone rispettivamente le funzioni createContainer e getContainer per creare e ottenere contenitori. Entrambe le funzioni accettano uno schema del contenitore che definisce il modello di dati del contenitore. Per la getContainer funzione è disponibile un parametro aggiuntivo per il contenitore del contenitore id da recuperare.

Nello scenario di creazione del contenitore è possibile usare il modello seguente:

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

La container.attach() chiamata è quando il contenitore diventa effettivamente connesso al servizio e viene registrato nell'archivio BLOB. Restituisce un oggetto id che rappresenta l'identificatore univoco per questa istanza del contenitore.

Qualsiasi client che vuole partecipare alla stessa sessione collaborativa deve chiamare getContainer con lo stesso contenitore id.

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

Per altre informazioni su come avviare la registrazione dei log generati da Fluid, vedere Registrazione e telemetria.

Il contenitore recuperato conterrà come initialObjects definito nello schema del contenitore. Per altre informazioni su come stabilire lo schema e usare l'oggettocontainer, vedere Modellazione dei dati in fluidframework.com.

Recupero dei dettagli del gruppo di destinatari

Chiama a createContainer e getContainer restituisce due valori: un , container descritto in precedenza, e un oggetto servizi.

container Contiene il modello di dati Fluid ed è indipendente dal servizio. Qualsiasi codice scritto in questo oggetto contenitore restituito da AzureClient è riutilizzabile con il client per un altro servizio. Un esempio è se è stato creato un prototipo dello scenario usando TinyliciousClient, tutto il codice che interagisce con gli oggetti condivisi all'interno del contenitore Fluid può essere riutilizzato quando si passa a usando AzureClient.

L'oggetto services contiene dati specifici del servizio Inoltro fluido di Azure. Questo oggetto contiene un valore del gruppo di destinatari che può essere usato per gestire l'elenco di utenti attualmente connessi al contenitore.

Il codice seguente illustra come usare l'oggetto audience per mantenere una visualizzazione aggiornata di tutti i membri attualmente in un contenitore.

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 fornisce due funzioni che restituiscono oggetti AzureMember con ID utente e nome utente:

getMembers restituisce una mappa di tutti gli utenti connessi al contenitore. Questi valori cambieranno ogni volta che un membro viene aggiunto o lascia il contenitore.
getMyself restituisce l'utente corrente in questo client.

audience genera anche eventi per quando cambia il roster dei membri. membersChanged verrà generato per tutte le modifiche del roster, mentre memberAdded e memberRemoved verrà attivato per le rispettive modifiche con i clientId valori e member che sono stati modificati. Dopo che uno di questi eventi viene generato, una nuova chiamata a getMembers restituirà l'elenco dei membri aggiornato.

Un oggetto di esempio AzureMember è simile al seguente:

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

Oltre all'ID utente, al nome e ai dettagli aggiuntivi, AzureMember gli oggetti contengono anche una matrice di connessioni. Se l'utente è connesso alla sessione con un solo client, connections avrà un solo valore in esso con l'ID del client e se è in modalità di lettura/scrittura. Tuttavia, se lo stesso utente ha effettuato l'accesso da più client ( ovvero, sono connessi da dispositivi diversi o hanno più schede del browser aperte con lo stesso contenitore), connections qui conterrà più valori per ogni client. Nei dati di esempio precedenti è possibile notare che un utente con nome "Utente di test" e l'ID "00aa00a-bb11-cc22-dd33-44ee44e4ee4e" ha attualmente il contenitore aperto da due client diversi. I valori nel campo additionalDetails corrispondono ai valori specificati nella generazione del AzureFunctionTokenProvider token.

Queste funzioni ed eventi possono essere combinati per presentare una visualizzazione in tempo reale degli utenti nella sessione corrente.

Complimenti. Il contenitore Fluid è stato connesso correttamente al servizio Inoltro fluido di Azure e sono stati recuperati i dettagli dell'utente per i membri della sessione di collaborazione.

Condividi tramite