Criar um conector personalizado com a CLI

Artigo
04/24/2024

A ferramenta da linha de comando paconn foi projetada para auxiliar o desenvolvimento de conectores personalizados do Microsoft Power Platform.

Observação

Essas notas sobre a versão descrevem uma funcionalidade que talvez ainda não tenha sido lançada.
Para descobrir quando está planejado o lançamento dessa funcionalidade, acesse Novidades e planejamentos para o Common Data Model e a Integração de Dados.
Os cronogramas de entrega e a funcionalidade prevista podem sofrer alterações ou não serem fornecidas (vá para política da Microsoft).

Instalar

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.
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 o seguinte:

python --version
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 consiste em dois a quatro arquivos: uma definição de swagger de Open API, um arquivo de propriedades da API, um ícone opcional para o conector e um arquivo de script csharp opcional. Os arquivos geralmente 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 pode ter um arquivo de settings.json. Embora esse arquivo não faça parte da definição do conector, ele pode ser usado 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. Ele é também conhecido como arquivo Swagger. Para obter mais informações sobre as definições de API usadas para escrever o conector personalizado, acesse Criar um conector personalizado de uma definição 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. Essas propriedades não fazem parte da definição da API. Ele 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"
        }
      }
    ]    
  }
}

Mais informações sobre cada uma das propriedades são dadas abaixo:

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: descreve os recursos do conector, por exemplo, somente na nuvem, gateway local etc.
policyTemplateInstances: uma lista opcional de instâncias do modelo de política e de valores usados no conector personalizado.

Arquivo de ícone

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

Arquivo de script

O script é um arquivo de 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 ao seguinte 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"
}

No arquivo de configurações, esperam-se os seguintes itens. Se uma opção necessária estiver ausente, o console solicitará as informações ausentes.

connectorId: a cadeia de caracteres de ID do conector personalizado. Esse parâmetro é necessário para operações de download e atualização, mas não para a operação create ou validate. Um novo conector personalizado com a nova ID será criado para o comando create. Caso precise atualizar um conector personalizado que acabou de ser criado usando o mesmo arquivo de configurações, verifique se o arquivo de configurações foi atualizado corretamente com a nova ID do conector da operação create.
environment: a cadeia de caracteres de ID do ambiente do conector personalizado. Este parâmetro é necessário para todas as operações, exceto a operação validate.
apiProperties: o caminho do arquivo apiProperties.json de propriedades da API. Ele é necessário para a operação create e update. Quando essa opção estiver presente durante o download, o arquivo será baixado no local especificado, caso contrário, será salvo como apiProperties.json.
apiDefinition: o caminho do arquivo do swagger. Ele é necessário para a operação de create, update e validate. Quando essa opção estiver presente durante a operação de download, o arquivo será gravado no local especificado, caso contrário, será salvo como apiDefinition.swagger.json.
icon: o caminho do arquivo de ícone opcional. As operações de criação e atualização usarão o ícone padrão quando esse parâmetro não for especificado. Quando essa opção estiver presente durante a operação de download, o arquivo será gravado no local especificado, caso contrário, será salvo como icon.png.
script: o caminho do arquivo de script opcional. As operações de criação e atualização usarão apenas o valor dentro do parâmetro especificado. Quando essa opção estiver presente durante a operação de download, o arquivo será gravado no local especificado, caso contrário, será 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

Faça logon no Power Platform executando:

paconn login

Esse comando solicitará que você entre usando o processo de logon do código do dispositivo. Siga o prompt para fazer logon. A autenticação de Princípio de Serviço não tem suporte neste momento.

Fazer logoff

Fazer logoff executando:

paconn logout

Baixar arquivos do conector personalizado

Os arquivos do conector são sempre baixados em um subdiretório em que a ID do conector é o nome do diretório. Quando houver um diretório de destino especificado, o subdiretório será criado nele. Caso contrário, ele será criado no diretório atual. Além dos três arquivos do conector, a operação de download também gravará 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

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

paconn download -s [Path to settings.json]

Quando não houver especificação do ambiente ou da ID do conector, o comando solicitará o(s) argumento(s) ausente(s). O comando criará 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

Um novo conector personalizado pode ser criado 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]

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 não houver um ambiente especificado, o comando solicitará um. No entanto, a definição da API e o arquivo de propriedades da API devem ser fornecidos como parte do argumento da linha de comando ou de um arquivo de configurações. O segredo OAuth2 deve ser fornecido para um conector que esteja usando OAuth2. O comando imprimirá 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 create, 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, um conector personalizado existente pode ser atualizado 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]

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 não houver especificação do ambiente ou da ID do conector, o comando solicitará o(s) argumento(s) ausente(s). No entanto, a definição da API e o arquivo de propriedades da API devem ser fornecidos como parte do argumento da linha de comando ou de um arquivo de configurações. O segredo OAuth2 deve ser fornecido para um conector que esteja usando OAuth2. O comando imprimirá a ID do conector atualizado, caso a conclusão seja bem-sucedida. Se você estiver usando um arquivo settings.json para o comando update, 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]

paconn validate -s [Path to settings.json]

O comando imprimirá 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 no ambiente do Power Automate e do Power Apps. Quando não houver um ambiente especificado, somente os ambientes do Power Automate estarão listados como opções de escolha. Para conectores não personalizados, o arquivo do swagger não é retornado.

Propriedade stackOwner e arquivo apiProperties

Atualmente, há uma limitação que impede você de atualizar os artefatos do seu conector em seu ambiente usando o Paconn quando a propriedade stackOwner estiver presente em seu arquivo apiProperties.json. Como solução para isso, crie duas versões de seus artefatos de conector: A primeira é a versão que é enviada para certificação e contém a propriedade stackOwner. A segunda tem a propriedade stackOwner omitida para permitir a atualização em seu ambiente. Estamos trabalhando para remover a limitação e atualizaremos esta seção assim que ela for concluída.

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.

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.

Compartilhar via

Criar um conector personalizado com a CLI

Instalar

Diretório e arquivos do conector personalizado

Arquivo de definição da API (swagger)

Arquivo de propriedades da API

Arquivo de ícone

Arquivo de script

Arquivo de configurações

Operações da linha de comando

Fazer logoff

Baixar arquivos do conector personalizado

Criar um novo conector personalizado

Atualizar um conector personalizado existente

Validar um JSON swagger

Melhor prática

Limitações

Como relatar problemas e comentários

Enviar comentários

Recursos adicionais

Compartilhar via

Criar um conector personalizado com a CLI

Instalar

Diretório e arquivos do conector personalizado

Arquivo de definição da API (swagger)

Arquivo de propriedades da API

Arquivo de ícone

Arquivo de script

Arquivo de configurações

Operações da linha de comando

Logon

Fazer logoff

Baixar arquivos do conector personalizado

Criar um novo conector personalizado

Atualizar um conector personalizado existente

Validar um JSON swagger

Melhor prática

Limitações

Como relatar problemas e comentários

Enviar comentários

Recursos adicionais