Utiliser Fluid avec Teams

Article
04/04/2023

À la fin de ce tutoriel, vous pouvez intégrer n’importe quelle application optimisée par Fluid dans Teams et collaborer avec d’autres applications en temps réel.

Dans cette section, vous pouvez découvrir les concepts suivants :

Intégrer un client Fluid à l’application d’onglet Teams.
Exécutez et connectez votre application Teams à un service Fluid (Relais Azure Fluid).
Créez et obtenez des conteneurs Fluid, puis passez-les à un composant React.

Pour plus d’informations sur la création d’applications complexes, consultez FluidExamples.

Configuration requise

Ce didacticiel nécessite une connaissance des concepts et des ressources suivants :

Vue d’ensemble de l’infrastructure Fluid
Démarrage rapide de Fluid Framework
Les principes de base de React et React Hooks
Comment créer un onglet Microsoft Teams

Installer les composants prérequis

Créez le projet

Ouvrez une invite de commandes et accédez au dossier parent dans lequel vous souhaitez créer le projet, par exemple . /My Microsoft Teams Projects
Créez une application d’onglet Teams en exécutant la commande suivante et en créant un onglet de canal :
```
yo teams
```
Après avoir créé, accédez au projet, avec la commande cd <your project name>suivante .

Le projet utilise les bibliothèques suivantes :

Bibliothèque	Description
`fluid-framework`	Contient le IFluidContainer et d’autres structures de données distribuées qui synchronisent les données entre les clients.
`@fluidframework/azure-client`	Définit le schéma de départ du conteneur Fluid.
`@fluidframework/test-client-utils`	Définit le `InsecureTokenProvider` nécessaire pour créer la connexion à un service Fluid.

Exécutez la commande suivante pour installer les bibliothèques :

npm install @fluidframework/azure-client fluid-framework @fluidframework/test-client-utils

Coder le projet

Ouvrez le fichier /src/client/<your tab name> dans votre éditeur de code.

Créez un fichier en tant que Util.ts et ajoutez les instructions d’importation suivantes :

//`Util.ts

import { IFluidContainer } from "fluid-framework";
import { AzureClient, AzureClientProps } from "@fluidframework/azure-client";
import { InsecureTokenProvider } from "@fluidframework/test-client-utils";

Définition des fonctions et des paramètres Fluid

Cette application est destinée à être utilisée dans le contexte de Microsoft Teams, avec toutes les importations, l’initialisation et les fonctions liées à Fluid. Cela offre une expérience améliorée et facilite son utilisation à l’avenir. Vous pouvez ajouter le code suivant aux instructions d’importation :

// TODO 1: Define the parameter key(s).
// TODO 2: Define container schema.
// TODO 3: Define connectionConfig (AzureClientProps).
// TODO 4: Create Azure client.
// TODO 5: Define create container function.
// TODO 6: Define get container function.

Remarque

Les commentaires définissent toutes les fonctions et constantes nécessaires pour interagir avec le service et le conteneur Fluid.

Remplacez TODO 1: par le code suivant :
```
export const containerIdQueryParamKey = "containerId";
```
La constante est exportée au fur et à mesure qu’elle s’ajoute à dans contentUrl les paramètres De Microsoft Teams et ultérieurement pour analyser l’ID de conteneur dans la page de contenu. Il est courant de stocker des clés de paramètres de requête importantes en tant que constantes, au lieu de taper la chaîne brute à chaque fois.

Avant que le client puisse créer des conteneurs, il a besoin d’un containerSchema qui définit les objets partagés utilisés dans cette application. Cet exemple utilise un SharedMap comme initialObjectsobjet , mais n’importe quel objet partagé peut être utilisé.

Remarque

est map l’ID de l’objet SharedMap et doit être unique dans le conteneur comme n’importe quel autre DDS.

Remplacez TODO: 2 par le code suivant :

const containerSchema = {
    initialObjects: { map: SharedMap }
};

Remplacez TODO: 3 par le code suivant :
```
const connectionConfig : AzureClientProps =
{
    connection: {
        type: "local",
        tokenProvider: new InsecureTokenProvider("foobar", { id: "user" }),
        endpoint: "http://localhost:7070"
    }
};
```
Avant de pouvoir utiliser le client, il a besoin d’un AzureClientProps qui définit le type de connexion utilisé par le client. La connectionConfig propriété est requise pour se connecter au service. Le mode local du client Azure est utilisé. Pour activer la collaboration entre tous les clients, remplacez-la par les informations d’identification du service Relais Fluid. Pour plus d’informations, consultez Comment configurer le service Relais Azure Fluid.

Remplacez TODO: 4 par le code suivant :

const client = new AzureClient(connectionConfig);

Remplacez TODO: 5 par le code suivant :
```
export async function createContainer() : Promise<string> {
    const { container } = await client.createContainer(containerSchema);
    const containerId = await container.attach();
    return containerId;
};
```
Lorsque vous créez le conteneur dans la page de configuration et que vous l’ajoutez contentUrl au paramètre dans Teams, vous devez retourner l’ID du conteneur après avoir attaché le conteneur.
Remplacez TODO: 6 par le code suivant :
```
export async function getContainer(id : string) : Promise<IFluidContainer> {
    const { container } = await client.getContainer(id, containerSchema);
    return container;
};
```
Lorsque vous extrayez le conteneur Fluid, vous devez retourner le conteneur, car votre application doit interagir avec le conteneur et les DDS qu’il contient, dans la page de contenu.

Créer un conteneur Fluid dans la page de configuration

Ouvrez le fichier src/client/<your tab name>/<your tab name>Config.tsx dans votre éditeur de code.

Le flux d’application de l’onglet Teams standard va de la configuration à la page de contenu. Pour activer la collaboration, il est essentiel de conserver le conteneur lors du chargement dans la page de contenu. La meilleure solution pour rendre le conteneur persistant consiste à ajouter l’ID de conteneur sur et contentUrlwebsiteUrl, les URL de la page de contenu, en tant que paramètre de requête. Le bouton Enregistrer dans la page de configuration Teams est la passerelle entre la page de configuration et la page de contenu. Il s’agit d’un emplacement pour créer le conteneur et ajouter l’ID de conteneur dans les paramètres.

Ajoutez les instructions d’importation suivantes:

import { createContainer, containerIdQueryParamKey } from "./Util";

Remplacez la méthode onSaveHandler par le code ci-dessous. Les seules lignes ajoutées ici sont l’appel de la méthode create container définie précédemment dans Utils.ts , puis l’ajout de l’ID de conteneur retourné au contentUrl et websiteUrl en tant que paramètre de requête.

const onSaveHandler = async (saveEvent: microsoftTeams.settings.SaveEvent) => {
    const host = "https://" + window.location.host;
    const containerId = await createContainer();
    microsoftTeams.settings.setSettings({
        contentUrl: host + "/<your tab name>/?" + containerIdQueryParamKey + "=" + containerId + "&name={loginHint}&tenant={tid}&group={groupId}&theme={theme}",
        websiteUrl: host + "/<your tab name>/?" + containerIdQueryParamKey + "=" + containerId + "&name={loginHint}&tenant={tid}&group={groupId}&theme={theme}",
        suggestedDisplayName: "<your tab name>",
        removeUrl: host + "/<your tab name>/remove.html?theme={theme}",
        entityId: entityId.current
    });
    saveEvent.notifySuccess();
};

Veillez à remplacer par <your tab name> le nom d’onglet de votre projet.

Avertissement

Comme l’URL de la page de contenu est utilisée pour stocker l’ID de conteneur, cet enregistrement est supprimé si l’onglet Teams est supprimé. En outre, chaque page de contenu ne peut prendre en charge qu’un seul ID de conteneur.

Page de contenu de refactorisation pour refléter l’application Fluid

Ouvrez le fichier src/client/<your tab name>/<your tab name>.tsx dans votre éditeur de code. Une application fluide classique se compose d’une vue et d’une structure de données Fluid. Concentrez-vous sur l’obtention/le chargement du conteneur Fluid et laissez toutes les interactions liées à Fluid dans un composant React.

Ajoutez les instructions d’importation suivantes dans la page de contenu :

import { IFluidContainer } from "fluid-framework";
import { getContainer, containerIdQueryParamKey } from "./Util";

Supprimez tout le code sous les instructions d’importation dans la page de contenu et remplacez-le par ce qui suit :

export const <your tab name> = () => {
  // TODO 1: Initialize Microsoft Teams.
  // TODO 2: Initialize inTeams boolean.
  // TODO 3: Define container as a React state.
  // TODO 4: Define a method that gets the Fluid container
  // TODO 5: Get Fluid container on content page startup.
  // TODO 6: Pass the container to the React component as argument.
}

Veillez à remplacer par <your tab name> le nom d’onglet que vous définissez pour votre projet.

Remplacez TODO 1 par le code suivant :
```
microsoftTeams.initialize();
```
Pour afficher la page de contenu dans Teams, vous devez inclure la bibliothèque de client JavaScript Microsoft Teams et inclure un appel pour l’initialiser après le chargement de votre page.
Remplacez TODO 2 par le code suivant :
```
const [{ inTeams }] = useTeams();
```
Comme l’application Teams n’est qu’une injection IFrame d’une page web, vous devez initialiser la inTeams constante booléenne afin de savoir si l’application se trouve dans Teams ou non, et si les ressources Teams, telles que le contentUrl, sont disponibles.
Remplacez TODO 3 par le code suivant :
```
const [fluidContainer, setFluidContainer] = useState<IFluidContainer | undefined>(undefined);
```
Utilisez un état React pour le conteneur, car il permet de mettre à jour dynamiquement le conteneur et les objets de données qu’il contient.
Remplacez TODO 4 par le code suivant :
```
const getFluidContainer = async (url : URLSearchParams) => {
    const containerId = url.get(containerIdQueryParamKey);
    if (!containerId) {
        throw Error("containerId not found in the URL");
    }
    const container = await getContainer(containerId);
    setFluidContainer(container);
};
```
Analysez l’URL pour obtenir la chaîne de paramètre de requête, définie par containerIdQueryParamKey, et récupérer l’ID de conteneur. Avec l’ID de conteneur, vous pouvez charger le conteneur. Une fois que vous avez le conteneur, définissez l’état fluidContainer React, consultez l’étape précédente.
Remplacez TODO 5 par le code suivant :
```
useEffect(() => {
    if (inTeams === true) {
        microsoftTeams.settings.getSettings(async (instanceSettings) => {
            const url = new URL(instanceSettings.contentUrl);
            getFluidContainer(url.searchParams);
        });
        microsoftTeams.appInitialization.notifySuccess();
    }
}, [inTeams]);
```
Une fois que vous avez défini comment obtenir le conteneur Fluid, vous devez indiquer à React d’appeler getFluidContainer lors du chargement, puis stocker le résultat dans l’état selon que l’application se trouve dans Teams. le hook useState de React fournit le stockage requis, et useEffect vous permet d’appeler getFluidContainer lors du rendu, en transmettant la valeur retournée dans setFluidContainer.

En ajoutant inTeams dans le tableau de dépendances à la fin de , useEffectl’application garantit que cette fonction est appelée uniquement lors du chargement de la page de contenu.

Remplacez TODO 6 par le code suivant :

if (inTeams === false) {
  return (
      <div>This application only works in the context of Microsoft Teams</div>
  );
}

if (fluidContainer !== undefined) {
  return (
      <FluidComponent fluidContainer={fluidContainer} />
  );
}

return (
  <div>Loading FluidComponent...</div>
);

Remarque

Il est important de s’assurer que la page de contenu est chargée dans Teams et que le conteneur Fluid est défini avant de le transmettre au composant React (défini comme FluidComponent, voir ci-dessous).

Créer React composant pour la vue et les données Fluid

Vous avez intégré le flux de création de base de Teams et Fluid. Vous pouvez maintenant créer votre propre composant React qui gère les interactions entre la vue d’application et les données Fluid. À partir de maintenant, la logique et le flux se comportent comme d’autres applications avec Fluid. Une fois la structure de base configurée, vous pouvez créer n’importe lequel des exemples Fluid en tant qu’application Teams en modifiant l’interaction de la ContainerSchema vue et de l’application avec les objets DDS/data dans la page de contenu.

Démarrer le serveur Fluid et exécuter l’application

Si vous exécutez votre application Teams localement avec le mode local client Azure, veillez à exécuter la commande suivante dans l’invite de commandes pour démarrer le service Fluid :

npx @fluidframework/azure-local-service@latest

Pour exécuter et démarrer l’application Teams, ouvrez un autre terminal et suivez les instructions pour exécuter le serveur d’applications.

Avertissement

Les noms d’hôte avec ngrokles tunnels libres de ne sont pas conservés. Chaque exécution génère une URL différente. Lorsqu’un nouveau ngrok tunnel est créé, l’ancien conteneur n’est plus accessible. Pour les scénarios de production, consultez Utiliser AzureClient avec Azure Fluid Relay.

Remarque

Installez une dépendance supplémentaire pour rendre cette démonstration compatible avec Webpack 5. Si vous recevez une erreur de compilation liée à un package de mémoire tampon, exécutez npm install -D buffer et réessayez. Ce problème sera résolu dans une prochaine version de Fluid Framework.

Étapes suivantes

Utiliser AzureClient avec Relais Azure Fluid

Comme il s’agit d’une application d’onglet Teams, la collaboration et l’interaction sont les main focus. Remplacez le mode AzureClientProps local fourni précédemment par les informations d’identification non locales de votre instance de service Azure, afin que d’autres utilisateurs puissent vous rejoindre et interagir avec vous dans l’application. Découvrez comment approvisionner votre service Relais Azure Fluid.

Importante

Il est important de masquer les informations d’identification que vous transmettez AzureClientProps d’être accidentellement validées dans le contrôle de code source. Le projet Teams est fourni avec un .env fichier dans lequel vous pouvez stocker vos informations d’identification en tant que variables d’environnement et le fichier lui-même est déjà inclus dans ..gitignore Pour utiliser les variables d’environnement dans Teams, consultez Définir et obtenir une variable d’environnement.

Avertissement

InsecureTokenProvider est un moyen pratique de tester l’application localement. Il vous incombe de gérer toute authentification utilisateur et d’utiliser un jeton sécurisé pour n’importe quel environnement de production.

Définir et obtenir une variable d’environnement

Pour définir une variable d’environnement et la récupérer dans Teams, vous pouvez tirer parti du fichier intégré .env . Le code suivant est utilisé pour définir la variable d’environnement dans .env:

# .env

TENANT_KEY=foobar

Pour transmettre le contenu du .env fichier à notre application côté client, vous devez les configurer dans webpack.config.js afin de webpack pouvoir y accéder au moment de l’exécution. Utilisez le code suivant pour ajouter la variable d’environnement à partir de .env:

// webpack,config.js

webpack.EnvironmentPlugin({
    PUBLIC_HOSTNAME: undefined,
    TAB_APP_ID: null,
    TAB_APP_URI: null,
    REACT_APP_TENANT_KEY: JSON.stringify(process.env.TENANT_KEY) // Add environment variable here
}),

Vous pouvez accéder à la variable d’environnement dans Util.ts

// Util.ts

tokenProvider: new InsecureTokenProvider(JSON.parse(process.env.REACT_APP_TENANT_KEY!), { id: "user" }),

Conseil

Lorsque vous apportez des modifications au code, le projet est automatiquement reconstruit et le serveur d’applications se recharge. Toutefois, si vous apportez des modifications au schéma du conteneur, elles ne prendront effet que si vous fermez et redémarrez le serveur d’applications. Pour ce faire, accédez à l’invite de commandes et appuyez deux fois sur Ctrl+C. Ensuite, exécutez gulp serve ou gulp ngrok-serve à nouveau.

Utiliser Fluid avec Teams

Configuration requise

Créez le projet

Coder le projet

Définition des fonctions et des paramètres Fluid

Créer un conteneur Fluid dans la page de configuration

Page de contenu de refactorisation pour refléter l’application Fluid

Créer React composant pour la vue et les données Fluid

Démarrer le serveur Fluid et exécuter l’application

Étapes suivantes

Utiliser AzureClient avec Relais Azure Fluid

Définir et obtenir une variable d’environnement

Voir aussi

Commentaires

Ressources supplémentaires