Criar um conector personalizado do zero

Para criar um conector personalizado, você deve definir a API à qual deseja se conectar para que o conector compreenda as operações e as estruturas de dados da API. Neste artigo, cria-se um conector personalizado do zero, sem usar um formato de Definição OpenAPI para descrever a operação de análise de sentimentos da API de Análise de Texto dos Azure Cognitive Services (nosso exemplo para esta série). Em vez disso, você define o conector completamente 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.

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
  • Aplicações Power

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 para seu conector personalizado. Saiba como criar uma solução.

4. Selecione a lista suspensa Novo conector personalizado e selecione Criar em branco.

5. Insira o Nome do conector, como SentimentDemo. Selecione Continuar para abrir o assistente de configuração do conector onde o utilizador completa estas cinco secções no Power Automate.

   • General

   • Segurança

   • Definition

   • Código (opcional)

   • Test

     

Passo 1: Atualizar detalhes gerais

Você fornece informações do conector, como o ícone, a descrição, o esquema, o host e a URL base na seção Geral . Efetue estes passos:

1. Selecione Carregar ícone do conector ou Carregar na caixa de ícones para carregar um PNG ou JPG do ícone do conector. Certifique-se de que é inferior a 1MB. Você também pode designar uma cor de plano de fundo para seu ícone.

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

3. Selecione o esquema de URL do seu conector, HTTPs ou HTTP.

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

5. Atualize a URL base, o ponto de partida para todas as chamadas de API para um serviço específico.

6. Selecione Segurança na parte inferior para ir para a próxima seção.

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 seção Segurança , em Tipo de autenticação, selecione Chave de API na lista suspensa.

2. Em Chave de API, especifique um rótulo de parâmetro, nome e local. Especifique um rótulo significativo, porque ele é exibido quando alguém faz uma conexão pela primeira vez com o 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, certifique-se de que o nome está definido como SentimentDemoe, em seguida, selecione Criar conector.

4. Selecione Definição na parte inferior para ir para a próxima seção.

Passo 3: Criar a definição do conector

O assistente de conector personalizado oferece muitas opções para descrever como o conector funciona e como ele é exposto em aplicativos lógicos, fluxos, aplicativos e agentes. Você pode definir ações, gatilhos, referências e políticas. 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 Automatize e Copilot Studio), referências e políticas definidas para o conector.

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
   Description	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
   Valor predefinido	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
   Valor predefinido	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
   Valor predefinido	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.

8. Selecione Código na parte inferior para ir para a próxima seção.

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.

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.

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
• Aplicações Power
• Aplicativos lógicos
• Estúdio Copiloto

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.