Criar um dashboard no Teams

Este guia passo a passo ajuda você a criar uma guia dashboard, adicionar um novo widget ao dashboard e implementar API do Graph. Você verá a seguinte saída:

A captura de tela mostra a saída final do dashboard.

Pré-requisitos

23 minutos restantes

Instalar	Para usar
Visual Studio Code	Ambientes de compilação JavaScript, TypeScript ou Estrutura do SharePoint (SPFx). Use a versão 1.55 ou posterior.
Kit de Ferramentas do Teams ou CLI do TeamsFx	A Microsoft Visual Studio Code extensão que cria um scaffolding de projeto para seu aplicativo. Use o Teams Toolkit v5.
Programa para desenvolvedores do Microsoft 365	Conta do Teams com as permissões apropriadas para instalar um aplicativo.
Node.js	Ambiente de runtime do JavaScript de back-end. Para obter mais informações, consulte Node.js tabela de compatibilidade de versão para o tipo de projeto.
Microsoft Teams	O Microsoft Teams para colaborar com todos com quem você trabalha por meio de aplicativos para chat, reuniões e chamadas em um só lugar.
Microsoft Edge (recomendado) ou Google Chrome	Um navegador com ferramentas de desenvolvedor.

Criar um novo dashboard

22 minutos restantes

O Teams Toolkit dá suporte à criação de scaffolding e dashboard.

Para criar um novo dashboard:

Selecione o ícone Kit de Ferramentas do Teams na Barra de Atividades Visual Studio Code.
Selecione Criar um Novo Aplicativo.
Selecione Guia para criar um projeto de guia.
Selecione Painel.
Selecione TypeScript como a linguagem de programação.
Selecione Pasta padrão para armazenar sua pasta raiz do projeto no local padrão.
Insira um nome adequado para seu aplicativo e selecione Inserir.

O Teams Toolkit cria um aplicativo de guia em poucos segundos e exibe uma mensagem.
Selecione o ícone Kit de Ferramentas do Teams na barra lateral.
Selecione Entrar no Microsoft 365. Uma mensagem de aviso será exibida.
Selecione Entrar.
Selecione a chave F5 para executar o aplicativo no modo de depuração.
Selecione Adicionar.

O aplicativo de guia teams dashboard foi criado com êxito.

O aplicativo Teams também dá suporte a temas diferentes, incluindo temas escuros e de alto contraste.
- Tema escuro
- Tema de alto contraste
A imagem a seguir mostra o uso do tema Escuro no cliente da área de trabalho do Teams:

A imagem a seguir mostra o uso do tema Alto contraste no cliente da área de trabalho do Teams:

Na CLI do TeamsFX,

Se preferir o modo interativo, execute teamsfx new o comando e use o teclado para passar pelo mesmo fluxo que em Visual Studio Code.
Se preferir o modo não interativo, insira todos os parâmetros necessários em um comando:

teamsfx new--interactive false--capabilities "dashboard-tab"--programming-language "TypeScript"--folder "./"--app-name dashboard-cli-001

Faça um tour pelo código-fonte do aplicativo

22 minutos restantes

A implementação do dashboard principal está na pasta guias. Esta seção orienta você pelo código gerado.

Folder	Conteúdos
`.vscode`	Arquivos VSCode para depuração.
`appPackage`	Modelos para o manifesto do aplicativo teams.
`env`	Arquivos de ambiente.
`infra`	Modelos para provisionar recursos do Azure.
`src`	O código-fonte do aplicativo dashboard Teams.

Os arquivos a seguir fornecem a lógica de negócios para a guia dashboard. Esses arquivos podem ser atualizados para atender aos requisitos lógicos de negócios. A implementação padrão fornece um ponto de partida para ajudá-lo a começar.

Arquivo	Conteúdos
`src/models/chartModel.ts`	Modelo de dados para o widget do gráfico.
`src/models/listModel.ts`	Modelo de dados para o widget de lista.
`src/services/chartService.ts`	Uma implementação de recuperação de dados para o widget do gráfico.
`src/services/listService.ts`	Uma implementação de recuperação de dados para o widget de lista.
`src/dashboards/SampleDashboard.tsx`	Um exemplo dashboard implementação de layout.
`src/styles/ChartWidget.css`	O arquivo de estilo de widget do gráfico.
`src/styles/ListWidget.css`	O arquivo de estilo de widget de lista.
`src/widgets/ChartWidget.tsx`	Uma implementação de widget que pode exibir um gráfico.
`src/widgets/ListWidget.tsx`	Uma implementação de widget que pode exibir uma lista.
`src/App.css`	O estilo da rota do aplicativo.
`src/App.tsx`	Rota do aplicativo.

Os arquivos a seguir são arquivos relacionados ao projeto. Geralmente, você não precisa personalizar esses arquivos.

Arquivo	Conteúdos
`src/index.css`	O estilo do ponto de entrada do aplicativo.
`src/index.tsx`	Ponto de entrada do aplicativo.
`src/internal/addNewScopes.ts`	A implementação de novos escopos é adicionada.
`src/internal/context.ts`	Contexto TeamsFx.
`src/internal/login.ts`	Implementação do logon.
`src/internal/singletonContext.ts`	Implementação da instância teamsUserCredential singleton.

Adicionar um widget ao dashboard

20 minutos restantes

Para adicionar um novo widget ao dashboard, siga estas etapas:

Definir um modelo de dados
Criar um serviço de recuperação de dados
Criar um arquivo widget
Adicione o widget ao dashboard

Definir um modelo de dados

Em Visual Studio Code, acessemodelossrc>do EXPLORER>.
Crie um arquivo sampleModel.ts .

Adicione o seguinte código no arquivo sampleModel.ts :

  export interface SampleModel {
  content: string;
  }

A captura de tela mostra a criação do arquivo sampleModel na pasta modelos em Visual Studio Code.

Criar um serviço de recuperação de dados

Observação

Você pode implementar um serviço para recuperar dados do serviço de back-end ou do Microsoft API do Graph.

Em Visual Studio Code, vá paraos serviços do EXPLORER>src>.
Crie um arquivo sampleService.ts .

Adicione o seguinte código no arquivo sampleService.ts :

import { SampleModel } from "../models/sampleModel";

export const getSampleData = (): SampleModel => {
  return { content: "Hello world!" };
  };

A captura de tela mostra a criação do arquivo sampleService.ts na pasta de serviço em Visual Studio Code.

Em Visual Studio Code, acessewidgetssrc> do EXPLORER>.
Crie um arquivo SampleWidget.tsx .

Adicione o seguinte código no arquivo SampleWidget.tsx :

import { Button, Text } from "@fluentui/react-components";
import { BaseWidget } from "@microsoft/teamsfx-react";
import { SampleModel } from "../models/sampleModel";
import { getSampleData } from "../services/sampleService";

interface SampleWidgetState {
  data?: SampleModel;
}

export class SampleWidget extends BaseWidget<any, SampleWidgetState> {
  override async getData(): Promise<SampleWidgetState> {
    return { data: getSampleData() };
  }

  override header(): JSX.Element | undefined {
    return <Text>Sample Widget</Text>;
  }

  override body(): JSX.Element | undefined {
    return <div>{this.state.data?.content}</div>;
  }
  override footer(): JSX.Element | undefined {
    return <Button>View Details</Button>;
  }
}

Para adicionar um widget ao dashboard, siga estas etapas:

Em Visual Studio Code, acesse Explorer>src>dashboards>SampleDashboard.tsx.

Atualize o override layout() método para adicionar o widget ao dashboard:

override layout(): JSX.Element | undefined {
  return (
    <>
      <ListWidget />
      <ChartWidget />
      <SampleWidget />
    </>
  );
}

A captura de tela mostra o arquivo sampleDashboard existente no Visual Studio Code.

Opcional: se você quiser adicionar seu widget em uma coluna, você pode consultar o seguinte código:

.one-column {
  display: grid;
  gap: 20 px;
  grid-template-rows: 1fr 1fr;
}

override layout(): JSX.Element | undefined {
  return (
    <>
      <ListWidget />
      <div className="one-column">
        <ChartWidget />
        <SampleWidget />
      </div>
   </>
  );
}

Depois de adicionar todos os detalhes relevantes para criar um widget, salve os respectivos arquivos.

Você pode exibir o layout alterado e o widget de calendário no dashboard.

Adicionar chamada SSO e API do Graph

15 minutos restantes

Você aprendeu a criar uma guia dashboard e adicionar um novo widget ao dashboard. Vamos adicionar o SSO (Logon Único) e a chamada de API de grafo à guia dashboard.

Adicionar SSO

Para adicionar o SSO, siga estas etapas:

1. Criar manifesto de aplicativo do Azure Active Directory (Azure AD).

Para criar Azure AD manifesto do aplicativo, siga estas etapas:

Em Visual Studio Code, vá para EXPLORER.
Crie um arquivo aad.manifest.json .

Adicione o seguinte código no arquivo aad.manifest.json :

{
  "id": "${{AAD_APP_OBJECT_ID}}",
  "appId": "${{AAD_APP_CLIENT_ID}}",
  "name": "dashboardV5Demo",
  "accessTokenAcceptedVersion": 2,
  "signInAudience": "AzureADMyOrg",
  "optionalClaims": {
      "idToken": [],
      "accessToken": [
          {
            "name": "idtyp",
            "source": null,
            "essential": false,
            "additionalProperties": []
          }
      ],
      "saml2Token": []
  },
  "requiredResourceAccess": [
      {
        "resourceAppId": "Microsoft Graph",
        "resourceAccess": [
            {
              "id": "User.Read",
              "type": "Scope"
            }
        ]
      }
  ],
  "oauth2Permissions": [
      {
        "adminConsentDescription": "Allows Teams to call the app's web APIs as the current user.",
        "adminConsentDisplayName": "Teams can access app's web APIs",
        "id": "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}",
        "isEnabled": true,
        "type": "User",
        "userConsentDescription": "Enable Teams to call this app's web APIs with the same rights that you have",
        "userConsentDisplayName": "Teams can access app's web APIs and make requests on your behalf",
        "value": "access_as_user"
      }
  ],
  "preAuthorizedApplications": [
      {
          "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
          "permissionIds": [
              "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
          ]
      },
      {
          "appId": "5e3ce6c0-2b1f-4285-8d4b-75ee78787346",
          "permissionIds": [
              "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
          ]
      },
      {
          "appId": "d3590ed6-52b3-4102-aeff-aad2292ab01c",
          "permissionIds": [
              "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
          ]
      },
      {
          "appId": "00000002-0000-0ff1-ce00-000000000000",
          "permissionIds": [
              "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
          ]
      },
      {
          "appId": "bc59ab01-8403-45c6-8796-ac3ef710b3e3",
          "permissionIds": [
              "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
          ]
      },
      {
          "appId": "0ec893e0-5785-4de6-99da-4ed124e5296c",
          "permissionIds": [
              "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
          ]
      },
      {
          "appId": "4765445b-32c6-49b0-83e6-1d93765276ca",
          "permissionIds": [
              "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
          ]
      },
      {
          "appId": "4345a7b9-9a63-4910-a426-35363201d503",
          "permissionIds": [
              "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
          ]
      }
  ],
  "identifierUris": [
    "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"
  ],
  "replyUrlsWithType": [
    {
      "url": "${{TAB_ENDPOINT}}/auth-end.html",
      "type": "Web"
    },
    {
      "url": "${{TAB_ENDPOINT}}/auth-end.html?clientId=${{AAD_APP_CLIENT_ID}}",
      "type": "Spa"
    },
    {
      "url": "${{TAB_ENDPOINT}}/blank-auth-end.html",
      "type": "Spa"
    }
  ]
}

A captura de tela mostra a adição de código de dirctory ativo do azure.

2. Atualizar o manifesto do aplicativo Teams.

Para atualizar o manifesto do aplicativo teams, siga estas etapas:

Em Visual Studio Code, acesse EXPLORER>appPackage>manifest.json.

Adicione o seguinte código após validdomain a propriedade no arquivo manifest.json :

  "webApplicationInfo": {
  "id": "${{AAD_APP_CLIENT_ID}}",
  "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"
  }

A captura de tela mostra a adição de informações do aplicativo Web no manifesto.

3. Atualizar arquivos de configuração do Teams Toolkit.

Para atualizar o código de configuração do Teams Toolkit em arquivos teamsapp.yml e teamsapp.local.yml , siga as etapas:

teamsapp.yml
teamsapp.local.yml

Adicione o código em provisionamento.

  - uses: aadApp/create
    with:
        name: "YOUR_AAD_APP_NAME"
        generateClientSecret: true
        signInAudience: "AzureADMyOrg"
    writeToEnvironmentFile:
        clientId: AAD_APP_CLIENT_ID
        clientSecret: SECRET_AAD_APP_CLIENT_SECRET
        objectId: AAD_APP_OBJECT_ID
        tenantId: AAD_APP_TENANT_ID
        authority: AAD_APP_OAUTH_AUTHORITY
        authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST

  - uses: aadApp/update
    with:
      manifestPath: "./aad.manifest.json"
      outputFilePath : ./build/aad.manifest.${{TEAMSFX_ENV}}.json

A captura de tela mostra a adição do código aadApp/create e aadApp/update.

Na ação cli/runNpmCommand e no build app nome, adicione o seguinte código:

  env:
  REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
  REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html

A captura de tela mostra as informações para reagir ao código da cli.

Adicione o código em provisionamento.

  - uses: aadApp/create
    with:
        name: "YOUR_AAD_APP_NAME"
        generateClientSecret: true
        signInAudience: "AzureADMyOrg"
    writeToEnvironmentFile:
        clientId: AAD_APP_CLIENT_ID
        clientSecret: SECRET_AAD_APP_CLIENT_SECRET
        objectId: AAD_APP_OBJECT_ID
        tenantId: AAD_APP_TENANT_ID
        authority: AAD_APP_OAUTH_AUTHORITY
        authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST

  - uses: aadApp/update
    with:
      manifestPath: "./aad.manifest.json"
      outputFilePath : ./build/aad.manifest.${{TEAMSFX_ENV}}.json

A captura de tela mostra a adição do código aadApp/create e aadApp/update.

Na ação file/createOrUpdateEnvironmentFile**, adicione o seguinte código:

  REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
  REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html

A captura de tela mostra as informações para reagir códigos.

4. Atualizar código-fonte.

Crie arquivosauth-start.html e auth-end.html na pasta pública .

Adicione o código em arquivosauth-start.html e auth-end.html .

auth-start
auth-end

Adicione o seguinte código no auth-start.html:

  <!--This file is used during the Teams authentication flow to assist with retrieval of the access token.-->
  <!--If you're not familiar with this, do not alter or remove this file from your project.-->
  <html>
    <head>
      <title>Login Start Page</title>
      <meta charset="utf-8" />
    </head>

    <body>
    <script src="https://res.cdn.office.net/teams-js/2.7.1/js/MicrosoftTeams.min.js" integrity="sha384-4Gy2G+qxzDVdrdemcVqKVQvaSK1Ghg3x6xcsaMLPc/pw7KPtiogHGM97LTWF2PWg" crossorigin="anonymous"></script>
      <script
        type="text/javascript"
        src="https://alcdn.msauth.net/browser/2.21.0/js/msal-browser.min.js"
        integrity="sha384-s/NxjjAgw1QgpDhOlVjTceLl4axrp5nqpUbCPOEQy1PqbFit9On6uw2XmEF1eq0s"
        crossorigin="anonymous">
      </script>
      <script type="text/javascript">
        microsoftTeams.app.initialize().then(() => {
          microsoftTeams.app.getContext().then(async (context) => {
            // Generate random state string and store it, so we can verify it in the callback
            var currentURL = new URL(window.location);
            var clientId = currentURL.searchParams.get("clientId");
            var scope = currentURL.searchParams.get("scope");
            var loginHint = currentURL.searchParams.get("loginHint");

            const msalConfig = {
              auth: {
                clientId: clientId,
                authority: `https://login.microsoftonline.com/${context.user.tenant.id}`,
                navigateToLoginRequestUrl: false
              },
              cache: {
                cacheLocation: "sessionStorage",
              },
            }

            const msalInstance = new msal.PublicClientApplication(msalConfig);
            const scopesArray = scope.split(" ");
            const scopesRequest = {
              scopes: scopesArray,
              redirectUri: window.location.origin + `/auth-end.html?clientId=${clientId}`,
              loginHint: loginHint
            };
            await msalInstance.loginRedirect(scopesRequest);
          });
        });
        </script>
    </body>
  </html>

Adicione o seguinte código no auth-end.html:

  <!--This file is used during the Teams authentication flow to assist with retrieval of the access token.-->
  <!--If you're not familiar with this, do not alter or remove this file from your project.-->
  <html>
    <head>
      <title>Login End Page</title>
      <meta charset="utf-8" />
    </head>

    <body>
    <script src="https://res.cdn.office.net/teams-js/2.7.1/js/MicrosoftTeams.min.js" integrity="sha384-4Gy2G+qxzDVdrdemcVqKVQvaSK1Ghg3x6xcsaMLPc/pw7KPtiogHGM97LTWF2PWg" crossorigin="anonymous"></script>
      <script
        type="text/javascript"
        src="https://alcdn.msauth.net/browser/2.21.0/js/msal-browser.min.js"
        integrity="sha384-s/NxjjAgw1QgpDhOlVjTceLl4axrp5nqpUbCPOEQy1PqbFit9On6uw2XmEF1eq0s"
        crossorigin="anonymous">
      </script>
      <script type="text/javascript">
        var currentURL = new URL(window.location);
        var clientId = currentURL.searchParams.get("clientId");

        microsoftTeams.app.initialize().then(() => {
          microsoftTeams.app.getContext().then(async (context) => {
            const msalConfig = {
              auth: {
                clientId: clientId,
                authority: `https://login.microsoftonline.com/${context.user.tenant.id}`,
                navigateToLoginRequestUrl: false
              },
              cache: {
                cacheLocation: "sessionStorage",
              },
            }

            const msalInstance = new window.msal.PublicClientApplication(msalConfig);
            msalInstance.handleRedirectPromise()
              .then((tokenResponse) => {
                if (tokenResponse !== null) {
                  microsoftTeams.authentication.notifySuccess(JSON.stringify({
                    sessionStorage: sessionStorage
                  }));
                } else {
                  microsoftTeams.authentication.notifyFailure("Get empty response.");
                }
              })
              .catch((error) => {
                microsoftTeams.authentication.notifyFailure(JSON.stringify(error));
              });
          });
        });
      </script>
    </body>
  </html>

Você adicionou os arquivos SSO ao seu projeto e agora chama APIs do Graph.

Adicionar API do Graph chamada

Para adicionar API do Graph, siga estas etapas:

A chamada de API do grafo é implementada por meio do SDK do TeamsFx.

Em Visual Studio Code, acesse EXPLORER>src>services>listService.ts.

Atualize o seguinte código no listService.ts:

/**
  * Retrive sample data
  * @returns data for list widget
  */
import {TeamsUserCredentialContext} from "../internal/singletonContext";
import {
  createMicrosoftGraphClientWithCredential,
  TeamsUserCredential,
  } from "@microsoft/teamsfx";
  import { ListModel } from "../models/listModel";
  import { loginAction } from "../internal/login";

export const getListData = async (): Promise<ListModel[]> => {
  await loginAction(["User.Read"]);
  let credential = TeamsUserCredentialContext.getInstance().getCredential();
  const graphClient = createMicrosoftGraphClientWithCredential(credential, [
    "User.Read",
  ]);
  const me = await graphClient.api("/me").get();
  return [
    {
      id: me.id,
      title: me.displayName,
      content: me.mail,
    },
  ];

  // {
  //   id: "id1",
  //   title: "Lorem ipsum",
  //   content: "Lorem ipsum dolor sit amet",
  // },
  // {
  //   id: "id2",
  //   title: "Lorem ipsum",
  //   content: "Lorem ipsum dolor sit amet",
  // },
  // {
  //   id: "id3",
  //   title: "Lorem ipsum",
  //   content: "Lorem ipsum dolor sit amet",
  // },
}

Acesse Explorer>src>services>ListWidget.tsx.

Atualize o para adicionar widget export default class ListWidget() pofile do usuário.

 export default class ListWidget extends BaseWidget<any, IListWidgetState> {
   async getData(): Promise<IListWidgetState> {
     return { data: await getListData() };

SSO e API do Graph mostra o perfil de usuário de logon no widget de lista.

Desafio completo

10 minutos restantes

Você veio com algo assim?