Guide pratique : Se connecter à un service Relais Azure Fluid

Article
01/04/2024

Cet article décrit la procédure permettant d’approvisionner votre service Relais Azure Fluid pour qu’il soit prêt à être utilisé.

Important

Pour pouvoir connecter votre application à un serveur Relais Azure Fluid, vous devez provisionner une ressource de type serveur Relais Azure Fluid sur votre compte Azure.

Le service Relais Azure Fluid est un service Fluid hébergé dans le cloud. Vous pouvez connecter votre application Fluid à une instance Azure Fluid Relay à l’aide d’AzureClient dans le package @fluidframework/azure-client . Le client AzureClient gère la logique de connexion de votre conteneur Fluid au service tout en maintenant l’objet conteneur proprement dit indépendant du service. Vous pouvez utiliser une seule instance de ce client pour gérer plusieurs conteneurs.

Les sections ci-dessous expliquent comment utiliser AzureClient dans votre propre application.

Connexion au service

Pour vous connecter à une instance Relais Azure Fluid, vous devez d’abord créer un AzureClient. Vous devez fournir des paramètres de configuration, notamment l’ID de l’abonné, l’URL de service, ainsi qu’un fournisseur de jetons permettant de générer le jeton JWT (JSON Web Token) qui sera utilisé pour autoriser l’utilisateur actuel sur le service. Le package @fluidframework/test-client-utils fournit un insecureTokenProvider qui peut être utilisé à des fins de développement.

Attention

Il InsecureTokenProvider ne doit être utilisé qu’à des fins de développement, car l’utilisation expose le secret de clé de locataire dans votre ensemble de codes côté client. Cela doit être remplacé par une implémentation d’ITokenProvider qui récupère le jeton à partir de votre propre service principal chargé de la signer avec la clé de locataire. Un exemple d’implémentation est AzureFunctionTokenProvider. Pour plus d’informations, consultez Guide pratique : Écrire un TokenProvider avec une fonction Azure. Notez que les champs id et name sont arbitraires.

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

Maintenant que vous disposez d’une instance AzureClient, vous pouvez commencer à l’utiliser pour créer ou charger des conteneurs Fluid.

Fournisseurs de jetons

AzureFunctionTokenProvider est une implémentation qui ITokenProvider garantit que votre clé secrète de locataire n’est pas exposée dans votre code groupé côté client. Il prend votre URL de fonction Azure, à laquelle est ajouté /api/GetAzureToken, avec l’objet utilisateur actuel. Plus tard, il envoie une requête GET à votre fonction Azure en passant tenantId, documentId et userId/userName comme paramètres optionnels.

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

Ajout de données personnalisées à des jetons

L’objet utilisateur peut également contenir des informations supplémentaires facultatives sur l’utilisateur. Par exemple :

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

Votre fonction Azure génère le jeton pour l’utilisateur signé avec la clé secrète du locataire et le retourne au client sans exposer le secret proprement dit.

Gestion des conteneurs

L’API AzureClient expose les fonctions createContainer et getContainer pour créer et obtenir des conteneurs respectivement. Elles prennent un schéma de conteneur qui définit le modèle de données de conteneur. Pour la fonction getContainer, il existe un paramètre supplémentaire correspondant à la valeur id du conteneur que vous souhaitez extraire.

Dans le scénario de création de conteneur, vous pouvez appliquer le modèle suivant :

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

L’appel container.attach() intervient lorsque le conteneur est réellement connecté au service et enregistré dans son stockage blob. Il retourne un id qui constitue l’identificateur unique de cette instance de conteneur.

Les clients qui souhaitent rejoindre la même session collaborative doivent appeler getContainer avec le même conteneur id.

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

Pour savoir comment commencer l’enregistrement des journaux émis par Fluid, consultez Journalisation et télémétrie.

Le conteneur récupéré contiendra les initialObjects comme cela est défini dans le schéma de conteneur. Pour savoir comment établir le schéma et utiliser l’objet container, consultez Modélisation des données sur fluidframework.com.

Récupération des informations sur l’audience

createContainer Appelle et getContainer retourne deux valeurs : une container -- décrite ci-dessus - et un objet de services.

Le container contient le modèle de données Fluid. Il est indépendant du service. Tout le code que vous écrivez pour cet objet conteneur renvoyé par AzureClient est réutilisable avec le client pour un autre service. Par exemple, si vous avez prototyper votre scénario à l’aide de TinyliciousClient, tout votre code interagissant avec les objets partagés au sein du conteneur Fluid peut être réutilisé lors du passage à l’utilisation AzureClient.

L’objet services contient des données propres au service Relais Azure Fluid. Il comporte une valeur d’audience qui peut permettre de gérer la liste des utilisateurs actuellement connectés au conteneur.

Le code suivant montre comment utiliser l’objet audience pour conserver une vue à jour de tous les membres qui se trouvent actuellement dans un conteneur.

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 fournit deux fonctions qui retournent des objets AzureMember qui ont un ID d’utilisateur et un nom d’utilisateur :

getMembers retourne la carte de tous les utilisateurs connectés au conteneur. Ces valeurs changent à chaque fois qu’un membre rejoint ou quitte le conteneur.
getMyself retourne l’utilisateur actuel présent sur ce client.

audience émet également des événements lorsque la liste des membres change. membersChanged se déclenche pour toutes les modifications de la liste, tandis que memberAdded et memberRemoved se déclenchent respectivement pour les ajouts et suppressions avec les valeurs clientId et member modifiées. Une fois qu’un de ces événements est activé, un nouvel appel à getMembers retourne la liste des membres mise à jour.

Voici un exemple d’objet 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"
  }
}

Outre l’ID utilisateur, le nom et les détails supplémentaires, AzureMember les objets contiennent également un tableau de connexions. Si l’utilisateur est connecté à la session avec un seul client, connections ne comporte qu’une seule valeur avec l’ID du client et le mode (lecture/écriture ou non). Toutefois, si le même utilisateur est connecté à partir de plusieurs clients (c’est-à-dire à partir de différents appareils ou en ouvrant plusieurs onglets de navigateur avec le même conteneur), connections contient plusieurs valeurs pour chaque client. Dans l’exemple de données ci-dessus, un utilisateur portant le nom « Test User » et associé à l’ID « 0e662aca-9d7d-4ff0-8faf-9f8672b70f15 » a actuellement le conteneur ouvert à partir de deux clients différents. Les valeurs du champ additionalDetails correspondent aux valeurs fournies dans la génération de AzureFunctionTokenProvider jeton.

Ces fonctions et événements peuvent être combinés pour présenter une vue en temps réel des utilisateurs de la session active.

Félicitations ! Vous avez connecté votre conteneur Fluid au service Relais Azure Fluid et récupéré les informations sur l’utilisateur pour les membres de votre session collaborative.