Utilizar o Fluid com o Teams

Artigo
06/26/2024

No final deste tutorial, pode integrar qualquer aplicação com tecnologia Fluid no Teams e colaborar com outras pessoas em tempo real.

Nesta secção, pode aprender os seguintes conceitos:

Integrar um cliente Fluid na aplicação de separador Teams.
Execute e ligue a sua aplicação do Teams a um serviço Fluid (Azure Fluid Relay).
Crie e obtenha Contentores de Fluidos e transmita-os para um componente do React.

Para obter mais informações sobre a criação de aplicações complexas, veja FluidExamples.

Pré-requisitos

Este tutorial requer familiaridade com os seguintes conceitos e recursos:

Descrição Geral do Fluid Framework
Início Rápido do Fluid Framework
As noções básicas do React e do React Hooks
Como criar um Separador do Microsoft Teams

Instalar pré-requisitos

Criar o projeto

Abra uma Linha de Comandos e navegue para a pasta principal onde pretende criar o projeto, por exemplo, /My Microsoft Teams Projects.
Crie uma aplicação de separador do Teams ao executar o seguinte comando e ao criar um separador de canal:
```
yo teams
```
Depois de criar, navegue para o projeto, com o seguinte comando cd <your project name>.

O projeto utiliza as seguintes bibliotecas:

Biblioteca	Descrição
`fluid-framework`	Contém o IFluidContainer e outras estruturas de dados distribuídas que sincronizam dados entre clientes.
`@fluidframework/azure-client`	Define o esquema inicial para o contentor Fluid.
`@fluidframework/test-client-utils`	Define o `InsecureTokenProvider` necessário para criar a ligação a um serviço Fluid.

Execute o seguinte comando para instalar as bibliotecas:

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

Codificar o projeto

Abra o ficheiro /src/client/<your tab name> no editor de código.

Crie um novo ficheiro como Util.ts e adicione as seguintes instruções de importação:

//`Util.ts

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

Definir funções e parâmetros do Fluid

Esta aplicação destina-se a ser utilizada no contexto do Microsoft Teams, com todas as importações, inicialização e funções relacionadas com o Fluid em conjunto. Isto proporciona uma experiência melhorada e facilita a sua utilização no futuro. Pode adicionar o seguinte código às instruções de importação:

// 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.

Observação

Os comentários definem todas as funções e constantes necessárias para interagir com o serviço Fluid e o contentor.

Substitua TODO 1: pelo código a seguir:
```
export const containerIdQueryParamKey = "containerId";
```
A constante está a ser exportada à medida que é acrescentada às contentUrl definições do Microsoft Teams e posteriormente para analisar o ID do contentor na página de conteúdo. É um padrão comum armazenar chaves de parâmetros de consulta importantes como constantes, em vez de escrever sempre a cadeia não processada.

Antes de o cliente poder criar contentores, precisa de um containerSchema que defina os objetos partilhados utilizados nesta aplicação. Este exemplo utiliza um SharedMap como o initialObjects, mas qualquer objeto partilhado pode ser utilizado.

Observação

O map é o ID do SharedMap objeto e tem de ser exclusivo no contentor como qualquer outro DDSes.

Substitua TODO: 2 pelo código a seguir:

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

Substitua TODO: 3 pelo código a seguir:
```
const connectionConfig : AzureClientProps =
{
    connection: {
        type: "local",
        tokenProvider: new InsecureTokenProvider("foobar", { id: "user" }),
        endpoint: "http://localhost:7070"
    }
};
```
Antes de o cliente poder ser utilizado, precisa de um AzureClientProps que defina o tipo de ligação que o cliente utiliza. A connectionConfig propriedade é necessária para ligar ao serviço. É utilizado o modo local do Cliente do Azure. Para permitir a colaboração em todos os clientes, substitua-a pelas credenciais do Serviço de Reencaminhamento de Fluidos. Para obter mais informações, veja como configurar o serviço Azure Fluid Relay.

Substitua TODO: 4 pelo código a seguir:

const client = new AzureClient(connectionConfig);

Substitua TODO: 5 pelo código a seguir:

export async function createContainer() : Promise<string> {
    const { container } = await client.createContainer(containerSchema);
    const containerId = await container.attach();
    return containerId;
};

À medida que cria o contentor na página de configuração e o contentUrl acrescenta à definição no Teams, tem de devolver o ID do contentor depois de anexar o contentor.

Substitua TODO: 6 pelo código a seguir:
```
export async function getContainer(id : string) : Promise<IFluidContainer> {
    const { container } = await client.getContainer(id, containerSchema);
    return container;
};
```
Quando obtém o contentor Fluid, tem de devolver o contentor, uma vez que a sua aplicação tem de interagir com o contentor e os DDSes dentro do mesmo, na página de conteúdo.

Criar um contentor fluido na página de configuração

Abra o ficheiro src/client/<your tab name>/<your tab name>Config.tsx no editor de código.

O fluxo de aplicação de separador padrão do Teams vai da configuração para a página de conteúdo. Para ativar a colaboração, manter o contentor ao carregar para a página de conteúdo é crucial. A melhor solução para manter o contentor é acrescentar o ID de contentor ao contentUrl e websiteUrl, os URLs da página de conteúdo, como um parâmetro de consulta. O botão Guardar na página de configuração do Teams é o gateway entre a página de configuração e a página de conteúdo. É um local para criar o contentor e acrescentar o ID do contentor nas definições.

Adicione a seguinte declaração de importação:

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

Substitua o método onSaveHandler com o seguinte código. As únicas linhas adicionadas aqui são chamar o método criar contentor definido anteriormente em e, em Utils.ts seguida, acrescentar o ID de contentor devolvido ao contentUrl e websiteUrl como um 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();
};

Certifique-se de que substitui <your tab name> pelo nome do separador do projeto.

Aviso

Como o URL da página de conteúdo é utilizado para armazenar o ID de contentor, este registo é removido se o separador Teams for eliminado. Além disso, cada página de conteúdo só pode suportar um ID de contentor.

Refatorizar página de conteúdo para refletir a aplicação Fluid

Abra o ficheiro src/client/<your tab name>/<your tab name>.tsx no editor de código. Uma aplicação típica com tecnologia Fluid consiste numa vista e numa estrutura de dados fluidas. Concentre-se em obter/carregar o contentor Fluid e deixe todas as interações relacionadas com o Fluido num componente do React.

Adicione as seguintes instruções de importação na página de conteúdo:

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

Remova todo o código abaixo das instruções de importação na página de conteúdo e substitua-o pelo seguinte:

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.
}

Certifique-se de que substitui <your tab name> pelo nome do separador definido para o projeto.

Substitua TODO 1 pelo código a seguir:
```
microsoftTeams.initialize();
```
Para apresentar a página de conteúdo no Teams, tem de incluir a biblioteca de cliente JavaScript do Microsoft Teams e incluir uma chamada para a inicializar após o carregamento da sua página.
Substitua TODO 2 pelo código a seguir:
```
const [{ inTeams }] = useTeams();
```
Uma vez que a aplicação Teams é apenas uma injeção de IFrame de uma página Web, tem de inicializar a inTeams constante booleana para saber se a aplicação está ou não dentro do Teams e se os recursos do Teams, como o contentUrl, estão disponíveis.
Substitua TODO 3 pelo código a seguir:
```
const [fluidContainer, setFluidContainer] = useState<IFluidContainer | undefined>(undefined);
```
Utilize um estado do React para o contentor, uma vez que proporciona a capacidade de atualizar dinamicamente o contentor e os objetos de dados no mesmo.

Substitua TODO 4 pelo código a seguir:

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

Analise o URL para obter a cadeia do parâmetro de consulta, definida por containerIdQueryParamKeye obter o ID do contentor. Com o ID do contentor, pode carregar o contentor. Assim que tiver o contentor, defina o estado react fluidContainer , veja o passo anterior.

Substitua TODO 5 pelo código a seguir:
```
useEffect(() => {
    if (inTeams === true) {
        microsoftTeams.settings.getSettings(async (instanceSettings) => {
            const url = new URL(instanceSettings.contentUrl);
            getFluidContainer(url.searchParams);
        });
        microsoftTeams.appInitialization.notifySuccess();
    }
}, [inTeams]);
```
Depois de definir como obter o contentor fluido, tem de indicar ao React para chamar getFluidContainer a carga e, em seguida, armazenar o resultado em estado com base no caso de a aplicação estar dentro do Teams. UseState hook do React fornece o armazenamento necessário e useEffect permite-lhe chamar getFluidContainer na composição, transmitindo o valor devolvido para setFluidContainer.

Ao adicionar inTeams na matriz de dependências no final do , a aplicação garante que esta função só é chamada no carregamento da página de useEffectconteúdo.

Substitua TODO 6 pelo código a seguir:

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

Observação

É importante garantir que a página de conteúdos é carregada no Teams e que o contentor Fluid é definido antes de o transmitir para o componente react (definido como FluidComponent, consulte abaixo).

Criar componente do React para a vista fluida e os dados

Integrou o fluxo básico de criação do Teams e do Fluid. Agora, pode criar o seu próprio componente react que processa as interações entre a vista de aplicação e os dados do Fluid. A partir de agora, a lógica e o fluxo comportam-se tal como outras aplicações com tecnologia Fluid. Com a estrutura básica configurada, pode criar qualquer um dos exemplos do Fluid como uma aplicação do Teams ao alterar a ContainerSchema interação da vista e da aplicação com os objetos DDSes/dados na página de conteúdo.

Iniciar o Servidor de fluidos e executar a aplicação

Se estiver a executar a sua aplicação do Teams localmente com o modo local do Cliente do Azure, certifique-se de que executa o seguinte comando na Linha de Comandos para iniciar o serviço Fluid:

npx @fluidframework/azure-local-service@latest

Para executar e iniciar a aplicação Teams, abra outro terminal e siga as instruções para executar o servidor de aplicações.

Aviso

Os HostNames com ngroktúneis livres não são preservados. Cada execução gera um URL diferente. Quando é criado um novo ngrok túnel, o contentor mais antigo deixará de estar acessível. Para cenários de produção, veja Utilizar o AzureClient com o Azure Fluid Relay.

Observação

Instale uma dependência adicional para tornar esta demonstração compatível com o Webpack 5. Se receber um erro de compilação relacionado com um pacote "buffer", execute npm install -D buffer e tente novamente. Isto será resolvido numa versão futura do Fluid Framework.

Próximas etapas

Utilizar o AzureClient com o Azure Fluid Relay

Uma vez que se trata de uma aplicação de separador do Teams, a colaboração e a interação são o foco principal. Substitua o modo AzureClientProps local fornecido anteriormente por credenciais não locais da sua instância de serviço do Azure, para que outras pessoas possam participar e interagir consigo na aplicação. Veja como aprovisionar o serviço Azure Fluid Relay.

Importante

É importante ocultar as credenciais que está a transmitir AzureClientProps de serem acidentalmente consolidadas no controlo de origem. O projeto do Teams inclui um .env ficheiro onde pode armazenar as suas credenciais como variáveis de ambiente e o próprio ficheiro já está incluído no .gitignore. Para utilizar as variáveis de ambiente no Teams, veja Definir e obter a variável de ambiente.

Aviso

InsecureTokenProvider é uma forma conveniente de testar a aplicação localmente. É da sua responsabilidade processar qualquer autenticação de utilizador e utilizar um token seguro para qualquer ambiente de produção.

Definir e obter variável de ambiente

Para definir uma variável de ambiente e obtê-la .env no Teams, pode tirar partido do ficheiro incorporado. O código seguinte é utilizado para definir a variável de ambiente em .env:

# .env

TENANT_KEY=foobar

Para transmitir o conteúdo do .env ficheiro para a nossa aplicação do lado do cliente, tem de configurá-los webpack.config.js para que webpack lhes forneça acesso no runtime. Utilize o seguinte código para adicionar a variável de ambiente a 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
}),

Pode aceder à variável de ambiente em Util.ts

// Util.ts

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

Dica

Quando efetua alterações ao código, o projeto reconstrói automaticamente e o servidor de aplicações é recarregado. No entanto, se fizer alterações ao esquema de contentor, estas só entrarão em vigor se fechar e reiniciar o servidor de aplicações. Para tal, aceda à Linha de Comandos e prima Ctrl-C duas vezes. Em seguida, execute gulp serve ou gulp ngrok-serve novamente.

Compartilhar via

Utilizar o Fluid com o Teams

Pré-requisitos

Criar o projeto

Codificar o projeto

Definir funções e parâmetros do Fluid

Criar um contentor fluido na página de configuração

Refatorizar página de conteúdo para refletir a aplicação Fluid

Criar componente do React para a vista fluida e os dados

Iniciar o Servidor de fluidos e executar a aplicação

Próximas etapas

Utilizar o AzureClient com o Azure Fluid Relay

Definir e obter variável de ambiente

Confira também

Comentários

Recursos adicionais