Criar conectores para Grupos do Microsoft 365
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:
O usuário seleciona o conector para iniciar o processo de configuração.
O usuário interage com a experiência da Web para concluir a configuração.
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.
Inicialize o TeamsJS chamando
app.initialize()
.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.Registre o
microsoftTeams.pages.config.registerOnSaveHandler()
manipulador de eventos, que é chamado quando o usuário seleciona Salvar.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.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.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 , groups ou 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:
- Incluir dois ícones.
- 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.
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
Crie Webhooks de entrada diretamente para sua equipe.
Adicione uma página de configuração e publique seu Webhook de entrada em um conector para Grupos do Microsoft 365.
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
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de