Compartilhar via

Criar um conector personalizado do zero

  • Artigo

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

Observação

Certifique-se de ler a visão geral do conector personalizado para entender o processo.

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 tópico, você cria um conector personalizado do zero, sem usar uma definição de OpenAPI 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, 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 Dados > Conectores personalizados.

  3. Selecione Novo conector personalizado > Criar do zero.

  4. Insira um nome para o conector personalizado e, depois, selecione Continuar.

    Parâmetro Valor
    Título do conector personalizado SentimentDemo

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. Apontaremos as diferenças.

Na guia Geral, você pode fazer o seguinte:

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

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

    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.

  1. Na guia Definição, o painel esquerdo exibe as ações, os gatilhos (para os Aplicativos Lógicos e o Power Automate) e as referências definidas para o conector. Selecione Nova ação.

    Não há gatilho neste conector. Para saber mais sobre gatilhos para conectores personalizados, consulte Usar webhooks com os Aplicativos Lógicos do Azure e o Power Automate.

  2. A área Geral exibe informações sobre a ação ou o gatilho selecionado no momento. 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: escondido em outro menu
    • interno: ocultado do usuário
    • importante: sempre exibido para o usuário primeiro

  3. A área Solicitação exibe informações com base na solicitação HTTP para a açã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 imagem a seguir) 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 Use o código JSON a seguir

    Exemplo:

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

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

  6. Especifique o corpo da resposta e, depois, selecione Importar. Como fizemos para o corpo da solicitação, fornecemos essas informações para você, depois da imagem, mas elas costumam ser fornecidas na documentação da API.

    Exemplo:

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

  7. A área Validação exibe problemas detectados na definição da API. Verifique o status e, 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 usar em um aplicativo lógico, fluxo ou aplicativo.

  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 repita o processo que você usou para id nas etapas 2 e 3 deste procedimento com os seguintes valores.

    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 repita o processo que você usou para id nas etapas 2 e 3 deste procedimento com os seguintes valores.

    Parâmetro Valor
    Título Texto
    Descrição O texto no qual analisar o sentimento
    Valor padrão Nenhum
    É obrigatório Sim

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

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

Etapa 4: (Opcional) habilitar o conector como um plugin de IA

Só use a guia Plugin de IA (versão preliminar) para um conector se você estiver se planejando para certificar o conector. Para um conector ser usado como plugin de IA, o conector deve ser certificado.

Para habilitar o conector como um plugin de IA, certifique-se de que compreenda o caso de uso dos cenários de plugin de IA e de ter examinado outras considerações, como capacidade de suporte, melhores práticas e recomendações. Mais informações: Criar um plugin de IA do conector (versão preliminar)

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

    Se você não vir Conectores personalizados, selecione Mais > Descobrir tudo > Conectores personalizados. A opção é exibida no painel de navegação no lado esquerdo.

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

  3. Certifique-se de ter concluído Etapa 1, Etapa 2 e Etapa 3 deste artigo.

  4. Selecione a guia Plugin de IA (versão preliminar).

  5. Na seção Manifesto de plugin, insira detalhes para habilitar esse conector como um plugin de IA.

    Captura de tela dos campos na página Manifesto do plugin.

    Campo Description
    Manifesto do plugin: nome Nome do plugin de IA.
    Manifesto do Plugin: Descrição Descrição do plugin de IA. Mais informações: Criar um plugin de IA do conector (versão preliminar)
    Manifesto do Plugin: Email do contato Endereço de email do contato para esse plugin de IA.
    Manifesto do plugin: URL de informações legais Um local acessível publicamente onde as informações legais relacionadas ao plugin de IA são publicadas.

  6. Role a tela para baixo até a seção Detalhes das Ações de Plugin e insira os detalhes de cada ação no plugin de IA do conector.

    Captura de tela dos campos na página Detalhes da Ação do Plugin.

    Campo Description
    Detalhes da ação do plugin: resumo Resumo sobre cada ação do plugin de IA que os usuários podem realizar.
    Detalhes da ação do plugin: descrição Descrição de cada ação que os usuários podem realizar em relação a essa etapa de ação específica do plugin de IA.
    Caixa de seleção: Habilitar operação de plugin do Copilot Quando há uma marca na caixa de seleção, a operação do plugin de IA está habilitada.
    Caixa de seleção: A confirmação do usuário é necessária? Quando uma marca está na caixa de seleção, a confirmação do usuário é necessária.

    Dica

    Se você precisar de ajuda para definir as ações, ative o botão Editor Swagger.

  7. Role a tela para baixo até a seção Parâmetro e insira os detalhes do parâmetro do plug-in de IA do conector.

    Captura de tela dos campos na página Parâmetros.

    Campo Description
    Parâmetro: nome Nome do parâmetro. Use nomes identificáveis, como Identificador da Conta, em vez de ID.
    Parâmetro: descrição Descrição do parâmetro. Use uma explicação descritiva, como Data de nascimento de um contato em formato MM/DD/AAAA, em vez de b_data. Esses nomes e descrições ajudam LLMs (modelos de linguagem grandes) a interagir de maneira eficaz com o plugin de IA.
    Parâmetro: resumo Informações de resumo sobre o parâmetro.
    Parâmetro: valor padrão O valor padrão do parâmetro.

  8. Na seção Solicitação abaixo das seções Plugin de IA (versão preliminar), selecione o parâmetro de entrada e insira uma descrição.

Etapa 5: (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 for usado, ele terá 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 6: 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 6: 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 Dados > 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.

  5. O conector chamará a API e você poderá analisar a resposta, que inclui a pontuação de sentimento.

    Captura de tela da resposta do conector.

(Para usuários da CLI) Práticas recomendadas

  • 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 criou um conector personalizado e definiu seus comportamentos, você poderá usá-lo 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.

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