Criar um conector personalizado com a CLI

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

Instalar

1. Instale o Python 3.5+ de [https://www.python.org/downloads](Python downloads). Selecione o link Download em qualquer versão do Python superior ao Python 3.5. Para Linux e macOS X, acesse o respectivo link na página. Você também pode instalar usando um gerenciador de pacotes específico do sistema operacional de sua escolha.

2. Execute o instalador para iniciar a instalação e certifique-se de marcar a caixa Adicionar Python X.X ao PATH.

3. Verifique se o caminho de instalação está na variável PATH executando o seguinte:

   python --version

4. Após a instalação do Python, instale paconn executando o seguinte:

   pip install paconn

   Se você receber erros dizendo Acesso negado, use a opção --user ou execute o comando como Administrador (Windows).

Diretório e arquivos do conector personalizado

Um conector personalizado é composto por quatro arquivos:

• uma definição da API/swagger Aberta
• 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 em que a ID do conector é o nome do diretório.

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

Arquivo de definição da API (swagger)

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

Arquivo de propriedades da API

O arquivo de propriedades da API contém algumas propriedades do conector personalizado que não fazem parte da definição da API. O arquivo de propriedades da API contém informações como: cor da marca, informações de autenticação etc. Geralmente, o arquivo de propriedades da API é semelhante 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"
        }
      }
    ]    
  }
}

Veja mais informações sobre cada uma das propriedades:

• properties: o contêiner para as informações.

• connectionParameters: define o parâmetro de conexão do serviço.

• iconBrandColor: a cor da marca do ícone em código hexadecimal HTML do conector personalizado.

• scriptOperations: uma lista das operações que são executadas com o arquivo de script. Uma lista de scriptOperations vazia indica que todas as operações são executadas com o arquivo de script.

• capabilities: descrição dos recursos do conector. Por exemplo, somente na nuvem e gateway local.

• policyTemplateInstances: uma lista opcional de instâncias do modelo de política e de valores que o conector personalizado usa.

Arquivo de ícone

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

Arquivo de script

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

Arquivo de configurações

Em vez de fornecer os argumentos na linha de comando, pode ser usado um arquivo settings.json para especificá-los. Geralmente, o arquivo settings.json é semelhante a 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 configurações. Se uma opção necessária estiver ausente, o console solicita as informações ausentes.

• connectorId: a cadeia de caracteres de ID do conector personalizado. As operações Baixar e atualizar exigem o parâmetro ID do conector, enquanto as operações criar e validar não. O comando create cria um novo conector personalizado com um novo ID. Caso precise atualizar um conector personalizado existente usando o mesmo arquivo de configurações, certifique-se de atualizar o arquivo de configurações com a nova ID do conector da operação de criação.

• environment: a cadeia de caracteres de ID do ambiente do conector personalizado. Todas as operações exigem este parâmetro, exceto a operação de validação.

• apiProperties: o caminho ao arquivo de propriedades da API. As operações de Criação e atualização exigem o arquivo de propriedades da API. Quando essa opção estiver presente durante o download, o arquivo é baixado no local, caso contrário, o arquivo é salvo como apiProperties.json.

• apiDefinition: o caminho do arquivo do swagger. As operações de criação, atualização e validação exigem o arquivo de definições da API. Quando essa opção estiver presente durante a operação de download, o arquivo é baixado no local, caso contrário, o arquivo é salvo como apiDefinition.swagger.json.

• icon: o caminho do arquivo de ícone opcional. Se não houver especificação para este parâmetro, as operações de criação e atualização usam o ícone padrão. Quando essa opção estiver presente durante a operação de download, o arquivo é baixado no local, caso contrário, o arquivo é salvo como icon.png.

• script: o caminho do arquivo de script opcional. As operações de criação e atualização somente usam o valor dentro do parâmetro especificado. Quando essa opção estiver presente durante a operação de download, o arquivo é baixado no local, caso contrário, o arquivo é salvo como script.csx.

• powerAppsUrl: a URL da API para o Power Apps. Esse parâmetro é opcional e definido como https://api.powerapps.com, por padrão.

• powerAppsApiVersion: a versão da API a ser usada para o Power Apps. Esse parâmetro é opcional e definido como 2016-11-01, por padrão.

Operações da linha de comando

Logon

Faça logon no Power Platform executando:

paconn login

Esse comando solicita que você faça logon usando o processo de logon do código do dispositivo. Siga o prompt para fazer logon. Não há suporte para a autenticação de Princípio de Serviço neste momento.

Fazer logoff

Fazer logoff executando:

paconn logout

Baixar arquivos do conector personalizado

Sempre baixe os arquivos do conector em um subdiretório em que a ID do conector é 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 é criado no diretório atual. Além dos três arquivos do conector, a operação de download também grava um quarto arquivo chamado settings.json que contém parâmetros usados para baixar os arquivos.

Baixe os arquivos do conector personalizado executando o seguinte:

paconn download

or

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

or

paconn download -s [Path to settings.json]

Quando não houver especificação do ambiente ou da ID do conector, o comando solicita os argumentos ausentes. O comando cria o 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 operação create. Crie um conector executando o seguinte:

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

or

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]

or

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

Quando você não especifica o ambiente, o comando o solicita. 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 de um arquivo de configurações. Forneça o segredo OAuth2 para um conector que usa o OAuth2. O comando imprimi a ID do conector para o conector personalizado recém-criado, caso a conclusão seja bem-sucedida. Se você estiver usando um arquivo settings.json para o comando de criação, lembre-se de atualizá-lo 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 um conector personalizado existente

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

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

or

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]

or

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

Quando você não especifica o ambiente ou o 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 de um arquivo de configurações. Forneça o segredo OAuth2 para um conector que usa o OAuth2. O comando imprime a ID do conector atualizado, caso a conclusão seja bem-sucedida. Se você estiver usando um arquivo settings.json para o comando de atualização, verifique se estão especificados o ambiente e a ID do conector corretos.

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 validade pega um arquivo swagger e verifica se ele segue todas as regras recomendadas. Valide um arquivo swagger executando:

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

or

paconn validate -s [Path to settings.json]

O comando imprime a mensagem de erro, aviso ou sucesso 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

Baixe todos os conectores personalizados e use o git ou qualquer outro sistema de controle do código-fonte para salvar os arquivos. Se houver uma atualização incorreta, reimplante o conector, reexecutando o comando update com o conjunto correto de arquivos do sistema de controle do código-fonte.

Teste o conector personalizado e o arquivo de configurações em um ambiente de teste antes de implantá-los no ambiente de produção. Sempre verifique mais de uma vez se o ambiente e a ID do conector estão corretos.

Limitações

O projeto é limitado à criação, à atualização e ao download de um conector personalizado nos ambientes dos Copilot Studio, Power Automate e Power Apps. Quando um ambiente não é especificado, você só tem a opção de selecionar um ambiente do Power Automate. Para conectores não personalizados, o arquivo do swagger não é retornado.

Como relatar problemas e comentários

Caso encontre algum bug na ferramenta, envie-o na seção Problemas de nosso repositório do GitHub.

Caso acredite ter encontrado uma vulnerabilidade de segurança que corresponda à definição de vulnerabilidade de segurança da Microsoft, envie o relatório para o MSRC. Mais informações podem ser encontradas em Perguntas frequentes do MSRC sobre relatórios.

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.