Criar um conector personalizado com a CLI

A paconn ferramenta de linha de comando é projetada para ajudar na criação de conectores personalizados para Copilot Studio e Power Platform.

Nota

Esta funcionalidade pode ainda não ter sido lançada.
Para obter informações sobre a versão, vá para Novidades e planos para Common Data Model e Data Integration.
Os prazos de entrega e a funcionalidade projetada podem ser alterados ou podem não ser enviados (vá para a política da Microsoft).

Instalar

Instale o Python 3.5+ a partir de [https://www.python.org/downloads](Python downloads). Selecione o link Download em qualquer versão do Python maior que o Python 3.5. Para Linux e macOS X, siga a ligação relevante na página. Também pode utilizar um gestor de pacotes de SO específico à sua escolha para instalar.
Execute o instalador para iniciar a instalação e certifique-se de marcar a caixa Adicionar Python X.X ao PATH.
Verifique se o caminho de instalação está na variável PATH executando:

python --version
Depois que o python for instalado, instale paconn executando:

pip install paconn

Se você receber erros dizendo que o acesso foi negado, considere usar a --user opção ou executar o comando como administrador (Windows).

Diretório e ficheiros do conector personalizado

Um conector personalizado consiste em dois a quatro arquivos:

Uma definição de API aberta/swagger
Um arquivo de propriedades da API
Um ícone opcional para o conector
Arquivo de script csharp opcional

Os arquivos estão localizados em um diretório com o ID do conector como o nome do diretório.

Às vezes, o diretório do conector personalizado inclui um settings.json arquivo. Embora esse arquivo não faça parte da definição do conector, você pode usá-lo como um armazenamento de argumentos para a CLI.

Ficheiro de definição (swagger) da API

O arquivo de definição de API descreve a API para o conector personalizado usando a OpenAPI especificação, também conhecida como arquivo swagger. Para obter mais informações sobre como um arquivo de definição de API ajuda a criar um conector personalizado, vá para Criar um conector personalizado a partir de uma OpenAPI definição. Analise também o tutorial no artigo Estender uma OpenAPI definição para um conector personalizado.

Ficheiro de propriedades da API

O arquivo de propriedades da API contém algumas propriedades para o conector personalizado que não fazem parte da definição da API. O arquivo de propriedades da API contém informações como a cor da marca, informações de autenticação e assim por diante. Regra geral, os ficheiros de propriedades de APIs assemelham-se ao seguinte exemplo:

{
  "properties": {
    "capabilities": [],
    "connectionParameters": {
      "api_key": {
        "type": "securestring",
        "uiDefinition": {
          "constraints": {
            "clearText": false,
            "required": "true",
            "tabIndex": 2
          },
          "description": "The KEY for this API",
          "displayName": "KEY",
          "tooltip": "Provide your KEY"
        }
      }
    },
    "iconBrandColor": "#007EE6",
    "scriptOperations": [
        "getCall",
        "postCall",
        "putCall"
    ],
    "policyTemplateInstances": [
      {
        "title": "MyPolicy",
        "templateId": "setqueryparameter",
        "parameters": {
            "x-ms-apimTemplateParameter.name": "queryParameterName",
            "x-ms-apimTemplateParameter.value": "queryParameterValue",
            "x-ms-apimTemplateParameter.existsAction": "override"
        }
      }
    ]    
  }
}

Aqui estão mais informações sobre cada uma das propriedades:

properties: O recipiente para a informação.
connectionParameters: Define o parâmetro de conexão para o serviço.
iconBrandColor: A cor da marca do ícone no código hexadecimal HTML para o conector personalizado.
scriptOperations: Uma lista das operações que são executadas com o arquivo de script. Um lista scriptOperations vazia indica que todas as operações são executadas com o ficheiro de script.
capabilities: Descrição das capacidades do conector. Por exemplo, gateway somente na nuvem e no local.
policyTemplateInstances: Uma lista opcional de instâncias e valores de modelo de política que o conector personalizado usa.

Ficheiro de ícone

O ficheiro de ícone é uma pequena imagem que representa o ícone do conector personalizado.

Ficheiro de script

O arquivo de script CSX (Visual C# Script) implanta para o conector personalizado e é executado para cada chamada para um subconjunto das operações do conector.

Ficheiro de definições

Em vez de fornecer os argumentos na linha de comando, um settings.json arquivo pode ser usado para especificá-los. Um arquivo típico settings.json se parece com este exemplo:

{
  "connectorId": "CONNECTOR-ID",
  "environment": "ENVIRONMENT-GUID",
  "apiProperties": "apiProperties.json",
  "apiDefinition": "apiDefinition.swagger.json",
  "icon": "icon.png",
  "script": "script.csx",
  "powerAppsApiVersion": "2016-11-01",
  "powerAppsUrl": "https://api.powerapps.com"
}

Espere esses itens no arquivo de definições. Se uma opção estiver a faltar, mas for necessária, o console solicitará as informações ausentes.

connectorId: A cadeia de caracteres de ID do conector para o conector personalizado. As operações de download e atualização exigem o parâmetro ID do conector, enquanto as operações de criação e validação não. O comando create cria um novo conector personalizado com uma nova ID. Se você precisar atualizar um conector personalizado existente usando o mesmo arquivo de definições, certifique-se de atualizar o arquivo de definições com a nova ID do conector da operação de criação.
environment: A cadeia de caracteres de ID do ambiente para o conector personalizado. Todas as operações requerem esse parâmetro, exceto a operação validar.
apiProperties: O caminho para o arquivo de propriedades da API. As operações de criação e atualização exigem o arquivo de propriedades da API. Quando esta opção está presente durante o download, o arquivo é baixado para seu local; caso contrário, o arquivo será salvo como apiProperties.json.
apiDefinition: O caminho para o arquivo swagger. As operações de criação, atualização e validação exigem o arquivo de definições de API. Quando esta opção está presente durante a operação de download, o arquivo é baixado para seu local; caso contrário, o arquivo será salvo como apiDefinition.swagger.json.
icon: O caminho para o arquivo de ícone opcional. Se não houver nenhuma especificação para esse parâmetro, as operações de criação e atualização usarão o ícone padrão. Quando esta opção está presente durante a operação de download, o arquivo é baixado para seu local; caso contrário, o arquivo será salvo como icon.png.
script: O caminho para o arquivo de script opcional. As operações de criação e atualização usam apenas o valor dentro do parâmetro especificado. Quando esta opção está presente durante a operação de download, o arquivo é baixado para seu local; caso contrário, o arquivo será salvo como script.csx.
powerAppsUrl: O URL da API para Power Apps. Este parâmetro é opcional e definido como https://api.powerapps.com por padrão.
powerAppsApiVersion: A versão da API a ser usada Power Apps. Este parâmetro é opcional e definido como 2016-11-01 por padrão.

Operações da linha de comandos

Inicie sessão no Power Platform executando:

paconn login

Este comando pede-lhe para iniciar sessão utilizando o processo de início de sessão do código do dispositivo. Siga o pedido de início de sessão. Não há suporte para a autenticação do Princípio de Serviço neste momento.

Fim de Sessão

Termine sessão executando:

paconn logout

Transferir os ficheiros do conector personalizado

Sempre baixe os arquivos do conector em um subdiretório com o ID do conector como o nome do diretório. Quando você especifica um diretório de destino, isso cria um subdiretório no diretório especificado. Caso contrário, ele será criado no diretório atual. Além dos três arquivos conectores, a operação de download também grava um quarto arquivo chamado settings.json contendo os parâmetros usados para baixar os arquivos.

Para transferir os ficheiros do conector personalizado, execute:

paconn download

paconn download -e [Power Platform Environment GUID] -c [Connector ID]

paconn download -s [Path to settings.json]

Quando o ambiente ou ID do conector não é especificado, o comando solicita os argumentos ausentes. O comando emite a saída do local de download do conector se ele for baixado com êxito.

Todos os argumentos também podem ser especificados usando um arquivo settings.json.

Arguments
   --cid -c       : The custom connector ID.
   --dest -d      : Destination directory.
   --env -e       : Power Platform environment GUID.
   --overwrite -w : Overwrite all the existing connector and settings files.
   --pau -u       : Power Platform URL.
   --pav -v       : Power Platform API version.
   --settings -s  : A settings file containing required parameters.
                    When a settings file is specified some command 
                    line parameters are ignored.

Criar um novo conector personalizado

Você pode criar um novo conector personalizado a partir dos arquivos de conectores executando a create operação. Para criar um conector, execute:

paconn create --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json]

paconn create -e [Power Platform Environment GUID] --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json] --icon [Path to icon.png] --secret [The OAuth2 client secret for the connector]

paconn create -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Quando você não especifica o ambiente, o comando solicita isso. No entanto, você precisa fornecer a definição da API e o arquivo de propriedades da API como parte do argumento da linha de comando ou um arquivo de definições. Forneça o segredo OAuth2 para um conector usando OAuth2. O comando imprime o ID do conector para o conector personalizado recém-criado após a conclusão bem-sucedida. Se você estiver a usar um settings.json arquivo para o comando create, atualize-o com a nova ID do conector antes de atualizar o conector recém-criado.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --api-prop    : Location for the API properties JSON document.
   --env -e      : Power Platform environment GUID.
   --icon        : Location for the icon file.
   --script -x   : Location for the script file.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --secret -r   : The OAuth2 client secret for the connector.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Atualizar conector personalizado já existente

Como a create operação, você pode atualizar um conector personalizado existente usando a update operação. Para atualizar um conector, execute:

paconn update --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json]

paconn update -e [Power Platform Environment GUID] -c [Connector ID] --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json] --icon [Path to icon.png] --secret [The OAuth2 client secret for the connector]

paconn update -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Quando você não especifica o ambiente ou a ID do conector, o comando solicita os argumentos ausentes. No entanto, você precisa fornecer a definição da API e o arquivo de propriedades da API como parte do argumento da linha de comando ou um arquivo de definições. Forneça o segredo OAuth2 para um conector usando OAuth2. O comando imprime o ID do conector atualizado após a conclusão bem-sucedida. Se você estiver a usar um settings.json arquivo para o comando update, certifique-se de especificar o ambiente correto e a ID do conector.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --api-prop    : Location for the API properties JSON document.
   --cid -c      : The custom connector ID.
   --env -e      : Power Platform environment GUID.
   --icon        : Location for the icon file.
   --script -x   : Location for the script file.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --secret -r   : The OAuth2 client secret for the connector.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Validar um JSON swagger

A operação validate pega num ficheiro swagger e verifica se segue todas as regras recomendadas. Valide um ficheiro swagger executando:

paconn validate --api-def [Path to apiDefinition.swagger.json]

paconn validate -s [Path to settings.json]

O comando imprime a mensagem de erro, aviso ou êxito, dependendo do resultado da validação.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Melhor prática

Transfira todos os conectores personalizados e utilize o git ou qualquer outro sistema de controlo de origem para guardar os ficheiros. Se existir uma atualização incorreta, reimplemente o conector ao executar novamente o comando de atualização com o conjunto de ficheiros certos a partir do sistema de controlo 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 que os IDs do ambiente e do conector estão certos.

Limitações

O projeto é limitado à criação, atualização e download de um conector personalizado em Copilot Studio Power Automate ambientes e Power Apps ambientes. Quando um ambiente não é especificado, você só tem a opção de selecionar um Power Automate ambiente. Relativamente a conectores não personalizados, o ficheiro swagger não é devolvido.

Nota

Propriedade stackOwner e arquivo de propriedades da API

Atualmente, há uma limitação que impede que você atualize os artefatos do conector em seu ambiente usando Paconn quando a stackOwner propriedade estiver presente no arquivo de propriedades da API. Como solução alternativa para isso, crie duas versões dos artefatos do conector:

Crie uma versão que contenha a stackOwner propriedade e envie-a para certificação.
Crie uma segunda versão que omita stackOwner permitir que você faça atualizações em seu próprio ambiente.

Estamos também a trabalhar para remover a limitação e iremos atualizar esta secção quando concluído.

Reportar problemas e comentários

Se você encontrar algum bug com a ferramenta, envie um problema na secção Problemas do nosso repositório GitHub.

Se você acredita ter encontrado uma vulnerabilidade de segurança que atende à definição da Microsoft de vulnerabilidade de segurança, envie um relatório ao MSRC. Mais informações podem ser encontradas em Perguntas frequentes sobre relatórios do MSRC.

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.

Last updated on 2025-06-24

Partilhar via