Criar um conector personalizado do zero

Para criar um conector personalizado, você deve definir a API à qual deseja se conectar para que o conector entenda as operações e as estruturas de dados da API. Neste artigo, você criará um conector personalizado desde o início, sem usar um formato de definição OpenAPI para descrever a operação de análise de sentimento da API de Análise de Texto dos Serviços Cognitivos do Azure (nosso exemplo para esta série). Em vez disso, você define o conector completamente no assistente de conector personalizado.

Para ver outra maneira de descrever uma API, acesse Criar um conector personalizado a partir de uma definição de OpenAPI.

Pré-requisitos

• Uma chave de API para a API de Análise de Texto dos Serviços Cognitivos

  Observação

  A API Análise de Texto dos Serviços Cognitivos Azure é usada como a API de exemplo nesta série de tutoriais. Se você tiver problemas para obter a chave de API, ainda poderá seguir as etapas neste artigo usando qualquer API REST à qual tenha acesso. O assistente de conector personalizado aceita qualquer chave de API válida esperada pela API de destino.

• Uma das seguintes assinaturas:

  • Power Automate
  • Power Apps

Iniciar o assistente de conector personalizado

1. Entre no Power Apps ou Power Automate.

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

3. Edite ou crie uma solução não gerenciada para o 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 você conclui estas cinco seções no Power Automate:

   • Geral

   • Segurança

   • Definition

   • Código (opcional)

   • Test

     

Etapa 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 . Execute estas etapas:

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 seja menor que 1 MB. Você também pode designar uma cor de tela de fundo para o ícone.

2. No campo Descrição, insira um valor significativo. Essa descrição aparece nos detalhes do conector personalizado e poderá ajudar outras pessoas a decidir se o conector pode ser útil para elas.

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

4. Atualize o campo Host para o endereço da API de análise de texto. O conector usa o host da API e a URL base para determinar como chamar a API.

   Parâmetro	Valor
   Descrição	Usa a API de Sentimento da Análise de Texto dos Serviços Cognitivos para determinar se o texto é positivo ou negativo
   Anfitrião	westus.api.cognitive.microsoft.com

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

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

Etapa 2: especificar o tipo de autenticação

Há várias opções disponíveis para a autenticação nos conectores personalizados. As APIs de Serviços Cognitivos usam autenticação por chave de API, portanto esse é o método que você deve especificar 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, um nome e um local. Especifique um rótulo significativo, pois isso é exibido quando alguém faz uma conexão pela primeira vez com o conector personalizado. O nome e o local do parâmetro devem corresponder ao que a API espera.

   Parâmetro	Valor
   Rótulo de 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 SentimentDemoe selecione Criar conector.

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

Etapa 3: criar a definição do conector

O assistente de conector personalizado oferece várias 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. Explicaremos a interface do usuário e abordaremos algumas opções nesta seçã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 invoque a operação de análise 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), referências e políticas definidas para o conector.

1. Selecione Nova ação.

2. Na área Geral, adicione um resumo, descrição e ID da operação para esta ação.

   Parâmetro	Valor
   Resumo	Retorna uma pontuação numérica representando o sentimento detectado
   Descrição	A API retorna uma pontuação numérica entre 0 e 1. Pontuações próximas de 1 indicam sentimento positivo, enquanto pontuações próximas de 0 indicam sentimento negativo.
   ID da Operação	DetectSentiment

   Deixe a propriedade Visibilidade definida como nenhum. Essa propriedade para operações e parâmetros em um aplicativo lógico ou fluxo possui as seguintes opções:

   • nenhum: normalmente exibido no aplicativo lógico ou no fluxo
   • avançado: ocultado em outro menu
   • interno: ocultado do usuário
   • importante: sempre exibido para o usuário 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.

   Normalmente, você obtém essas informações da documentação da API para uma API pública.

   Parâmetro	Valor
   Verbo	POSTAR
   URL	https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment
   Corpo	Use o JSON de exemplo.

   Exemplo:

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

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

6. Especifique o corpo da resposta e, depois, selecione Importar. Assim como fizemos para o corpo da solicitação, fornecemos essas informações para você, mas elas 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 problemas detectados na definição da API.

7. Corrija quaisquer problemas. Você deverá ver uma marca de verificação verde quando a validação da definição for concluída com êxito.

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

Atualizar a definição

Vamos alterar algumas coisas para que o conector fique mais fácil de usar para quem o utiliza no Logic Apps, Power Automate, Power Apps ou Copilot Studio.

1. Na área Solicitação, selecione corpo e, depois,, Editar.

2. Na área Parâmetro, você vê os três parâmetros esperados pela API: id, language e text. Selecione id e, depois, Editar.

3. Na área Propriedade do Esquema, atualize os valores do parâmetro e selecione Voltar.

   Parâmetro	Valor
   Título	ID
   Descrição	Um identificador para cada documento que você enviar
   Valor padrão	1
   É obrigatório	Sim

4. Na área Parâmetro, selecione idioma>Editar e, em seguida, repita o processo que você usou para id para adicionar os seguintes valores de language:

   Parâmetro	Valor
   Título	Linguagem
   Descrição	O código de idioma de dois ou quatro caracteres para o texto
   Valor padrão	en
   É obrigatório	Sim

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

   Parâmetro	Valor
   Título	Texto
   Descrição	O texto a ser analisado quanto ao sentimento
   Valor padrão	Nenhum
   É obrigatório	Sim

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

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.

Etapa 4: (opcional) Usar suporte ao código personalizado

O código personalizado transforma cargas de solicitação e resposta além do escopo dos modelos de política existentes. As transformações incluem o envio de solicitações externas para buscar dados adicionais. Quando o código é usado, ele tem precedência sobre a definição sem código. Isso significa que o código será executado e não enviaremos a solicitação ao back-end.

Você pode colar seu código ou carregar um arquivo com seu código. Seu código deve:

• Ser escrito em C#.
• Ter um tempo máximo de execução de cinco segundos.
• Ter um tamanho de arquivo de até 1 MB.

Para obter instruções e exemplos de como escrever código, acesse Escrever código em conectores personalizados.

Para perguntas frequentes sobre código personalizado, acesse 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, apenas os arquivos com extensão .cs ou .csx estarão disponíveis.

   

   Importante

   No momento, só oferecemos suporte ao realce de sintaxe no editor de código. Teste seu código localmente.

2. Depois de colar ou carregar seu código, selecione a alternância ao lado de Código Desabilitado para habilitar seu código. O nome do botão de alternância muda para Código ativado.

   Você pode habilitar ou desabilitar seu código a qualquer momento. Se o botão estiver em Código desativado, seu código é excluído.

3. Selecione as ações e os gatilhos a serem aplicados ao código personalizado selecionando uma opção no menu suspenso. Se nenhuma operação for selecionada, as ações e os gatilhos serão aplicados a todas operações.

   

Etapa 5: testar o conector

Após criar o conector, teste-o para verificar se ele está funcionando corretamente. Atualmente, os testes estão disponíveis somente no Power Automate e no Power Apps.

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

2. Insira a chave de API de Análise de Texto e, depois, selecione Criar conexão.

   Observação

   Para APIs que exigem autenticação do portador, adicione Portador e um espaço antes da chave de API.

3. Retorne para a guia Teste e siga um destes procedimentos:

   • (No Power Automate) você é redirecionado para a guia Teste. Selecione o ícone de atualização para garantir que as informações de conexão estejam atualizadas.

     

   • (No Power Apps) você será direcionado para a lista de conexões disponíveis no ambiente atual. No painel esquerdo, selecione Conectores personalizados. Escolha o conector criado e retorne à guia Teste.

4. Na guia Teste, insira um valor no campo texto (outros campos usam os padrões que você definiu anteriormente) e, depois, selecione Testar operação.

   O conector chama a API.

5. Analise a resposta, que inclui o índice de sentimento.

   

Melhores práticas para usuários CLI

• Baixe todos os seus conectores personalizados e use o Git ou outro sistema de gerenciamento de código-fonte para salvar os arquivos.

• Se houver uma atualização incorreta, reimplante o conector ao executar outra vez o comando de atualização com o conjunto correto de arquivos do sistema de gerenciamento de código-fonte.

• Teste o conector personalizado e o arquivo de configurações em um ambiente de teste antes de implantá-lo no ambiente de produção.

• Sempre verifique novamente se o ambiente e a ID do conector estão corretos.

Solucionar problemas comuns

• As ações do conector personalizado não estão sendo carregadas: Depois de criar ou atualizar um conector, aguarde alguns minutos para que a plataforma propague as alterações antes de testar. Limpe o cache do navegador ou tente uma sessão de navegação privada se as ações ainda não aparecerem.

• 401 Erros não autorizados: verifique se a chave de API ou as credenciais OAuth estão corretas e não expiraram. Para conectores OAuth, confirme se o URI de redirecionamento em seu provedor de identidade corresponde ao URI de redirecionamento por conector mostrado na guia Segurança .

• 403 Erros proibidos: verifique se o ponto de extremidade da API permite conexões de intervalos de IP do Power Platform. No caso do Azure Functions em uma rede virtual, revise os endereços IP de saída dos conectores gerenciados e garanta que as regras de rede permitam tráfego proveniente desses intervalos de IP.

• Conector não visível após o compartilhamento: pode levar alguns minutos para que um conector compartilhado apareça para outros usuários. Se você adicionou o conector a uma solução, os usuários precisarão de acesso a essa solução para ver o conector.

Próximas etapas

Agora que você criou um conector personalizado e definiu os comportamentos, poderá usar o conector de:

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

Também é possível compartilhar o conector em sua organização ou obter o conector certificado para que as pessoas fora de sua organização possam usá-lo.

• Compartilhar seu conector
• Certificar seu conector

Faça comentários

Agradecemos muito os comentários sobre problemas com nossa plataforma de conectores ou novas ideias de recursos. Para fornecer comentários, acesseEnviar problemas ou obter ajuda com conectores e selecione o tipo de comentário.