Criar um conector personalizado do zero

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:

  • Power Automate
  • Power Apps

Iniciar o assistente de conector personalizado

1. Iniciar sessão no Power Apps ou no Power Automate.

2. No painel esquerdo, selecione Soluções.

3. Edite ou crie uma solução não gerenciada que incluirá seu conector personalizado. Saiba como criar uma solução

4. Selecione a lista pendente Novo e selecione Conector personalizado> de automação.

   O assistente de novo conector é aberto

5. 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:

1. 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.

2. 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.

1. Na guia Segurança , em Tipo de autenticação, selecione Chave de API.

2. 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

3. 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.

1. Selecione Nova ação.

2. 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

3. Na área Solicitação , selecione Importar da amostra.

4. 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"
       }
     ]
   }
   

5. Na área Resposta , selecione Adicionar resposta padrão.

6. 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.

7. Corrija quaisquer problemas. Você verá uma marca de seleção verde quando a validação da definição for bem-sucedida.

8. 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.

1. Na área Pedido , selecione corpo e, em seguida, selecione Editar.

2. Na área Parâmetro , agora você vê os três parâmetros que a API espera: id, language, e text. Selecione id e, em seguida, selecione Editar.

3. 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

4. Na área Parâmetro , selecione Editar idioma>e repita o processo usado para id adicionar os seguintes language 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

5. Na área Parâmetro , selecione Editar texto>e repita o processo usado para id e language adicione os seguintes text valores:

   Parâmetro	valor
   Title	Texto
   Description	O texto para analisar quanto a sentimento
   Default value	None
   É obrigatório	Sim

6. Na área Parâmetro, selecione Voltar para retornar à guia Definição principal .

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

1. 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.

2. 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.

3. 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.

1. Na guia Teste , selecione Nova conexão.

2. 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.

3. 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 .

4. 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.

5. 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:

• Power Automate
• Power Apps
• Aplicativos lógicos
• Copilot Studio

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.

• Partilhe o seu conector
• Certificar o seu conector

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.