Partilhar via

Criar um conector personalizado com a CLI

  • Artigo

A ferramenta da linha de comandos paconn foi criada para ajudar no desenvolvimento de conectores personalizados para o Microsoft Power Platform.

Nota

Instalar

  1. Instale o Python 3.5+ a partir de [https://www.python.org/downloads](Python downloads). Selecione a ligação Transferir em qualquer versão do Python superior ao 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.

  2. Execute o instalador para começar a instalação e selecione a caixa "Add Python X.X to PATH" ("Adicionar Python X.X a CAMINHO").

  3. Confirme que o caminho da instalação está na variável PATH ao executar:

    python --version

  4. Quando o Python estiver instalado, instale paconn ao executar:

    pip install paconn

    Se obtiver erros a informar "Acesso negado", considere utilizar a opção --user ou execute o comando como um Administrador (Windows).

Diretório e ficheiros do conector personalizado

Um conector personalizado é composto por dois a quatro ficheiros: uma definição de swagger da API Open, um ficheiro de propriedades da API, um ícone opcional para o conector e um ficheiro de script csharp opcional. Geralmente, os ficheiros estão localizados num diretório com o ID de conector igual ao nome do diretório.

Por vezes, o diretório do conector personalizado pode incluir um ficheiro settings.json. Embora este ficheiro não faça parte da definição do conector, pode ser utilizado como um arquivo de argumentos para a CLI.

Ficheiro de definição (swagger) da API

O ficheiro de definição da API descreve a API para o conector personalizado ao utilizar a especificação OpenAPI. Também é conhecido como o ficheiro swagger. Para mais informações sobre as definições da API utilizadas para escrever um conector personalizado, aceda a Criar um conector personalizado a partir de uma definição de OpenAPI. Reveja também o tutorial no artigo Expandir uma definição de OpenAPI para um conector personalizado.

Ficheiro de propriedades da API

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

Pode ver abaixo mais informações sobre cada propriedade:

  • properties: o contentor para as informações.

  • connectionParameters: define o parâmetro de ligação para o serviço.

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

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

  • capabilities: descreve as capacidades do conector, por exemplo apenas cloud, gateway no local, etc.

  • policyTemplateInstances: uma lista opcional de instâncias de modelos de políticas e valores utilizados no conector personalizado.

Ficheiro de ícone

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

Ficheiro de script

O script é um ficheiro de script CSX que é implementado para o conector personalizado e executado para cada chamada a um subconjunto de operações do conector.

Ficheiro de definições

Pode utilizar um ficheiro settings.json para especificar os argumentos em vez de os fornecer na linha de comando. Regra geral, o ficheiro settings.json assemelha-se 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"
}

São esperados os itens seguintes no ficheiro de definições. Se uma opção necessária estiver em falta, a consola pedirá a informação ausente.

  • connectorId: a cadeia de ID do conector do conector personalizado. Este parâmetro é obrigatório para operações download e update, mas não para a operação create ou validate. Será criado um novo conector personalizado com o novo ID para o comando de criação. Se precisar de atualizar um conector personalizado acabado de criar com o mesmo ficheiro de definições, confirme que este está devidamente atualizado com o ID novo do conector da operação create.

  • environment: a cadeia de ID do ambiente do conector personalizado. Este parâmetro é obrigatório para todas as operações, exceto para a operação validate.

  • apiProperties: o caminho para o ficheiro apiProperties.json de propriedades da API. É necessário para as operações create e update. Se esta opção estiver presente durante a transferência, o ficheiro é transferido para a localização especificada; caso contrário, será guardado como apiProperties.json.

  • apiDefinition: o caminho para o ficheiro swagger. É obrigatório para as operações create, update e validate. Se esta opção estiver presente durante a operação download, para onde o ficheiro na localização especificada será gravado; caso contrário, será guardado como apiDefinition.swagger.json.

  • icon: o caminho para o ficheiro de ícone opcional. As operações create e update utilizarão o ícone predefinido quando este parâmetro não for especificado. Se esta opção estiver presente durante a operação download, para onde o ficheiro na localização especificada será gravado; caso contrário, será guardado como icon.png.

  • script: o caminho para o ficheiro de script opcional. As operações create e update só utilizarão o valor dentro do parâmetro especificado. Se esta opção estiver presente durante a operação download, para onde o ficheiro na localização especificada será gravado; caso contrário, será guardado como script.csx.

  • powerAppsUrl: O URL da API para o Power Apps. Por predefinição, este parâmetro é opcional e definido como https://api.powerapps.com.

  • powerAppsApiVersion: a versão da API a utilizar para o Power Apps. Por predefinição, este parâmetro é opcional e definido como 2016-11-01.

Operações da linha de comandos

Iniciar Sessão

Inicie sessão no Power Platform executando:

paconn login

Este comando irá pedir-lhe que inicie sessão através do processo de início de sessão de código do dispositivo. Siga o pedido de início de sessão. A autenticação do Princípio de Serviço não é suportada neste momento.

Fim de Sessão

Termine sessão executando:

paconn logout

Transferir os ficheiros do conector personalizado

Os ficheiros do conector são sempre transferidos para um subdiretório que tem o ID do conector como o nome do diretório. Quando é especificado um diretório de destino, o subdiretório é criado no diretório especificado. Caso contrário, é criado no diretório atual. Além dos três ficheiros de conector, a operação de transferência também vai escrever um quarto ficheiro chamado settings.json, que contém os parâmetros utilizados para transferir os ficheiros.

Para transferir os ficheiros do conector personalizado, execute:

paconn download

or

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

or

paconn download -s [Path to settings.json]

Se o ID do ambiente ou do conector não for especificado, o comando pedirá o argumento ou argumentos em falta. Se a transferência for bem-sucedida, o comando produz a localização da transferência do conector.

Todos os argumentos podem igualmente ser especificados com um ficheiro 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

É possível criar um novo conector personalizado a partir dos ficheiros de conectores executando a operação create. Para criar um conector, execute:

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

ou

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]

ou

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

Se o ambiente não estiver especificado, o comando pede-o. No entanto, os ficheiros de definição da API e propriedades da API têm de ser fornecidos como parte do argumento da linha de comando ou de um ficheiro de definições. Para conectores que utilizem OAuth2, tem de ser fornecido o segredo OAuth2. Após a conclusão, o comando imprime o ID do conector personalizado acabado de criar. Se estiver a utilizar um ficheiro settings.json para o comando de criação, confirme que o atualiza com o ID novo 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

Tal como com a operação create, é possível atualizar um conector personalizado existente utilizando a operação update. Para atualizar um conector, execute:

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

ou

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]

ou

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

Se o ID do ambiente ou do conector não for especificado, o comando pedirá o argumento ou argumentos em falta. No entanto, os ficheiros de definição da API e propriedades da API têm de ser fornecidos como parte do argumento da linha de comando ou de um ficheiro de definições. Para conectores que utilizem OAuth2, tem de ser fornecido o segredo OAuth2. Após a conclusão, o comando imprime o ID do conector atualizado. Se estiver a utilizar um ficheiro settings.json para o comando de atualização, confirme que são especificados os IDs corretos do ambiente e 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]

ou

paconn validate -s [Path to settings.json]

O comando irá imprimir a mensagem de erro, aviso ou êxito, consoante o 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 está limitado à criação, atualização e transferência de conectores personalizados nos ambientes do Power Automate e do Power Apps. Se não for especificado um ambiente, só são apresentados para escolha os ambientes do Power Automate. Relativamente a conectores não personalizados, o ficheiro swagger não é devolvido.

Ficheiro de propriedade stackOwner e apiProperties

Atualmente, existe uma limitação que impede que atualize os artefactos do conector no ambiente utilizando Paconn quando a propriedade stackOwner está presente no ficheiro apiProperties.json. Como solução alternativa para este problema, crie duas versões dos artefactos do conector: a primeira é a versão que é submetida para certificação e contém a propriedade stackOwner. O segundo tem a propriedade stackOwner omitida para permitir a atualização no 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 encontrar erros com a ferramenta, submeta um problema na secção Problemas do nosso repositório do GitHub.

Se achar que encontrou uma vulnerabilidade de segurança que corresponda à definição de vulnerabilidade de segurança da Microsoft, submeta a denúncia ao MSRC. Estão disponíveis mais informações nas perguntas mais frequentes sobre as denúncias do MSRC.

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para enviar comentários, aceda a Submeter problemas ou obter ajuda com conectores e selecione o tipo de comentários.