Compartilhar via

Criar um conector personalizado do zero

Observação

Este artigo faz parte de uma série de tutoriais sobre a criação e o uso de conectores personalizados nos Aplicativos Lógicos do Azure, no Microsoft Power Automate e no Microsoft Power Apps e usando conectores e ações do Copilot no Microsoft Copilot Studio. Certifique-se de ler a visão geral do conector personalizado para entender o processo.

Vá para Usar conectores do Power Platform no Copilot Studio para saber como você pode chamar os conectores como ações de conector em seu agente do Microsoft Copilot.

Para criar um conector personalizado, você deve descrever a API à qual deseja se conectar para que o conector entenda as estruturas de dados e as operações da API. Neste artigo, você criar um conector personalizado do zero, sem usar uma definição de OpenAPI para descrever a operação de sentimento de API da Análise de Texto dos Serviços Cognitivos do Azure (nosso exemplo para esta série). Em vez disso, você descreve totalmente o conector 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.

Observação

No momento, você poderá criar um conector personalizado desde o início no Power Automate e no Power Apps. Para Aplicativos Lógicos, você deve começar com pelo menos uma definição básica de OpenAPI.

Pré-requisitos

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

  4. Selecione Novo na lista suspensa e escolha Automação>Conector personalizado.

    O assistente de novo conector é aberto

  5. Digite o Nome do Conector, como SentimentDemo.

    Conclua o restante das etapas usando as instruções a seguir.

Etapa 1: Atualizar detalhes gerais

A partir desse ponto, será exibida a interface do usuário do Power Automate, mas as etapas são basicamente as mesmas em todas as tecnologias. Apontamos as diferenças.

Na guia Geral, você pode fazer o seguinte:

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

  2. 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
    Host westus.api.cognitive.microsoft.com

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 de chave de API, o que é especificado para este tutorial.

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

  2. Na Chave de API, especifique um rótulo de parâmetro, o nome e o local. Especifique um rótulo significativo, pois ele é exibido quando alguém faz uma conexão com o conector personalizado pela primeira vez. 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
    Local de parâmetro Cabeçalho

  3. Na parte superior do assistente, verifique se o nome está definido como SentimentDemo e, depois, selecione Criar conector.

Etapa 3: criar a definição do conector

O assistente de conector personalizado oferece várias opções para definir como o conector funciona e como ele é exposto em aplicativos lógicos, fluxos e aplicativos. 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 chama a operação de sentimento da API de Análise de Texto. Na guia Definição, o painel esquerdo exibe as ações, os gatilhos (para Aplicativos Lógicos, Power Automate e Copilot Studio) e referências que estão definidas para o conector.

Observação

Não há gatilho neste conector. Saiba mais sobre gatilhos para conectores personalizados, acesse Use um webhook como gatilho para os Aplicativos Lógicos do Azure e o Power Automate.

  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.

    Fornecemos essas informações, mas para uma API pública, você normalmente obtém essas informações de documentação como API de Análise de Texto (v2.0).

    Parâmetro Valor
    Verbo POSTAR
    URL https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment
    Body Usar 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ê 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

Agora vamos alterar algumas coisas para que o conector fique mais amigável quando alguém o usa em um Aplicativo Lógico, 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
    Description 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
    Description O texto no qual analisar o 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.

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.

Observação

  • Esta etapa é 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 ao código personalizado está disponível em versão preliminar pública.

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.

    Captura de tela de Carregar seu código personalizado.

    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 da alternância muda para Código Habilitado.

    Você pode habilitar ou desabilitar seu código a qualquer momento. Se a alternância for Código Desabilitado, seu código será 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.

    Captura de tela de Selecionar ações e gatilhos.

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.

Importante

Ao usar uma chave de API, recomendamos não testar o conector logo após a criação. Pode levar alguns minutos até que o conector esteja pronto para se conectar à API.

  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.

      Captura de tela da conexão de atualização

    • (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. Revise a resposta, que inclui a pontuação de sentimento.

    Captura de tela da resposta do conector.

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.

Próximas etapas

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

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.

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.