Criar um conector personalizado do zero

  • Artigo

Este artigo faz parte de uma série de tutoriais sobre a criação e a utilização de conectores personalizados no Azure Logic Apps, Microsoft Power Automate e Microsoft Power Apps.

Nota

Certifique-se de que leu a descrição geral do conector personalizado para compreender o processo.

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 tópico, cria um conector personalizado do zero, sem utilizar uma definição OpenAPI para descrever a operação de sentimento da API de Análise de Texto dos Serviços Cognitivos do Azure (o nosso exemplo para esta série). Em vez disso, descreve completamente o conector no assistente de conector personalizado.

Para outra forma de descrever uma API, aceda a Criar um conector personalizado a partir de uma definição OpenAPI.

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

Iniciar o assistente de conector personalizado

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

  2. No painel esquerdo, selecionar Dados > Conectores personalizados.

  3. Selecione Novo conector personalizado > Criar a partir do zero.

  4. Introduza um nome para o conector personalizado e, em seguida, selecione Continuar.

    Parâmetro valor
    Título do conector personalizado SentimentDemo

Passo 1: Atualizar detalhes gerais

A partir deste ponto, vamos mostrar a IU do Power Automate, mas os passos são praticamente os mesmos em todas as tecnologias. Vamos mostrar as diferenças.

No separador Geral, pode efetuar o seguinte:

  1. No campo Descrição, introduza um valor significativo. Esta descrição aparecerá nos detalhes do conector personalizado e pode ajudar outros a decidir se o conector lhes pode ser útil.

  2. Atualize o campo Anfitrião 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. No separador Segurança, em Tipo de autenticação, selecione Chave de API.

  2. Em Chave de API, especifique uma etiqueta de parâmetro, um nome e uma localização. 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. Selecione Ligar.

    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, certifique-se de que o nome está definido como SentimentDemo e, em seguida, 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. Explicaremos a IU e abordaremos algumas opções nesta secção, mas também encorajamos que explore 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.

  1. No separador Definição, o painel esquerdo apresenta todas as ações, acionadores (para o Logic Apps e o Power Automate) e referências que estão definidos para o conector. Selecione Nova ação.

    Não existem acionadores neste conector. Para saber mais sobre acionadores para conectores personalizados aceda a Utilizar webhooks com o Azure Logic Apps e o Power Automate.

  2. A área Geral apresenta informações sobre a ação ou o acionador atualmente selecionado. Adicione um resumo, descrição e 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 Visibilidade definida como nenhuma. Esta propriedade para operações e parâmetros num fluxo ou aplicação lógica tem as seguintes opções:

    • nenhum: apresentado normalmente na aplicação lógica ou no fluxo
    • avançado: oculto sob outro menu
    • interna: ocultada do utilizador
    • importante: sempre mostrada primeiro ao utilizador

  3. A área de Pedido apresenta informações com base no pedido HTTP para a ação. Selecione Importar a partir do exemplo.

  4. Especifique as informações necessárias para ligar à API, especifique o corpo do pedido (fornecido após a imagem seguinte) e selecione Importar. Fornecemos estas informações para si, mas para uma API pública, normalmente obtém estas informações a partir da documentação, tal como 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 Utilizar o seguinte código JSON

    Exemplo:

    {
  "documents": [
    {
      "language": "string",
      "id": "string",
      "text": "string"
    }
  ]
}

  5. A área de Resposta apresenta informações com base na resposta HTTP para a ação. Selecione Adicionar resposta predefinida.

  6. Especifique o corpo da resposta e, em seguida, selecione importar. Tal como fizemos para o corpo do pedido, fornecemos-lhe estas informações após a imagem, mas normalmente são fornecidas na documentação da API.

    Exemplo:

    {
 "documents": [
   {
     "score": 0.0,
     "id": "string"
   }
 ],
 "errors": [
   {
     "id": "string",
     "message": "string"
   }
 ]
}

  7. A área Validação mostra todos os problemas detetados na definição da API. Verifique o estado e, em seguida, no canto superior direito do assistente, selecione Atualizar conector.

Atualizar a definição

Agora, vamos alterar algumas coisas, para que o conector seja mais amigável quando alguém o utilizar numa aplicação lógica, num fluxo ou numa aplicação.

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

  2. Na área Parâmetro, vê agora 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 do parâmetro e selecione Anterior.

    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 o idioma > Editar e, em seguida, repita o processo para o qual usou o id nos passos 2 e 3 deste procedimento, com os seguintes 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 o texto > Editar e, em seguida, repita o processo para o qual usou o id nos passos 2 e 3 deste procedimento, com os seguintes valores.

    Parâmetro valor
    Título Texto
    Descrição O texto para analisar quanto a sentimento
    Valor predefinido Nenhum
    É obrigatório Sim

  6. Na área Parâmetro, selecione Voltar para levá-lo de volta ao separador principal Definição.

  7. No canto superior direito do assistente, selecione Atualizar conector.

Passo 4: (opcional) Ative o seu conector como um plug-in de IA

Utilize o separador Plug-in de IA (pré-visualização) para um conector, apenas se planeia certificar o seu conector. Para que um conector seja utilizado como um plug-in de IA, o conector deve ser certificado.

Antes de ativar o conector como um plug-in de IA, certifique-se que compreende o caso de utilização dos cenários de plug-in de IA e de ter revisto outras considerações, como capacidade de suporte, melhores práticas e recomendações. Mais informações: Criar um plug-in de IA de conector (pré-visualização)

  1. No painel de navegação esquerdo, selecione Conectores personalizados.

    Se não aparecer Conectores personalizados, selecione Mais > Descobrir todos > Conectores personalizados. A opção aparece no painel de navegação esquerdo.

  2. No canto superior direito, selecione uma opção do menu Novo conector personalizado.

  3. Certifique-se de ter concluído o Passo 1, o Passo 2 e o Passo 3 neste artigo.

  4. Selecione o separador Plug-in de IA (pré-visualização).

  5. Na secção Manifesto do plug-in , introduza os detalhes para ativar este conector como um plug-in de IA.

    Captura de ecrã dos campos na página 'Manifesto do plug-in'.

    Campo Description
    Manifesto do Plug-in: nome Nome do plug-in de IA.
    Manifesto do Plugin: descrição Descrição do plug-in de IA. Mais informações: Criar um plug-in de IA de conector (pré-visualização)
    Manifesto do plug-in: e-mail de contacto Endereço de e-mail do contacto para este plug-in de IA.
    Manifesto do plug-in: URL de informações legais Uma localização acessível publicamente onde são publicadas as informações legais relacionadas com o seu plug-in de IA.

  6. Desloque para baixo até à secção Detalhes das Ações do Plug-in e introduza os detalhes de cada ação no plug-in de IA do conector.

    Captura de ecrã dos campos na página 'Detalhes da Ação do Plug-in'.

    Campo Description
    Detalhes da Ação do Plug-in: resumo Resumo sobre cada ação do plug-in de IA que os utilizadores podem realizar.
    Detalhes da Ação do Plug-in: descrição Descrição de cada ação que os utilizadores podem realizar em relação a este passo de ação específico do plug-in de IA.
    Caixa de verificação: ativas como operação do plug-in do copilot Quando uma marca de verificação estiver na caixa de verificação, a operação do plug-in de IA está ativa.
    Caixa de verificação: é necessária confirmação do utilizador? Quando uma marca de verificação estiver na caixa de verificação, é necessária a confirmação do utilizador.

    Gorjeta

    Se precisar de ajuda para definir as suas ações, ligue o botão Editor Swagger .

  7. Desloque para baixo até à secção Parâmetro e introduza os detalhes do parâmetro do plug-in de IA do conector.

    Captura de ecrã dos campos na página 'Parâmetros'.

    Campo Description
    Parâmetero: nome Nome do parâmetro. Utilize nomes identificáveis, como Identificador da Conta em vez de ID.
    Parâmetro: descrição Descrição do parâmetro. Utilize uma explicação descritiva, como Data de nascimento para um contacto no formato MM/DD/AAAA em vez de b_date. Estes nomes e descrições ajudam os LLM (grandes modelos de linguagem) a interagirem de forma eficaz com o plug-in de IA.
    Parâmetro: resumo Informações de resumo sobre o parâmetro.
    Parâmetro: valor predefinido Valor predefinido do parâmetro.

  8. na secção Pedido abaixo das secções Plug-in de IA (pré-visualização), selecione o parâmetro de entrada e introduza uma descrição.

Passo 5: (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 for utilizado, terá precedência sobre a definição sem código. Isto significa que o código será executado e não enviaremos o pedido para o back-end.

Nota

  • Este passo é opcional. Pode concluir a experiência sem código para criação do seu conector ignorando este passo e indo para o Passo 6: 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 do código escrito, aceda a Escrever código em conectores personalizados.

Para ver as perguntas mais frequentes sobre código personalizado, aceda às FAQ do código personalizado.

  1. No separador Código, introduza o seu código personalizado utilizando uma das seguintes opções:

    • Copiar/colar
    • Selecione o botão Carregar.

    Se optar por carregar o seu código personalizado, apenas estarão disponíveis ficheiros com uma extensão .cs ou .csx.

    Captura de ecrã de Carregar o seu código personalizado.

    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 seu código, selecione o seletor ao lado de Código Desativado para ativar o seu código. O nome do seletor altera-se para Código Ativado.

    Pode ativar ou desativar o seu código em qualquer altura. Se o seletor for Código Desativado, o seu código será eliminado.

  3. Selecione as ações e os acionadores a aplicar ao seu código personalizado ao selecionar uma opção no menu pendente. Se não for selecionada nenhuma operação, as ações e os acionadores são aplicados a todas as operações.

    Captura de ecrã de Selecionar ações e acionadores.

Passo 6: 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. No separador Teste, selcione Nova ligação.

  2. Introduza a chave da API de Análise de Texto e, em seguida, selecione Criar ligação.

    Nota

    Para as APIs que requerem a autenticação do portador, adicione Portador e um espaço antes da Chave de API.

  3. Regresse ao separador Testar e faça uma das seguintes ações:

    • (No Power Automate) É direcionado de volta para o separador Teste. Selecione o ícone de atualização para se certificar de que as informações da ligação estão atualizadas.

      Captura de ecrã da ligação Atualizar

    • (No Power Apps) É direcionado para a lista de ligações disponíveis no ambiente atual. No painel esquerdo, selecionar Dados > Conectores personalizados. Escolha o conector que criou e, em seguida, volte ao separador Teste.

  4. No separador Teste, introduza um valor para o campo texto (os outros campos utilizam as predefinições que definiu anteriormente) e, em seguida, escolha Testar operação.

  5. O conector chama a API e poderá rever a resposta, que inclui a classificação de sentimento.

    Captura de ecrã de resposta do conector.

(Para utilizadores de CLI) Melhores práticas

  • 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 já criou um conector personalizado e definiu os comportamentos do mesmo, pode utilizá-lo:

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 enviar comentários, aceda a Submeter problemas ou obter ajuda com conectores e selecione o tipo de comentários.