Opções de implantação para soluções da Estrutura do SharePoint no Microsoft Teams

Os desenvolvedores têm várias opções ao implantar soluções de SPFx (Estrutura do SharePoint) para uso no Microsoft Teams. Este artigo explica as opções com suporte no SharePoint Online.

Observação

Antes de janeiro de 2021, o SharePoint Online só suportava uma opção: quando uma solução SPFx válida era carregada para o catálogo de aplicativos de locatários do SharePoint, o botão Sincronizar com o Teams na faixa de opções do catálogo de aplicativos de locatários.

O SharePoint Online oferece suporte a duas opções para a implantação de soluções SPFx para o armazenamento de aplicativos do Microsoft Teams:

  1. Criar automaticamente o manifesto e o pacote do aplicativo Microsoft Teams
  2. Usar o manifesto e o pacote de aplicativos do Microsoft Teams fornecido pelo desenvolvedor

Criar automaticamente o manifesto e o pacote do aplicativo Microsoft Teams

Esse recurso é ideal quando você tem uma implementação simples para expor automaticamente no Microsoft Teams.

Nesse cenário, quando uma solução SPFx é carregada para o catálogo de aplicativos do locatário do SharePoint Online, se a solução contiver componentes para o Microsoft Teams, o botão Sincronizar com o Teams na faixa de opções estará habilitado.

Sincronizar com o Teams

Esse botão iniciará o seguinte processo no SharePoint Online:

  1. O SharePoint criará dinamicamente o arquivo de manifesto do aplicativo Microsoft Teams
  2. O SharePoint criará dinamicamente o pacote de aplicativos do Microsoft Teams
  3. O SharePoint implantará o pacote de aplicativos gerado do Microsoft Teams na loja de aplicativos do Microsoft Teams do locatário

Quando o SharePoint criar o manifesto do aplicativo, ele usará valores da solução SPFx para gerar alguns nomes. A tabela a seguir lista as propriedades no arquivo de manifesto do aplicativo Microsoft Teams e os valores para os quais estão definidas.

Observação

Confira o link a seguir na documentação do Microsoft Teams para obter mais detalhes sobre o manifesto do aplicativo: Esquema de manifesto do Microsoft Teams.

propriedade manifest.json Propriedade no manifesto de componente SPFx
packageName alias
id id
name.short preconfiguredEntries[0].title
description.short preconfiguredEntries[0].description
description.long preconfiguredEntries[0].description

Observação

O manifesto do componente é retirado do manifesto do componente (./src/webparts/.. /*.manifest.json).

Se uma solução SPFx contiver várias Web Parts designadas para uso no Microsoft Teams, o SharePoint Online repetirá o processo acima para cada um delas.

Observação

Se você estiver curioso sobre a estrutura de pacotes gerada, você pode utilizar a seguinte API REST para baixar o pacote para soluções específicas:

_api/web/tenantappcatalog/downloadteamssolution(id)/$value

ID é o identificador numérico da solução na biblioteca do catálogo de aplicativos.

Você pode solicitar essa API no contexto do seu catálogo de aplicativos, por exemplo, com URL de https://[yourtenant]].sharepoint.com/sites/appcatalog/_api/web/tenantappcatalog/downloadteamssolution(12)/$value. A chamada da API iniciará o processo de download do pacote de manifesto gerado.

Manifesto e pacote de aplicativos do Microsoft Teams fornecidos pelo desenvolvedor

Quando precisar de mais controle sobre o manifesto do aplicativo Microsoft Teams ou o pacote de aplicativos, você poderá criar seu próprio pacote. Nesse caso, quando um administrador selecionar o botão Sincronizar com o Teams, o SharePoint Online procurará o seguinte arquivo no arquivo *.sppkg: ./teams/TeamsSPFxApp.zip.

Se esse arquivo estiver presente, o SharePoint Online o implantará na loja de aplicativos do Microsoft Teams do locatário, em vez de criá-lo dinamicamente. Essa opção oferece aos desenvolvedores controle total sobre o manifesto do aplicativo Microsoft Teams e o pacote de aplicativos.

Essa opção é ideal para os seguintes cenários:

  • Os desenvolvedores querem ter controle total sobre o conteúdo do manifesto do aplicativo Microsoft Teams
  • Cenários complexos do Microsoft Teams, como a especificação de bots, aplicativos de reunião etc.
  • Especifique a ID, o nome e a descrição do aplicativo Microsoft Teams quando a solução SPFx contiver mais de um componente. Por exemplo, se uma solução SPFx contiver várias web parts que podem ser usadas como guias no Microsoft Teams, a geração automática do manifesto selecionará um dos dois componentes para usar como ID, nome e descrição do aplicativo do Microsoft Teams.

Para usar seu próprio manifesto de aplicativo e pacote de aplicativo do Microsoft Teams em vez de permitir que o SharePoint Online o crie dinamicamente, faça o seguinte:

  1. Crie um manifesto do aplicativo Microsoft Teams de acordo com a documentação do Microsoft Teams:

    Importante

    no manifesto do aplicativo Teams, certifique-se de adicionar a seguinte entrada:

    "webApplicationInfo": {
    "resource": "https://{teamSiteDomain}",
    "id": "00000003-0000-0ff1-ce00-000000000000"
    }
    

    Isso é necessário para garantir que qualquer chamada à API no componente seja bem-sucedida de clientes avançados do Microsoft Teams. teamSiteDomain será o mesmo locatário que o cliente do Teams está usando. Isso não funcionará entre locatários/domínios, portanto, você não poderá codificar outro domínio.

  2. Crie o pacote de aplicativos do Microsoft Teams chamado TeamsSPFxApp.zip compactando o conteúdo da pasta ./teams.

    Importante

    Não compacte a pasta, em vez disso, compacte o conteúdo da pasta. Se você zipar a pasta, ela será uma subpasta de nível superior para o arquivo ZIP resultante, que não é um pacote de aplicativos válido no Microsoft Teams.

  3. Salve o TeamsSPFxApp.zip na pasta da solução SPFx . /teams.

  4. Crie o pacote SPFx da mesma maneira que você faria com uma solução SPFx normal, usando solução de pacote. Ele incluirá o pacote de aplicativos personalizado do Microsoft Teams *.sppkg.

Fazer referência dinâmica às URLs do site do SharePoint subjacentes

O manifesto do aplicativo Microsoft Teams deve apontar para o local de hospedagem implantado dos componentes do SPFx. No entanto, essas URLs não são conhecidas no momento em que o manifesto do aplicativo Microsoft Teams ou o pacote de aplicativos é criado.

Portanto, quando você especificar o pacote de aplicativos nesta opção de implantação, deverá usar as seguintes cadeias de caracteres que serão substituídas em tempo de execução pelo Microsoft Teams:

  • {teamSiteDomain}: a URL do locatário do SharePoint Online em que a solução SPFx foi implantada e instalada
  • {teamSitePath}: o caminho para o site do SharePoint onde os componentes do SPFx foram instalados
  • {locale}: a localidade atual do cliente do Microsoft Teams

Ao usar uma Web Part em uma solução personalizada do Microsoft Teams, você pode usar essas cadeias de caracteres para definir a URL da página que carregará a Web Part. Por exemplo, use a tabela a seguir como um guia para criar a URL de Web Parts usadas nos aplicativos do Microsoft Teams:

Importante

Nos exemplos a seguir, presume-se que a ID do componente da SPFx seja {{SPFX_COMPONENT_ID}}. Certifique-se de substituir esse valor pela ID de componente da Web Part. Esse valor não é definido dinamicamente pelo SharePoint ou pelo Microsoft Teams: é responsabilidade do desenvolvedor definir esse valor.

Componente do Microsoft Teams Propriedade de manifesto do aplicativo Microsoft Teams Propriedade de manifesto do aplicativo Microsoft Teams
Guia pessoal staticTabs[..].contentUrl https://{teamSiteDomain}/_layouts/15/TeamsLogon.aspx?SPFX=true&dest=/_layouts/15/teamshostedapp.aspx%3Fteams%26personal%26componentId={{SPFX_COMPONENT_ID}}%26forceLocale={locale}
Guia de chat de canal/grupo configurableTabs[..].configurationUrl https://{teamSiteDomain}{teamSitePath}/_layouts/15/TeamsLogon.aspx?SPFX=true&dest={teamSitePath}/_layouts/15/teamshostedapp.aspx%3FopenPropertyPane=true%26teams%26componentId={{SPFX_COMPONENT_ID}}%26forceLocale={locale}
Extensão de mensagem composeExtensions.commands[..].taskInfo.url https://{teamSiteDomain}/_layouts/15/TeamsLogon.aspx?SPFX=true&dest=/_layouts/15/teamstaskhostedapp.aspx%3Fteams%26personal%26componentId={{SPFX_COMPONENT_ID}}%26forceLocale={locale}