Usar a CLI de conectores do Microsoft Power Platform
Nem toda tarefa no ciclo de vida de um conector personalizado pode ser realizada usando uma interface do usuário do conector personalizado no Maker Portal. A ferramenta de linha de comando paconn deve ser usada como parte do ciclo de vida do conector personalizado nas seguintes tarefas:
Baixar um conector personalizado para edição e controle de origem depois de criá-lo ou editá-lo usando o maker portal. Por exemplo, para adicionar propriedades de conexão personalizadas, você deve baixar e editar os arquivos.
Criar um conector personalizado em um ambiente usando os arquivos de definição individuais baixados. O conector que foi criado não está contido em uma solução. Por exemplo, esse conector poderia ser usado para criar o mesmo conector com outra ID exclusiva no mesmo ambiente se você quisesse uma cópia e, ao mesmo tempo, manter o original intacto.
Atualizar um conector existente. Esta etapa pode ser usada na atualização de um conector personalizado autônomo ou um que esteja contido em uma solução. Por exemplo, você poderá atualizar um conector depois de editar as propriedades de conexão.
Validar o conector. Esta etapa é necessária para certificação, mas muitos dos erros detectados podem melhorar a qualidade de qualquer conector personalizado.
Garanta que ninguém esteja editando o conector personalizado usando o portal e os arquivos baixados simultaneamente, para evitar a perda de alterações. Quando você carrega usando a ferramenta de linha de comando, ela não verifica se há conflitos e apenas substitui a definição existente, sem mesclar.
Instale a ferramenta de linha de comando
A ferramenta de linha de comando paconn requer o Python 3.5 ou mais recente. Antes de instalar a ferramenta, instale o Python e, depois, o comando pip install paconn. Instruções de instalação detalhadas estão disponíveis.
Parâmetros ou arquivo de configurações
Você pode configurar as opções da ferramenta usando parâmetros de linha de comando ao executar um comando ou com o uso de um arquivo settings.json. Especifique um arquivo de configurações usando -settings ou -s parameter. Ao usar o arquivo de configurações, os demais parâmetros de linha de comando são ignorados.
O uso do arquivo de configurações pode facilitar as várias execuções de comandos. Quando você baixa um conector personalizado, um arquivo settings.json é criado como parte do download. A captura de tela a seguir mostra um exemplo de um arquivo settings.json.
Analise a lista detalhada de configurações para obter mais informações específicas sobre valores de cada configuração.
Autenticar
Para usar qualquer um dos comandos paconn, você deve primeiro fazer a autenticação usando o comando paconn login. Esse comando fornecerá um código e o direcionará para https://microsoft.com/devicelogin, em que você entrará com sua conta e fornecerá esse código.
A conclusão da entrada interativa estabelecerá uma sessão a ser usada por outros comandos paconn. A sessão expirará após algum tempo, e você precisará restabelecê-la para continuar usando a ferramenta. Você pode forçar um fim da sessão a qualquer momento usando o comando paconn logout.
Como é necessária uma entrada de usuário interativa para autenticação, a ferramenta de linha de comando pode ser usada com scripts de automação assistidos, mas não funcionaria em cenários não assistidos como um pipeline de criação.
Baixar
Use o comando paconn download para baixar um conector existente. Se você não fornecer parâmetros, será solicitado a escolher em uma lista de ambientes e em uma lista de conectores no ambiente selecionado.
Use -e parameter para pré-selecionar um ambiente específico e ignorar a lista de ambientes. A maneira mais fácil de obter um identificador de ambiente é pela URL do maker portal.
O uso dessa opção apresenta apenas os conectores desse ambiente.
Em vez de selecionar um conector de maneira interativa, você pode especificar um conector específico passando um identificador de conector no -c parameter. A maneira mais fácil de obter o identificador do conector é baixar o conector uma vez e, em seguida, copiar o valor no arquivo de configurações.
Como resultado, o comando será semelhante ao seguinte exemplo:
paconn download -e d80faec4-eb14-4076-9681-9b46b97adbfd -c shared_cr83e-5fcontoso-20invoicing-5f20493607d490e1e0
Este comando baixa os arquivos do conector sem solicitações.
A outra vantagem de usar identificadores é que, diferentemente dos números de ordem nas listas de seleção, os identificadores não são alterados à medida que ambientes e conectores são criados ou excluídos.
Os arquivos baixados são colocados em uma pasta chamada usando a ID do conector. Se o diretório já existir, ocorrerá falha no comando e você deverá remover a pasta manualmente. Os arquivos baixados são estes quatro:
apiDefinition.swagger.json: esse arquivo de definição de API descreve a API do conector personalizado usando a especificação OpenAPI.
apiProperties.json: o arquivo de propriedades da API contém as propriedades dos modelos de política e do conector personalizado.
Icon.png: o arquivo de ícone é uma pequena imagem que representa o ícone do conector personalizado.
settings.json: é possível usar esse arquivo de configurações pré-configurado em vez de fornecer parâmetros para cada comando.
Criar
O comando paconn create cria um conector personalizado no ambiente de destino usando os arquivos de definição especificados. A definição da API, as propriedades da API e o ícone devem ser especificados por parâmetros ou um arquivo de configurações. O comando create solicitará quaisquer outros parâmetros, como ID do ambiente, se os parâmetros não forem fornecidos. O exemplo a seguir mostra o comando create:
paconn create ^
-e [Microsoft 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]
Se o conector usar OAuth2, você poderá usar o parâmetro -secret para especificar o valor do segredo do cliente.
Atualizar
O comando paconn update atualiza um conector personalizado existente no ambiente de destino usando os arquivos de definição especificados. A definição da API, as propriedades da API e o ícone devem ser especificados por parâmetros ou um arquivo de configurações. O comando update solicitará quaisquer outros parâmetros, como ID do ambiente, se os parâmetros não forem fornecidos. O exemplo a seguir mostra o comando update:
paconn update ^
-e [Microsoft 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]
Importante
A atualização substituirá a definição no ambiente de destino, mesmo que ela tenha sido modificada desde que você baixou sua cópia. É importante coordenar com qualquer outra pessoa que esteja fazendo atualizações no conector.
A CLI de Conectores do Microsoft Power Platform é uma ferramenta essencial ao criar conectores personalizados. Use-a como parte do ciclo de vida para ajudar a fazer alterações nos conectores e para baixar cópias dos arquivos de definição de conector do controle de origem.