Compartilhar via

Criar conectores para Grupos do Microsoft 365

  • Artigo

Importante

Os Conectores do Microsoft 365 (anteriormente denominados conectores Office 365) estão prestes a descontinuar e a criação de novos Conectores do Microsoft 365 será bloqueada em breve. Para obter mais informações sobre a agenda e como a aplicação Fluxos de Trabalho fornece uma experiência mais flexível e segura, veja Descontinuação dos conectores do Microsoft 365 no Microsoft Teams.

Como pode criar um webhook no Teams?

Se já tiver criado Office 365 Conectores:

  • Criar um conector do Power Automate: o Power Automate melhora as aplicações de Fluxos de Trabalho amplamente utilizadas no Teams. É a abordagem dimensionável e segura para transmitir dados através de programação para dentro e para fora do Teams. Se adotar este método, pode criar modelos de fluxo de trabalho para publicar alertas do seu produto em canais do Teams. Esta abordagem simplifica a adoção pelo utilizador do novo método. Para obter mais informações, veja Power Automate para programadores empresariais, ISVs e parceiros.

  • Atualizar a sua aplicação Teams: pode melhorar a sua aplicação teams atual. Por exemplo, pode permitir que os utilizadores configurem mensagens proativas com base em eventos de acionador no seu sistema. Para obter mais informações, veja como os bots podem publicar em canais através de mensagens proativas.

Problemas conhecidos

  • A aplicação de fluxos de trabalho não pode publicar em canais privados como um bot de fluxo. No entanto, pode publicar em nome de um utilizador.
  • Os fluxos de trabalho suportam apenas Cartões Ajustáveis. Não suporta a mensagem mais antiga card formato que os Conectores Office 365 utilizam. O suporte para a utilização de mensagens card formato em Fluxos de Trabalho fica disponível a partir de meados de outubro. Para obter mais informações, veja como converter mensagens de conector card formato em Cartão Ajustável.
  • Os fluxos de trabalho não oferecem conectores de terceiros, como o DataDog e o Jenkins.
  • Os fluxos de trabalho só podem ser criados no seu ambiente predefinido.

Limites

Os fluxos de trabalho estão ligados apenas a utilizadores específicos (referidos como proprietários do fluxo de trabalho) e não a uma equipa ou canal do Teams. Os fluxos de trabalho podem tornar-se fluxos órfãos na ausência de um proprietário se não forem atribuídos coproprietários. Para manter a continuidade no processo de negócio automatizado pelo fluxo, os administradores podem adicionar um ou mais coproprietários e conceder-lhes controlo total sobre o fluxo de trabalho. Também podem adicionar autenticação para ligações, se existirem, e ativar o fluxo se este tiver sido desativado. Para obter mais informações, veja Gerir fluxos órfãos.

Com as aplicações do Microsoft Teams, pode adicionar o conector existente para Grupos do Microsoft 365 ou criar um novo no Teams. Para saber mais, veja compilar seu próprio conector.

Veja o seguinte vídeo para saber como criar conectores para Grupos do Microsoft 365:


Observação

Este tópico reflete a versão 2.0.x da biblioteca de cliente JavaScript do Microsoft Teams (TeamsJS). Se estiver a utilizar uma versão anterior, consulte a descrição geral da biblioteca do TeamsJS para obter orientações sobre as diferenças entre as versões mais recentes do TeamsJS e 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. Também pode fornecer o pacote diretamente aos utilizadores para carregamento 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 submeter o conector no artigo Publicar a sua aplicação na Microsoft Teams Store . Caso contrário, um conector registado funciona em todos os produtos do Microsoft 365 que suportam aplicações, incluindo o Outlook e o 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. O seu código tem de incluir a biblioteca do TeamsJS. Isto dá ao seu código acesso às APIs para realizar operações comuns, tais como obter o contexto de utilizador, canal ou equipa, e iniciar fluxos de autenticação.

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

Observação

A partir da biblioteca do TeamsJS v.2.0.0, as APIs no espaço de nomes de definições foram preteridas a favor de APIs equivalentes no espaço de nomes de páginas , incluindo pages.getConfig() e outras APIs no pages.config sub-espaço de nomes. Para obter mais informações, consulte Novidades no TeamsJS versão 2.x.x.

  1. Inicialize o TeamsJS ao chamar 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. Registar microsoftTeams.pages.config.registerOnSaveHandler() processador de eventos, que é chamado quando o utilizador seleciona Guardar.

  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, o código tem de chamar microsoftTeams.authentication.registerAuthenticationHandlers() com o URL e os métodos de chamada de retorno com êxito ou falha antes de efetuar a chamada authenticate() devido a razões de compatibilidade entre clientes. A partir do TeamsJS v.2.0.0, registerAuthenticationHandlers foi preterido a favor de chamar diretamente authenticate() com os parâmetros de autenticação necessários.

getConfig propriedades de resposta

Observação

Os parâmetros devolvidos pela getConfig chamada são diferentes quando invoca este método a partir de um separador e diferem dos 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 O URL do webhook criado para o conector. Utilize o URL do webhook para POST estruturado JSON para enviar cartões para o canal. O webhookUrl é devolvido apenas quando a aplicação devolve dados com êxito.
appType Os valores devolvidos podem ser mail, groupsou teams correspondentes ao Correio, Grupos do Microsoft 365 ou Teams do Microsoft 365. respetivamente.
userObjectId O ID exclusivo correspondente ao utilizador do Microsoft 365 que iniciou a configuração do conector. Tem de estar protegido. Este valor pode ser utilizado para associar o utilizador no Microsoft 365, que configurou a configuração no 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 é carregado, o contentUrl código tem de chamar getConfig() para pré-preencher quaisquer definições ou formulários na interface de utilizador 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 da aplicação

Transfira o manifesto de aplicação gerado automaticamente (anteriormente denominado manifesto de aplicação do Teams) a partir do Portal do Programador. Execute as seguintes etapas antes de testar ou publicar o aplicativo:

  1. Incluir dois ícones.
  2. Modifique a icons parte no ficheiro de manifesto da aplicação para incluir os nomes de ficheiro dos ícones em vez de URLs.

O exemplo de manifest.json seguinte contém os elementos necessários para testar e submeter a aplicação:

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. Pode criar um pacote de .zip com o ficheiro de manifesto da aplicação a partir dos dois ficheiros de ícone e do Dashboard do Programador de Conectores, modificado conforme indicado em Incluir o conector no manifesto da aplicação.

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 ecrã de uma secção de carregamento na caixa de diálogo do conector.

Observação

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

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 no teams.

Distribuir webhook e conector

  1. Crie Webhooks recebidos diretamente para a sua equipa.

  2. Adicione uma página de configuração e publique o Webhook recebido num 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 DE 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 que suporte 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