Uso de Fluid con Teams
Al final de este tutorial, puede integrar cualquier aplicación con tecnología Fluid en Teams y colaborar con otros usuarios en tiempo real.
En esta sección puede aprender los siguientes conceptos:
- Integre un cliente de Fluid en la aplicación de pestaña de Teams.
- Ejecute y conecte la aplicación de Teams a un servicio Fluid (Azure Fluid Relay).
- Cree y obtenga contenedores fluidos y páselos a un componente de React.
Para obtener más información sobre la creación de aplicaciones complejas, consulte FluidExamples.
Requisitos previos
Este tutorial requiere estar familiarizado con los siguientes conceptos y recursos:
- Información general sobre Fluid Framework
- Inicio rápido de Fluid Framework
- Los conceptos básicos de los enlaces react y react
- Cómo crear una pestaña de Microsoft Teams
Cree el proyecto
Abra un símbolo del sistema y vaya a la carpeta primaria donde desea crear el proyecto, por ejemplo,
/My Microsoft Teams Projects
.Cree una aplicación de pestaña de Teams ejecutando el siguiente comando y creando una pestaña de canal:
yo teams
Después de crear, vaya al proyecto con el siguiente comando
cd <your project name>
.El proyecto usa las siguientes bibliotecas:
Biblioteca Descripción fluid-framework
Contiene IFluidContainer y otras estructuras de datos distribuidas que sincronizan datos entre clientes. @fluidframework/azure-client
Define el esquema inicial del contenedor Fluid. @fluidframework/test-client-utils
Define el InsecureTokenProvider
necesario para crear la conexión a un servicio Fluid.Ejecute el siguiente comando para instalar las bibliotecas:
npm install @fluidframework/azure-client fluid-framework @fluidframework/test-client-utils
Codificar el proyecto
Abra el archivo
/src/client/<your tab name>
en el editor de código.Cree un archivo como
Util.ts
y agregue las siguientes instrucciones de importación://`Util.ts import { IFluidContainer } from "fluid-framework"; import { AzureClient, AzureClientProps } from "@fluidframework/azure-client"; import { InsecureTokenProvider } from "@fluidframework/test-client-utils";
Definición de funciones y parámetros de Fluid
Esta aplicación está pensada para usarse en el contexto de Microsoft Teams, con todas las importaciones, inicialización y funciones relacionadas con Fluid. Esto proporciona una experiencia mejorada y facilita su uso en el futuro. Puede agregar el código siguiente a las instrucciones import:
// 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.
Nota:
Los comentarios definen todas las funciones y constantes necesarias para interactuar con el servicio Fluid y el contenedor.
Reemplace
TODO 1:
por el código siguiente:export const containerIdQueryParamKey = "containerId";
La constante se exporta a medida que se anexa a
contentUrl
en la configuración de Microsoft Teams y, posteriormente, para analizar el identificador de contenedor en la página de contenido. Es un patrón común almacenar claves de parámetros de consulta importantes como constantes, en lugar de escribir la cadena sin procesar cada vez.Antes de que el cliente pueda crear contenedores, necesita un
containerSchema
que defina los objetos compartidos que se usan en esta aplicación. En este ejemplo se usa SharedMap comoinitialObjects
, pero se puede usar cualquier objeto compartido.Nota:
map
es el identificador delSharedMap
objeto y debe ser único dentro del contenedor como cualquier otro DDS.Reemplace
TODO: 2
por el código siguiente:const containerSchema = { initialObjects: { map: SharedMap } };
Reemplace
TODO: 3
por el código siguiente:const connectionConfig : AzureClientProps = { connection: { type: "local", tokenProvider: new InsecureTokenProvider("foobar", { id: "user" }), endpoint: "http://localhost:7070" } };
Antes de que se pueda usar el cliente, necesita un
AzureClientProps
que defina el tipo de conexión que usa el cliente. LaconnectionConfig
propiedad es necesaria para conectarse al servicio. Se usa el modo local del cliente de Azure. Para habilitar la colaboración entre todos los clientes, reemplácela por credenciales de Fluid Relay Service. Para más información, consulte configuración del servicio Azure Fluid Relay.Reemplace
TODO: 4
por el código siguiente:const client = new AzureClient(connectionConfig);
Reemplace
TODO: 5
por el código siguiente:export async function createContainer() : Promise<string> { const { container } = await client.createContainer(containerSchema); const containerId = await container.attach(); return containerId; };
A medida que crea el contenedor en la página de configuración y lo anexa a la
contentUrl
configuración de Teams, debe devolver el identificador de contenedor después de adjuntar el contenedor.Reemplace
TODO: 6
por el código siguiente:export async function getContainer(id : string) : Promise<IFluidContainer> { const { container } = await client.getContainer(id, containerSchema); return container; };
Al capturar el contenedor de Fluid, debe devolver el contenedor, ya que la aplicación debe interactuar con el contenedor y los DDS dentro de él, en la página de contenido.
Creación de un contenedor fluid en la página de configuración
Abra el archivo
src/client/<your tab name>/<your tab name>Config.tsx
en el editor de código.El flujo de aplicación de pestaña estándar de Teams va de la configuración a la página de contenido. Para habilitar la colaboración, es fundamental conservar el contenedor mientras se carga en la página de contenido. La mejor solución para conservar el contenedor es anexar el identificador de contenedor a y
contentUrl
websiteUrl
, las direcciones URL de la página de contenido, como parámetro de consulta. El botón Guardar de la página de configuración de Teams es la puerta de enlace entre la página de configuración y la página de contenido. Es un lugar para crear el contenedor y anexar el identificador de contenedor en la configuración.Agregue la siguiente instrucción de importación:
import { createContainer, containerIdQueryParamKey } from "./Util";
Reemplace el método
onSaveHandler
con el siguiente código: Las únicas líneas agregadas aquí son llamar al método create container definido anteriormente enUtils.ts
y, a continuación, anexar el identificador de contenedor devuelto acontentUrl
ywebsiteUrl
como parámetro de consulta.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(); };
Asegúrese de reemplazar por
<your tab name>
el nombre de la pestaña del proyecto.Advertencia
A medida que se usa la dirección URL de la página de contenido para almacenar el identificador de contenedor, este registro se quita si se elimina la pestaña Teams. Además, cada página de contenido solo puede admitir un identificador de contenedor.
Página de refactorización de contenido para reflejar la aplicación Fluid
Abra el archivo
src/client/<your tab name>/<your tab name>.tsx
en el editor de código. Una aplicación típica con tecnología Fluid consta de una vista y una estructura de datos Fluid. Céntrese en obtener o cargar el contenedor fluid y deje todas las interacciones relacionadas con Fluid en un componente de React.Agregue las siguientes instrucciones de importación en la página de contenido:
import { IFluidContainer } from "fluid-framework"; import { getContainer, containerIdQueryParamKey } from "./Util";
Quite todo el código debajo de las instrucciones import de la página de contenido y reemplácelo por lo siguiente:
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. }
Asegúrese de reemplazar por
<your tab name>
el nombre de pestaña que defina para el proyecto.Reemplace
TODO 1
por el código siguiente:microsoftTeams.initialize();
Para mostrar la página de contenido en Teams, debe incluir la biblioteca cliente JavaScript de Microsoft Teams e incluir una llamada para inicializarla una vez que se cargue la página.
Reemplace
TODO 2
por el código siguiente:const [{ inTeams }] = useTeams();
Como la aplicación de Teams es simplemente una inserción de IFrame de una página web, debe inicializar la
inTeams
constante booleana para saber si la aplicación está dentro de Teams o no, y si los recursos de Teams, comocontentUrl
, están disponibles.Reemplace
TODO 3
por el código siguiente:const [fluidContainer, setFluidContainer] = useState<IFluidContainer | undefined>(undefined);
Use un estado react para el contenedor, ya que proporciona la capacidad de actualizar dinámicamente el contenedor y los objetos de datos que contiene.
Reemplace
TODO 4
por el código siguiente: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); };
Analice la dirección URL para obtener la cadena del parámetro de consulta, definida por
containerIdQueryParamKey
y recuperar el identificador de contenedor. Con el identificador de contenedor, puede cargar el contenedor. Una vez que tenga el contenedor, establezca elfluidContainer
estado react, consulte el paso anterior.Reemplace
TODO 5
por el código siguiente:useEffect(() => { if (inTeams === true) { microsoftTeams.settings.getSettings(async (instanceSettings) => { const url = new URL(instanceSettings.contentUrl); getFluidContainer(url.searchParams); }); microsoftTeams.appInitialization.notifySuccess(); } }, [inTeams]);
Después de definir cómo obtener el contenedor fluid, debe indicar a React que llame
getFluidContainer
a la carga y, a continuación, almacenar el resultado en el estado en función de si la aplicación está dentro de Teams. El enlace useState de React proporciona el almacenamiento necesario y useEffect permite llamargetFluidContainer
a en la representación, pasando el valor devuelto asetFluidContainer
.Al agregar
inTeams
en la matriz de dependencias al final de , la aplicación garantiza que solo se llame a esta función en la carga deuseEffect
la página de contenido.Reemplace
TODO 6
por el código siguiente: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> );
Nota:
Es importante asegurarse de que la página de contenido se carga dentro de Teams y de que el contenedor fluid se define antes de pasarlo al componente react (definido como
FluidComponent
, vea a continuación).
Creación de un componente de React para la vista y los datos de Fluid
Ha integrado el flujo de creación básico de Teams y Fluid. Ahora puede crear su propio componente de React que controle las interacciones entre la vista de la aplicación y los datos de Fluid. A partir de ahora, la lógica y el flujo se comportan igual que otras aplicaciones con tecnología Fluid. Con la estructura básica configurada, puede crear cualquiera de los ejemplos de Fluid como una aplicación de Teams cambiando la interacción de la ContainerSchema
vista de aplicación y con los objetos DDSes/data de la página de contenido.
Iniciar el servidor de Fluid y ejecutar la aplicación
Si ejecuta la aplicación de Teams localmente con el modo local cliente de Azure, asegúrese de ejecutar el siguiente comando en el símbolo del sistema para iniciar el servicio Fluid:
npx @fluidframework/azure-local-service@latest
Para ejecutar e iniciar la aplicación de Teams, abra otro terminal y siga las instrucciones para ejecutar el servidor de aplicaciones.
Advertencia
Los nombres de host con ngrok
los túneles gratuitos no se conservan. Cada ejecución genera una dirección URL diferente. Cuando se crea un nuevo ngrok
túnel, ya no se podrá acceder al contenedor anterior. Para escenarios de producción, consulte Uso de AzureClient con Azure Fluid Relay.
Nota:
Instale una dependencia adicional para que esta demostración sea compatible con Webpack 5. Si recibe un error de compilación relacionado con un paquete de "búfer", ejecute npm install -D buffer
e inténtelo de nuevo. Esto se resolverá en una versión futura de Fluid Framework.
Siguientes pasos
Uso de AzureClient con Azure Fluid Relay
Como se trata de una aplicación de pestaña de Teams, la colaboración y la interacción son el foco principal. Reemplace el modo AzureClientProps
local proporcionado anteriormente por las credenciales no locales de la instancia de servicio de Azure para que otros usuarios puedan unirse e interactuar con usted en la aplicación. Consulte cómo aprovisionar el servicio Azure Fluid Relay.
Importante
Es importante ocultar las credenciales que se pasan AzureClientProps
para que no se confirmen accidentalmente en el control de código fuente. El proyecto de Teams incluye un .env
archivo donde puede almacenar sus credenciales como variables de entorno y el propio archivo ya está incluido en ..gitignore
Para usar las variables de entorno en Teams, consulte Establecimiento y obtención de variables de entorno.
Advertencia
InsecureTokenProvider
es una manera cómoda de probar la aplicación localmente. Es su responsabilidad controlar cualquier autenticación de usuario y usar un token seguro para cualquier entorno de producción.
Establecimiento y obtención de una variable de entorno
Para establecer una variable de entorno y recuperarla en Teams, puede aprovechar el archivo integrado .env
. El código siguiente se usa para establecer la variable de entorno en .env
:
# .env
TENANT_KEY=foobar
Para pasar el contenido del .env
archivo a nuestra aplicación del lado cliente, debe configurarlo en webpack.config.js
para que webpack
proporcione acceso a ellos en tiempo de ejecución. Use el código siguiente para agregar la variable de entorno 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
}),
Puede acceder a la variable de entorno en Util.ts
// Util.ts
tokenProvider: new InsecureTokenProvider(JSON.parse(process.env.REACT_APP_TENANT_KEY!), { id: "user" }),
Sugerencia
Al realizar cambios en el código, el proyecto se vuelve a generar automáticamente y el servidor de aplicaciones se vuelve a cargar. Sin embargo, si realiza cambios en el esquema de contenedor, solo surtirán efecto si cierra y reinicia el servidor de aplicaciones. Para ello, vaya al símbolo del sistema y presione Ctrl-C dos veces. A continuación, ejecute gulp serve
o gulp ngrok-serve
de nuevo.