Criar conectores para Grupos do Microsoft 365

  • Artigo

Com aplicativos do Microsoft Teams, você pode adicionar seu conector existente para Grupos do Microsoft 365 ou criar um novo no Teams. Para saber mais, veja compilar seu próprio conector.

Confira o vídeo a seguir para saber como criar um conector para Grupos do Microsoft 365:


Observação

Este tópico reflete a versão 2.0.x da biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS). Se você estiver usando uma versão anterior, consulte a visão geral da biblioteca do TeamsJS para obter diretrizes sobre as diferenças entre o TeamsJS mais recente e as versões anteriores.

Adicionar um conector ao aplicativo Teams

Você pode criar um pacote e publicar seu conector como parte do envio do AppSource. Você pode distribuir seu conector registrado como parte do pacote de aplicativos do Teams. Para obter informações sobre pontos de entrada para o aplicativo Teams, consulte capacidades. Você também pode fornecer o pacote diretamente aos usuários para carregar no Teams.

Para distribuir o conector, registre-o no Painel do Desenvolvedor de Conectores.

Para que um conector funcione apenas no Teams, siga as instruções para enviar o conector em publicar seu aplicativo no artigo da Microsoft Teams Store . Caso contrário, um conector registrado funciona em todos os produtos do Microsoft 365 que dão suporte a aplicativos, incluindo Outlook e Teams.

Importante

Seu conector é registrado depois que você seleciona Salvar no Painel do Desenvolvedor de Conectores. Se você quiser publicar seu conector no AppSource, siga as instruções em publique seu aplicativo Microsoft Teams no AppSource. Se você não quiser publicar seu aplicativo no AppSource, distribua-o diretamente para a organização. Após publicar os conectores para sua organização, nenhuma ação adicional será necessária no Painel do Conector.

Integrar a experiência de configuração

Os usuários podem concluir toda a experiência de configuração do conector sem precisar sair do cliente do Teams. Para obter a experiência, o Teams pode inserir sua página de configuração diretamente em um iframe. A sequência de operações é a seguinte:

  1. O usuário seleciona o conector para iniciar o processo de configuração.

  2. O usuário interage com a experiência da Web para concluir a configuração.

  3. O usuário seleciona Salvar, que dispara um retorno de chamada no código.

    Observação

    • O código pode processar o evento de salvamento recuperando as configurações do webhook. Seu código armazena o webhook para postar eventos mais tarde.
    • A experiência de configuração é carregada embutida no Teams.

Você pode reutilizar sua experiência de configuração da Web existente ou criar uma versão separada para ser hospedada especificamente no Teams. Seu código deve incluir a biblioteca do TeamsJS. Isso fornece acesso de código às APIs para executar operações comuns, como obter o contexto atual do usuário, canal ou equipe e iniciar fluxos de autenticação.

Para integrar a experiência de configuração:

Observação

Começando com a biblioteca do TeamsJS v.2.0.0, as APIs no namespace de configurações foram preteridas em favor de APIs equivalentes no namespace de páginas , incluindo pages.getConfig() e outras APIs no pages.config sub-namespace. Para obter mais informações, confira Novidades no TeamsJS versão 2.x.x.

  1. Inicialize o TeamsJS chamando app.initialize().

  2. Chame pages.config.setValidityState(true) para habilitar Salvar.

    Observação

    Você deve chamar microsoftTeams.pages.config.setValidityState(true) como uma resposta à seleção do usuário ou à atualização de campo.

  3. Registre o microsoftTeams.pages.config.registerOnSaveHandler() manipulador de eventos, que é chamado quando o usuário seleciona Salvar.

  4. Chame microsoftTeams.pages.config.setConfig() para salvar as configurações do conector. As configurações salvas também serão mostradas na caixa de diálogo de configuração se o usuário tentar atualizar uma configuração existente para o conector.

  5. Chame microsoftTeams.pages.getConfig() para buscar propriedades de webhook, incluindo a URL.

    Observação

    Você deve chamar microsoftTeams.pages.getConfig() quando a página for carregada pela primeira vez em caso de reconfiguração.

  6. Registre microsoftTeams.pages.config.registerOnRemoveHandler() manipulador de eventos, que é chamado quando o usuário remove o conector.

Esse evento oferece ao seu serviço a oportunidade de executar qualquer ação de limpeza.

O código a seguir fornece um HTML de exemplo para criar uma página de configuração de conector sem o atendimento ao cliente e suporte:

<h2>Send notifications when tasks are:</h2>
<div class="col-md-8">
    <section id="configSection">
        <form id="configForm">
            <input type="radio" name="notificationType" value="Create" onclick="onClick()"> Created
            <br>
            <br>
            <input type="radio" name="notificationType" value="Update" onclick="onClick()"> Updated
        </form>
    </section>
</div>

<script src="https://res.cdn.office.net/teams-js/2.2.0/js/MicrosoftTeams.min.js" integrity="sha384-Q2Z9S56exI6Oz/ThvYaV0SUn8j4HwS8BveGPmuwLXe4CvCUEGlL80qSzHMnvGqee" crossorigin="anonymous"></script>
<script src="/Scripts/jquery-1.10.2.js"></script>

<script>
        function onClick() {
            pages.config.setValidityState(true);
        }

        await microsoftTeams.app.initialize();
        pages.config.registerOnSaveHandler(function (saveEvent) {
            var radios = document.getElementsByName('notificationType');

            var eventType = '';
            if (radios[0].checked) {
                eventType = radios[0].value;
            } else {
                eventType = radios[1].value;
            }

            await pages.config.setConfig({
                entityId: eventType,
                contentUrl: "https://YourSite/Connector/Setup",
                removeUrl:"https://YourSite/Connector/Setup",
                configName: eventType
                });

            pages.getConfig().then(async (config) {
                // We get the Webhook URL from config.webhookUrl which needs to be saved. 
                // This can be used later to send notification.
            });

            saveEvent.notifySuccess();
        });

        pages.config.registerOnRemoveHandler(function (removeEvent) {
            alert("Removed" + JSON.stringify(removeEvent));
        });

</script>

Para autenticar o usuário como parte do carregamento de sua página, consulte fluxo de autenticação para guias para integrar a entrada quando sua página for inserida.

Observação

Antes do TeamsJS v.2.0.0, seu código deve chamar microsoftTeams.authentication.registerAuthenticationHandlers() com a URL e métodos de retorno de chamada de sucesso ou falha antes de chamar authenticate() devido a razões de compatibilidade entre clientes. Começando com TeamsJS v.2.0.0, registerAuthenticationHandlers foi preterido em favor de chamar diretamente authenticate() com os parâmetros de autenticação necessários.

getConfig propriedades de resposta

Observação

Os parâmetros retornados pela getConfig chamada são diferentes quando você invoca esse método de uma guia e difere daqueles documentados na referência.

A tabela a seguir fornece os parâmetros e os detalhes de getConfig propriedades de resposta:

Parâmetros Detalhes
entityId A ID da entidade, conforme definido pelo código ao chamar setConfig().
configName O nome da configuração, conforme definido pelo código ao chamar setConfig().
contentUrl A URL da página de configuração, conforme definido pelo código ao chamar setConfig().
webhookUrl A URL do webhook criada para o conector. Use a URL do webhook para POSTAR JSON estruturado para enviar cartões para o canal. O webhookUrl é retornado somente quando o aplicativo retorna dados com êxito.
appType Os valores retornados podem ser mail, groupsou teams correspondentes ao Microsoft 365 Mail, Grupos do Microsoft 365 ou Teams. Respectivamente.
userObjectId A ID exclusiva correspondente ao usuário do Microsoft 365 que iniciou a instalação do conector. Ele deve ser protegido. Esse valor pode ser usado para associar o usuário no Microsoft 365, que configurou a configuração em seu serviço.

Manipular edições

Seu código deve lidar com usuários que retornam para editar uma configuração de conector existente. Para fazer isso, chame microsoftTeams.pages.config.setConfig() durante a configuração inicial com os seguintes parâmetros:

  • entityId é a ID personalizada que representa o que o usuário configurou e entendeu pelo seu serviço.
  • configName é um nome que o código de configuração pode recuperar.
  • contentUrl é uma URL personalizada que é carregada quando um usuário edita uma configuração de conector existente.

Essa chamada é feita como parte do manipulador de eventos de salvamento. Em seguida, quando o contentUrl é carregado, seu código deve chamar getConfig() para pré-popular quaisquer configurações ou formulários em sua interface de usuário de configuração.

Lidar com remoções

Você pode executar um manipulador de eventos quando o usuário remove uma configuração de conector existente. Registre esse manipulador chamando microsoftTeams.pages.config.registerOnRemoveHandler(). Esse manipulador é usado para executar operações de limpeza, como a remoção de entradas de um banco de dados.

Incluir o conector no manifesto do aplicativo

Baixe o manifesto do aplicativo gerado automaticamente (anteriormente chamado de manifesto do aplicativo Teams) no Portal do Desenvolvedor (https://dev.teams.microsoft.com). Execute as seguintes etapas antes de testar ou publicar o aplicativo:

  1. Incluir dois ícones.
  2. Modifique a icons parte no arquivo de manifesto do aplicativo para incluir os nomes de arquivo dos ícones em vez de URLs.

O exemplo de manifest.json a seguir contém os elementos necessários para testar e enviar o aplicativo:

Observação

Substitua id e connectorId no exemplo a seguir com o GUID do conector.

Exemplo de manifest.json com conector

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "id": "e9343a03-0a5e-4c1f-95a8-263a565505a5",
  "version": "1.0",
  "developer": {
    "name": "Publisher",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.microsoft.com",
    "termsOfUseUrl": "https://www.microsoft.com"
  },
  "description": {
    "full": "This is a small sample app we made for you! This app has samples of all capabilities Microsoft Teams supports.",
    "short": "This is a small sample app we made for you!"
  },
  "icons": {
    "outline": "sampleapp-outline.png",
    "color": "sampleapp-color.png"
  },
  "connectors": [
    {
      "connectorId": "e9343a03-0a5e-4c1f-95a8-263a565505a5",
      "scopes": [
        "team"
      ]
    }
  ],
  "name": {
    "short": "Sample App",
    "full": "Sample App"
  },
  "accentColor": "#FFFFFF",
  "needsIdentity": "true"
}

Testar seu conector

Para testar seu conector, carregue-o em uma equipe com qualquer outro aplicativo. Você pode criar um pacote .zip usando o arquivo de manifesto do aplicativo a partir dos dois arquivos de ícone e do Painel do Desenvolvedor de Conectores, modificado conforme indicado em Incluir o conector no manifesto do aplicativo.

Depois de carregar o aplicativo, abra a lista de conectores de qualquer canal. Role até a parte inferior para ver o aplicativo na seção Carregado.

Captura de tela de uma seção de upload na caixa de diálogo do conector.

Observação

O fluxo ocorre inteiramente no Teams como uma experiência hospedada.

Para verificar se a ação HttpPOST está funcionando corretamente, envie mensagens ao conector.

Siga o guia passo a passo para criar e testar os conectores em seu Teams.

Distribuir webhook e conector

  1. Crie Webhooks de entrada diretamente para sua equipe.

  2. Adicione uma página de configuração e publique seu Webhook de entrada em um conector para Grupos do Microsoft 365.

  3. Empacote e publique seu conector como parte do sua entrega AppSource.

Exemplo de código

A tabela a seguir fornece o nome do exemplo e sua descrição:

Nome de exemplo Descrição .NET Node.js
Notificação TODO do Conector Este exemplo mostra um conector para Grupos do Microsoft 365, que gera e envia notificações para o canal do Teams. View Exibir
Exemplo de conectores genéricos Este exemplo mostra um conector genérico que é fácil de personalizar para qualquer sistema compatível com webhooks. NA View

Guias passo a passo

Siga o a guia passo a passo para criar e testar o conector no Teams.

Confira também