Introdução
Os conectores personalizados do Microsoft Power Platform usam as definições de OpenAPI (Swagger) para descrever autenticação, ações e gatilhos, além dos seus parâmetros. A especificação OpenAPI permite definir extensões que ampliam a definição principal para manipular cenários específicos. A Microsoft definiu uma série de extensões para a definição OpenAPI para permitir que você configure recursos específicos que são compatíveis com conectores personalizados.
Para identificar cada extensão, procure x-ms-<name> nas definições OpenAPI. Você provavelmente já usou algumas dessas definições para configurar um conector personalizado com o designer, por exemplo, ao inserir um resumo no parâmetro de uma ação que usa a extensão x-ms-summarypara armazenar o valor na definição. Há várias extensões que só podem ser editadas diretamente no editor Swagger do designer ou fazendo a exportação das definições do conector e, depois, a edição e nova importação. Você pode encontrar uma lista completa das extensões compatíveis com o conector personalizado.
Este módulo explica as seguintes extensões e suas utilizações:
x-ms-capabilities – usado no conector e na definição de nível de operação para indicar os recursos oferecidos.
x-ms-encoding – especifica a codificação para um parâmetro de caminho.
x-ms-dynamic-values e x-ms-dynamic-list – fornecem uma lista de opções para que o usuário selecione parâmetros de entrada em uma operação.
x-ms-dynamic-schema – permite que você faça com que parâmetros e respostas sejam dinâmicos com base nos resultados do esquema obtido em uma operação na API.
O principal caso de uso para configurar essas extensões é facilitar o uso do conector. Por exemplo, sem valores dinâmicos, os criadores teriam que conhecer valores de esquemas internos ou strings complicados para parâmetros de tipo/pesquisa. Configurando valores dinâmicos, você ajuda a criar uma lista suspensa simples com opções para os criadores selecionarem.
Tenha em mente que algumas extensões também precisam de compatibilidade com a API. Por exemplo, o esquema dinâmico requer que a API ajude em uma operação para recuperar o esquema. Nos casos em que você não controla a API, talvez não seja possível configurar esses tipos de extensão.
Configurar extensões
Enquanto algumas extensões de OpenAPI são configuradas com o uso do designer enquanto você trabalha com definições, as extensões abordadas neste módulo não o são. Para configurar essas extensões, adote uma das opções a seguir:
Importar OpenAPI – quando você importa um arquivo OpenAPI, ele pode conter extensões Microsoft OpenAPI.
CLI de Conectores do Microsoft Power Platform – a ferramenta de linha de comando paconn permite que você baixe e edite o arquivo de definição da API usando o editor de JSON que quiser. Depois de concluir a edição, você pode usar o paconn para subir as definições corrigidas para seu ambiente. Essa abordagem é a melhor opção quando você precisa fazer outras alterações no arquivo API Properties para parâmetros de conexão, por exemplo.
Microsoft Power Platform CLI: usando a ferramenta de linha de comando, você pode baixar o arquivo de definição de API para conectores personalizados usando soluções e editá-lo usando o editor JSON de sua preferência. Quando terminar de editar, você poderá usar a CLI para carregar as definições corrigidas de volta para a solução. Essa abordagem é melhor quando você precisa fazer outras alterações no arquivo de Propriedades da API para parâmetros de conexão e o conector personalizado está em uma solução.
Editor Swagger Integrado – o designer de conectores personalizados vem com um editor OpenAPI integrado, que é a forma mais rápida de adicionar extensões OpenAPI.
Usar o editor Swagger
Para conseguir visualizar o editor Swagger, ative o botão Swagger Editor durante qualquer uma das etapas no designer personalizado.
Sempre que o editor está ativado, a definição de OpenAPI em YAML Ain't Markup Language (YAML) fica exibida à esquerda. Já as mensagens de validação (se houver) e a lista de operações serão exibidas à direita.
Se você não está familiarizado com a YAML, ela um padrão simplificado de serialização de dados que ajuda a fazer alterações no conteúdo YAML, salvar essas alterações e inseri-las no runtime do conector.
Será fornecido um exemplo inicial para a maioria das alterações que você fizer. Um bom local para procurar alterações na YAML são os outros conectores localizados no repositório de GitHub de Conectores no Microsoft Power Platform. Por exemplo, para implementar a extensão x-ms-capability, você pode pesquisar no repositório para ver como outros conectores configuraram essa extensão.
Ao usar o editor, o recomendável é fazer alterações pequenas e com foco. O editor verifica sua sintaxe à medida que você digita e informa, em tempo real, a ocorrência de erros e onde eles ocorreram.
Dicas para trabalhar com a YAML no editor Swagger:
Questões sobre o recuo – o recuo faz parte das especificações da YAML; portanto, observe como o recuo é usado para fornecer informações específicas de configuração.
Chaves de abertura e fechamento {} – para cada chave de abertura { será necessária uma chave de fechamento }.
Colchetes de abertura e fechamento[] – para cada colchete de abertura será necessário um colchete de fechamento.
Ctrl + F para Localizar – use este atalho de teclado para fazer pesquisas na YAML.
Ctrl + Z para Desfazer – se quiser corrigir um erro, use o atalho de teclado CTRL + Z para desfazer a última alteração.
No restante deste módulo, você explorará como usar algumas das extensões de OpenAPI da Microsoft para facilitar o uso dos conectores personalizados.