Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Nota
Este artigo faz parte de uma série de tutoriais sobre como criar e usar conectores personalizados em Aplicativos Lógicos do Azure e Microsoft Power Automate usar conectores e ações do Copilot. Microsoft Power Apps Microsoft Copilot Studio Certifique-se de ler a visão geral do conector personalizado para entender o processo.
Vá para Usar Power Platform conectores em Copilot Studio para saber como você pode chamar os conectores como ações de conector em seu Microsoft Copilot agente.
Para criar um conector personalizado, tem de descrever a API à qual se pretende ligar, para que o conector compreenda as operações e as estruturas de dados da API. Neste artigo, você cria um conector personalizado do zero, sem usar uma OpenAPI definição para descrever a operação de sentimento da API de Análise de Texto dos Serviços Cognitivos do Azure (nosso exemplo para esta série). Em vez disso, descreve completamente o conector no assistente de conector personalizado.
Para outra maneira de descrever uma API, vá para Criar um conector personalizado a partir de uma OpenAPI definição.
Nota
Atualmente, pode criar um conector personalizado a partir do zero no Power Automate e no Power Apps. Para Logic Apps, tem de começar com, pelo menos, uma definição OpenAPI básica.
Pré-requisitos
Uma chave de API para a API de Análise de Texto dos Serviços Cognitivos
Uma das seguintes subscrições:
Iniciar o assistente de conector personalizado
Iniciar sessão no Power Apps ou no Power Automate.
No painel esquerdo, selecione Soluções.
Edite ou crie uma solução não gerenciada que incluirá seu conector personalizado. Saiba como criar uma solução
Selecione a lista pendente Novo e selecione Conector personalizado> de automação.
O assistente de novo conector é aberto
Digite o Nome doconector, como
SentimentDemo
.Conclua o restante das etapas usando as instruções a seguir.
Passo 1: Atualizar detalhes gerais
A partir deste ponto, mostramos a interface do Power Automate utilizador, mas as etapas são basicamente as mesmas em todas as tecnologias. Apontamos quaisquer diferenças.
No separador Geral, pode efetuar o seguinte:
No campo Descrição , insira um valor significativo. Essa descrição aparece nos detalhes do conector personalizado e pode ajudar outras pessoas a decidir se o conector pode ser útil para elas.
Atualize o campo Host para o endereço da API de Análise de Texto. O conector utiliza o anfitrião da API e o URL de base para determinar como chamar a API.
Parâmetro valor Description Utiliza a API de Sentimento de Análise de Texto dos Serviços Cognitivos para determinar se o texto é positivo ou negativo Host westus.api.cognitive.microsoft.com
Passo 2: Especificar o tipo de autenticação
Existem várias opções disponíveis para a autenticação nos conectores personalizados. As APIs de Serviços Cognitivos utilizam a autenticação de chave de API, por isso, esta é a sua especificação para este tutorial.
Na guia Segurança , em Tipo de autenticação, selecione Chave de API.
Em Chave de API, especifique um rótulo de parâmetro, nome e local. Indique uma etiqueta significativa, porque esta é apresentada na primeira vez que alguém faz uma ligação ao conector personalizado. O nome do parâmetro e a localização devem corresponder ao que a API espera.
Parâmetro valor Etiqueta do parâmetro Chave de API Nome do parâmetro Ocp-Apim-Subscription-Key Localização do parâmetro Cabeçalho Na parte superior do assistente, verifique se o nome está definido como SentimentDemo e selecione Criar conector.
Passo 3: Criar a definição do conector
O assistente do conector personalizado irá dar-lhe muitas opções para definir como o seu conector funciona e como é exposto em Logic Apps, fluxos e aplicações. Explicamos a interface do utilizador e abordamos algumas opções nesta secção, mas também incentivamos você a explorar por conta própria.
Criar uma ação
A primeira coisa a fazer é criar uma ação que chame a operação de sentimento da API de Análise de Texto. Na guia Definição , o painel esquerdo exibe todas as ações, gatilhos (para Aplicativos Lógicos Power Automate e Copilot Studio) e referências definidas para o conector.
Nota
Não existem acionadores neste conector. Para saber mais sobre gatilhos para conectores personalizados, vá para Usar um webhook como um gatilho para Aplicativos Lógicos do Azure e Power Automate.
Selecione Nova ação.
Na área Geral , adicione um resumo, uma descrição e um ID de operação para esta ação.
Parâmetro valor Resumo Devolve uma pontuação numérica que representa o sentimento detetado Descrição A API devolve uma pontuação numérica entre 0 e 1. As pontuações próximas de 1 indicam um sentimento positivo, enquanto as pontuações próximas de 0 indicam um sentimento negativo. ID da operação DetectSentiment Deixe a propriedade Visibility definida como nenhuma. Esta propriedade para operações e parâmetros num fluxo ou aplicação lógica tem as seguintes opções:
- none: exibido normalmente no aplicativo lógico ou fluxo
- avançado: Oculto sob outro menu
- interno: oculto do utilizador
- importante: Sempre mostrado ao utilizador primeiro
Na área Solicitação , selecione Importar da amostra.
Especifique as informações necessárias para se conectar à API, especifique o corpo da solicitação (fornecido após a tabela) e selecione Importar.
Nós fornecemos essas informações para você, mas para uma API pública, você normalmente obtém essas informações da documentação, como a API de Análise de Texto (v2.0).
Parâmetro valor Verbo POST URL https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment
Body Use o exemplo JSON. Exemplo:
{ "documents": [ { "language": "string", "id": "string", "text": "string" } ] }
Na área Resposta , selecione Adicionar resposta padrão.
Especifique o corpo da resposta e selecione Importar. Como fizemos para o corpo da solicitação, fornecemos essas informações para você, mas normalmente são fornecidas na documentação da API.
Exemplo:
{ "documents": [ { "score": 0.0, "id": "string" } ], "errors": [ { "id": "string", "message": "string" } ] }
A área Validação exibe todos os problemas detetados na definição da API.
Corrija quaisquer problemas. Você verá uma marca de seleção verde quando a validação da definição for bem-sucedida.
No canto superior direito do assistente, selecione Atualizar conector.
Atualizar a definição
Vamos mudar algumas coisas para que o conector seja mais amigável quando alguém o usa em Aplicativos Lógicos, Power Automate, Power Apps ou Copilot Studio.
Na área Pedido , selecione corpo e, em seguida, selecione Editar.
Na área Parâmetro , agora você vê os três parâmetros que a API espera:
id
,language
, etext
. Selecione id e, em seguida, selecione Editar.Na área Propriedade do esquema, atualize os valores para o parâmetro e selecione Voltar .
Parâmetro valor Title ID Description Um identificador para cada documento que submeter Default value 5 É obrigatório Sim Na área Parâmetro , selecione Editar idioma>e repita o processo usado para
id
adicionar os seguinteslanguage
valores:Parâmetro valor Title Linguagem Description O código de idioma de dois ou quatro carateres para o texto Default value en É obrigatório Sim Na área Parâmetro , selecione Editar texto>e repita o processo usado para
id
elanguage
adicione os seguintestext
valores:Parâmetro valor Title Texto Description O texto para analisar quanto a sentimento Default value None É obrigatório Sim Na área Parâmetro, selecione Voltar para retornar à guia Definição principal .
No canto superior direito do assistente, selecione Atualizar conector.
Passo 4: (Opcional) Utilizar suporte de código personalizado
O código personalizado transforma os payloads de pedido e resposta para além do âmbito dos modelos de política existentes. As transformações incluem o envio de pedidos externos para obter dados adicionais. Quando o código é utilizado, tem precedência sobre a definição sem código. Isso significa que o código será executado e não enviamos a solicitação para o back-end.
Nota
Este passo é opcional. Você pode concluir a experiência sem código para criar seu conector ignorando esta etapa e indo para a Etapa 5: Testar o conector.
O suporte de código personalizado está disponível na pré-visualização pública.
Pode colar o seu código ou carregar um ficheiro com o mesmo. O seu código tem de:
- Estar escrito em C#.
- Ter um tempo de execução máximo de cinco segundos.
- Ter um tamanho de ficheiro inferior a 1 MB.
Para obter instruções e exemplos de como escrever código, vá para Escrever código em conectores personalizados.
Para perguntas frequentes sobre código personalizado, vá para Perguntas frequentes sobre código personalizado.
Na guia Código , insira seu código personalizado usando uma das seguintes opções:
- Copiar/colar
- Selecione o botão Carregar.
Se você optar por carregar seu código personalizado, somente arquivos com uma extensão .cs ou .csx estarão disponíveis.
Importante
Atualmente, apenas apoiamos o realce da sintaxe no editor de código. Certifique-se de que testa o seu código localmente.
Depois de colar ou carregar o código, selecione a alternância ao lado de Código desativado para ativar o código. O nome de alternância muda para Código habilitado.
Pode ativar ou desativar o seu código em qualquer altura. Se a alternância for Código desativado, seu código será excluído.
Selecione as ações e os acionadores a aplicar ao seu código personalizado ao selecionar uma opção no menu pendente. Se nenhuma operação for selecionada, as ações e gatilhos serão aplicados a todas as operações.
Passo 5: Testar o conector
Agora que criou o conector, teste-o para se certificar de que está a funcionar corretamente. Os testes estão atualmente disponíveis apenas no Power Automate e no Power Apps.
Importante
Quando utiliza uma chave de API, recomendamos não testar o conector imediatamente depois de o criar. Pode demorar alguns minutos até o conector estar pronto para ligar à API.
Na guia Teste , selecione Nova conexão.
Insira a chave da API da API de Análise de Texto e selecione Criar conexão.
Nota
Para APIs que exigem autenticação ao portador, adicione Portador e um espaço antes da chave da API.
Retorne à guia Teste e siga um destes procedimentos:
(Em Power Automate) Você será levado de volta para a guia Teste . Selecione o ícone de atualização para garantir que as informações de conexão estejam atualizadas.
- (No Power Apps) É direcionado para a lista de ligações disponíveis no ambiente atual. No painel esquerdo, selecione Conectores personalizados. Escolha o conector que você criou e volte para a guia Teste .
Na guia Teste , insira um valor para o campo de texto (os outros campos usam os padrões definidos anteriormente) e selecione Operação de teste.
O conector chama a API.
Analise a resposta, que inclui a pontuação de sentimento.
Práticas recomendadas para usuários da CLI
Transfira todos os seus conectores e utilize o Git ou qualquer sistema de gestão de códigos de origem para guardar os ficheiros.
Se uma atualizações estiver incorreta, volte a implementar o conector executando novamente o comando de atualização com o conjunto de ficheiros certos a partir do sistema de gestão de códigos de origem.
Antes de implementar no ambiente de produção, teste o conector personalizado e o ficheiro de definições num ambiente de teste.
Verifique sempre se o ID do ambiente e do conector estão corretos.
Próximos passos
Agora que você criou um conector personalizado e definiu seus comportamentos, você pode usar o conector de:
Também pode partilhar um conector dentro da sua organização ou obter o conector certificado, para que possam ser utilizados por pessoas externas à sua organização.
Enviar comentários
Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para fornecer comentários, vá para Enviar problemas ou obter ajuda com conectores e selecione seu tipo de feedback.