Share via

Usar Fluido com o Teams

  • Artigo

Ao final deste tutorial, você pode integrar qualquer aplicativo movido a fluidos ao Teams e colaborar com outras pessoas em tempo real.

Nesta seção, você pode aprender os seguintes conceitos:

  1. Integrar um cliente Fluid ao aplicativo de guia teams.
  2. Execute e conecte seu aplicativo teams a um serviço Fluid (Retransmissão de Fluidos do Azure).
  3. Crie e obtenha contêineres fluidos e passe-os para um componente React.

Para obter mais informações sobre como criar aplicativos complexos, consulte FluidExamples.

Pré-requisitos

Este tutorial requer familiaridade com os seguintes conceitos e recursos:

Instalar pré-requisitos

Criar o projeto

  1. Abra um Prompt de Comando e navegue até a pasta pai em que você deseja criar o projeto, por exemplo, /My Microsoft Teams Projects.

  2. Crie um aplicativo de guia do Teams executando o seguinte comando e criando uma guia de canal:

    yo teams

  3. Depois de criar, navegue até o projeto, com o comando cd <your project name>a seguir .

  4. O projeto usa 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 do contêiner Fluid.
    @fluidframework/test-client-utils Define o InsecureTokenProvider necessário para criar a conexão com 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

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

  2. Crie um novo arquivo 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";

Definindo funções e parâmetros fluidos

Este aplicativo destina-se a ser usado no contexto do Microsoft Teams, com todas as importações, inicialização e funções relacionadas ao fluido juntas. Isso fornece uma experiência aprimorada e facilita o uso no futuro. Você 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 contêiner.

  1. Substitua TODO 1: pelo código a seguir:

    export const containerIdQueryParamKey = "containerId";

    A constante está sendo exportada à medida que é acrescentada às configurações do contentUrl Microsoft Teams e posterior para analisar a ID do contêiner na página de conteúdo. É um padrão comum armazenar chaves de parâmetro de consulta importantes como constantes, em vez de digitar a cadeia de caracteres bruta sempre.

    Antes que o cliente possa criar contêineres, ele precisa de um containerSchema que defina os objetos compartilhados usados neste aplicativo. Este exemplo usa um SharedMap como o initialObjects, mas qualquer objeto compartilhado pode ser usado.

    Observação

    O map é a ID do SharedMap objeto e deve ser exclusivo dentro do contêiner como qualquer outro DDSes.

  2. Substitua TODO: 2 pelo código a seguir:

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

  3. 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 que o cliente possa ser usado, ele precisa de um AzureClientProps que defina o tipo de conexão que o cliente usa. A connectionConfig propriedade é necessária para se conectar ao serviço. O modo local do Cliente do Azure é usado. Para habilitar a colaboração entre todos os clientes, substitua-a por credenciais do Serviço de Retransmissão fluida. Para obter mais informações, confira como configurar o serviço de Retransmissão de Fluidos do Azure.

  4. Substitua TODO: 4 pelo código a seguir:

    const client = new AzureClient(connectionConfig);

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

    Ao criar o contêiner na página de configuração e anexá-lo à configuração contentUrl no Teams, você deve retornar a ID do contêiner depois de anexar o contêiner.

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

    Ao buscar o contêiner Fluid, você precisa retornar o contêiner, pois seu aplicativo deve interagir com o contêiner e os DDSes dentro dele, na página de conteúdo.

Criar contêiner Fluid na página de configuração

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

    O fluxo de aplicativo da guia Teams padrão vai da configuração para a página de conteúdo. Para habilitar a colaboração, a persistência do contêiner durante o carregamento na página de conteúdo é crucial. A melhor solução para persistir o contêiner é anexar a ID do contentUrl contêiner na página e websiteUrl, as URLs da página de conteúdo, como um parâmetro de consulta. O botão Salvar 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 lugar para criar o contêiner e acrescentar a ID do contêiner nas configurações.

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

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

  3. Substitua o método onSaveHandler com o seguinte código. As únicas linhas adicionadas aqui são chamar o método create container definido anteriormente e, em Utils.ts seguida, acrescentar a ID de contentUrl contêiner retornada ao parâmetro e websiteUrl como uma 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();
};

    Verifique se você substitui <your tab name> pelo nome da guia de seu projeto.

    Aviso

    Como a URL da página de conteúdo é usada para armazenar a ID do contêiner, esse registro será removido se a guia Teams for excluída. Além disso, cada página de conteúdo só pode dar suporte a uma ID de contêiner.

Página de conteúdo do refatorar para refletir o aplicativo Fluid

  1. Abra o arquivo src/client/<your tab name>/<your tab name>.tsx no editor de código. Um aplicativo típico alimentado por fluidos consiste em uma exibição e uma estrutura de dados Fluid. Concentre-se em obter/carregar o contêiner Fluid e deixe todas as interações relacionadas ao Fluid em um componente React.

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

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

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

    Verifique se você substitui <your tab name> pelo nome da guia que você define para seu projeto.

  4. Substitua TODO 1 pelo código a seguir:

    microsoftTeams.initialize();

    Para exibir a página de conteúdo no Teams, você deve incluir a biblioteca de clientes JavaScript do Microsoft Teams e incluir uma chamada para inicializá-la após o carregamento da página.

  5. Substitua TODO 2 pelo código a seguir:

    const [{ inTeams }] = useTeams();

    Como o aplicativo Teams é apenas uma injeção IFrame de uma página da Web, você precisa inicializar a inTeams constante booliana para saber se o aplicativo está dentro do Teams ou não e se os recursos do Teams, como o contentUrl, estão disponíveis.

  6. Substitua TODO 3 pelo código a seguir:

    const [fluidContainer, setFluidContainer] = useState<IFluidContainer | undefined>(undefined);

    Use um estado React para o contêiner, pois ele fornece a capacidade de atualizar dinamicamente o contêiner e os objetos de dados nele.

  7. 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 a URL para obter a cadeia de caracteres do parâmetro de consulta, definida por containerIdQueryParamKey, e recupere a ID do contêiner. Com a ID do contêiner, você pode carregar o contêiner. Depois de ter o contêiner, defina o fluidContainer estado React, consulte a etapa anterior.

  8. 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 contêiner Fluid, você precisa informar React para chamar getFluidContainer no carregamento e armazenar o resultado no estado com base em se o aplicativo estiver dentro do Teams. O gancho useState do React fornece o armazenamento necessário e useEffect permite que você chame getFluidContainer na renderização, passando o valor retornado para setFluidContainer.

    Ao adicionar inTeams a matriz de dependência no final do , o useEffectaplicativo garante que essa função só seja chamada no carregamento da página de conteúdo.

  9. 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údo seja carregada dentro do Teams e que o contêiner Fluid seja definido antes de passá-lo para o componente React (definido como FluidComponent, confira abaixo).

Criar React componente para a exibição fluida e os dados

Você integrou o fluxo de criação básico do Teams e do Fluid. Agora você pode criar seu próprio componente React que lida com as interações entre a exibição do aplicativo e os dados fluidos. A partir de agora, a lógica e o fluxo se comportam como outros aplicativos movidos a fluidos. Com a estrutura básica configurada, você pode criar qualquer um dos exemplos fluidos como um aplicativo do Teams alterando a ContainerSchema interação do modo de exibição do aplicativo com os objetos DDSes/dados na página de conteúdo.

Iniciar o servidor Fluid e executar o aplicativo

Se você estiver executando seu aplicativo teams localmente com o modo local do Cliente do Azure, verifique se você executará o seguinte comando no Prompt de Comando para iniciar o serviço Fluid:

npx @fluidframework/azure-local-service@latest

Para executar e iniciar o aplicativo teams, abra outro terminal e siga as instruções para executar o servidor de aplicativo.

Aviso

HostNames com ngroktúneis gratuitos não são preservados. Cada execução gerará uma URL diferente. Quando um novo ngrok túnel for criado, o contêiner mais antigo não estará mais acessível. Para cenários de produção, consulte usar o AzureClient com o Azure Fluid Relay.

Observação

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

Próximas etapas

Usar o AzureClient com o Azure Fluid Relay

Como este é um aplicativo de guia do Teams, a colaboração e a interação são o foco main. Substitua o modo AzureClientProps local fornecido anteriormente por credenciais não locais de sua instância de serviço do Azure, para que outras pessoas possam ingressar e interagir com você no aplicativo. Confira como provisionar seu serviço de Retransmissão de Fluidos do Azure.

Importante

É importante ocultar as credenciais que você está passando AzureClientProps de serem acidentalmente comprometidas com o controle de origem. O projeto do Teams vem com um .env arquivo em que você pode armazenar suas credenciais como variáveis de ambiente e o arquivo em si já está incluído no .gitignore. Para usar as variáveis de ambiente no Teams, consulte Definir e obter variável de ambiente.

Aviso

InsecureTokenProvider é uma maneira conveniente de testar o aplicativo localmente. É sua responsabilidade lidar com qualquer autenticação de usuário e usar um token seguro para qualquer ambiente de produção.

Definir e obter variável de ambiente

Para definir uma variável de ambiente e recuperá-la no Teams, você pode aproveitar o arquivo interno .env . O código a seguir é usado para definir a variável de ambiente em .env:

# .env

TENANT_KEY=foobar

Para passar o conteúdo do arquivo para nosso .env aplicativo do lado do cliente, você precisa configurá-los webpack.config.js para que webpack forneça acesso a eles em runtime. Use o código a seguir para adicionar a variável de ambiente 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
}),

Você pode acessar a variável de ambiente em Util.ts

// Util.ts

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

Dica

Quando você faz alterações no código, o projeto é recompilado automaticamente e o servidor de aplicativo recarrega. No entanto, se você fizer alterações no esquema de contêiner, elas só entrarão em vigor se você fechar e reiniciar o servidor de aplicativo. Para fazer isso, acesse o Prompt de Comando e pressione Ctrl-C duas vezes. Em seguida, execute gulp serve ou gulp ngrok-serve novamente.

Confira também