Usar extensões do OpenAPI
Esta unidade explora como usar as extensões Microsoft OpenAPI x-ms-capabilities e x-ms-url-encoding em seus conectores personalizados.
A extensão x-ms-capabilities ajuda a configurar quais recursos são oferecidos pelo conector no nível de conector e no nível de operação. Atualmente, os conectores personalizados do Microsoft Power Platform podem ser configurados para as seguintes opções:
chunkTransfer – nível de operação
testConnection – nível de conector
Habilitar transferência de parte
Ao lidar com mensagens, o tempo de execução do conector limita o conteúdo da mensagem a um tamanho máximo. Esse limite ajuda a reduzir a sobrecarga criada pelo armazenamento e processamento de mensagens grandes. Para ajudar a lidar com mensagens maiores do que esse limite, os conectores podem fragmentar uma mensagem grande em partes de mensagem menores. Assim, você ainda pode transferir conteúdo grande. Ao se comunicar com outros serviços por meio de conectores, o tempo de execução pode consumir mensagens grandes, mas apenas em partes. Essa condição significa que os conectores também devem dar suporte a agrupamento e à troca de mensagens HTTP subjacente entre o conector e esses serviços deve usar agrupamento.
Para que um conector personalizado use a transferência de partes, os seguintes parâmetros são necessários:
A API deve dar suporte a agrupamento. Para obter mais informações, consulte Tratamento de mensagens em partes para conectores.
O conector personalizado deve habilitar a extensão de funcionalidade de transferência de partes na ação.
O criador que está usando a ação do conector deve habilitar a transferência de partes para a etapa do fluxo.
Na definição de conector personalizado, você adicionaria a lógica a seguir à definição de operações para a qual deseja habilitar a transferência de partes.
{chunkTransfer: true}
Se estivesse trabalhando com o arquivo apiDefinition.swagger.json baixado em vez do editor YAML, você faria a alteração mostrada na captura de tela a seguir.
Depois que essa alteração for feita, a indicação da alteração não será mostrada no designer de conector personalizado. No entanto, quando a ação for usada em um fluxo, a opção Permitir agrupamento a seguir será exibida nas configurações da etapa.
Supondo que a API desse suporte a isso, depois que a agrupamento fosse habilitado, as mensagens grandes funcionariam e seriam transferidas usando agrupamento.
Configurar uma conexão de teste
Por padrão, quando você cria uma conexão usando um conector personalizado, a conexão não é verificada como válida ou não. Por exemplo, se fornecesse uma URL de host inválido ou uma chave de API inválida, você poderia criar uma conexão, mas eventualmente ela falharia quando a conexão fosse usada. Usando a extensão OpenAPI testConnection, você pode especificar uma operação no conector personalizado que será executada durante a criação da conexão para validar a configuração fornecida.
Para implementar o teste de conexão, você deve definir uma operação simples no conector personalizado que retorne HTTP 200 (êxito). Essa operação pode ser uma existente que você já tenha configurado ou você pode criar uma especificamente para testar a conexão. Se você configurar uma operação de teste específica, recomendamos que a marque como interna para que os usuários não tentem usá-la. Você também pode passar parâmetros estáticos para a operação. Por exemplo, se a ação usar um parâmetro $top para limitar o número de registros retornados, você poderá usar parâmetros para limitar os resultados a um registro.
O exemplo a seguir mostra a operação ListInvoices definida e como ela será usada para testar a conexão e mostra a configuração da extensão testConnection.
A edição de apiDefinition.swagger.json seria semelhante à imagem a seguir.
Configurar a codificação de caminho
A extensão x-ms-url-encoding se aplica aos parâmetros incluídos no caminho da URL de solicitação.
Por exemplo, você pode definir uma ação para devolver clientes por país/região com a seguinte solicitação:
https://myapi.myservice.com/customers/{country}
Nessa ação, país/região se tornará um parâmetro fornecido pelo usuário do conector. Como esses parâmetros fazem parte do caminho, eles precisam ser codificados por URL. Por padrão, os parâmetros de caminho são codificados por URL única. No entanto, em determinados cenários, a API subjacente pode esperar que os parâmetros tenham codificação dupla de URL para resolver ambiguidades potenciais que são introduzidas por certos caracteres, como arroba (@), barra (/), barra invertida (\) e assim por diante.
Para configurar a codificação dupla em um parâmetro de caminho, adicione a seguinte opção ao parâmetro:
x-ms-url-encoding: double
Considere a API que tem dois métodos que retornam o parâmetro do caminho de entrada, exceto que um deles usa codificação dupla, conforme mostrado na imagem a seguir.
Quando você executa um fluxo do Microsoft Power Automate que chama ambas as ações com uma entrada complexa, a codificação dupla passa o mesmo valor de texto para a API, exceto que agora ele é codificado duas vezes.
Essa extensão simplifica o tratamento dos parâmetros em que a API espera a codificação de URL dupla, pois um usuário do conector não precisa codificar os parâmetros do caminho ao chamar as ações.