Usar a extensão de lista dinâmica de valores
Quando você configura um parâmetro para uma ação em um conector personalizado, a experiência padrão do fabricante para inserir o valor do parâmetro é uma caixa de texto simples. Se você tiver um parâmetro em uma ação Adicionar Fatura chamado ID do Tipo de Fatura, a experiência do fabricante será semelhante à imagem a seguir.
O fabricante precisará saber os valores corretos do campo ID do Tipo de Fatura que, neste exemplo, são os valores abaixo.
| Valor | Rótulo |
|---|---|
| 1 | Ordem de Compra |
| 2 | Sem Ordem de Compra |
Um fabricante precisará inserir 1 para indicar que a fatura é do tipo Ordem de Compra. Para facilitar a definição de OpenAPI, você deve permitir a palavra-chave enumeração. Você pode definir uma enumeração com uma lista de valores que o fabricante pode escolher.
É possível configurar uma enumeração usando o designer do conector personalizado e editando a configuração do parâmetro. Na configuração, se você selecionar Estático na área Tipo de lista suspensa, isso permitirá que você forneça uma lista de valores separados por vírgula. A captura de tela a seguir mostra a aparência da configuração ID do Tipo de Fatura.
Também é possível usar o editor Swagger e adicionar a enumeração, conforme mostrado na imagem a seguir.
Além disso, se você examinou a experiência do fabricante no Power Automate, ele agora é semelhante à imagem a seguir.
Embora a experiência tenha sido melhorada, ela ainda exige que o fabricante saiba o que significa o valor 1 ou 2. É possível descrever o significado desses valores na descrição do parâmetro para ajudar a simplificar o processo para os fabricantes. O uso de enumerações é ideal para dados autodescritivos, por exemplo, se você tiver um parâmetro de Dias de Vencimento e usar uma enumeração para 30, 60, 90 que será simples de entender e usar. Outra limitação no uso de enumeração é se a API adicionar novos valores permitidos. Você deverá editar a definição de enumeração do conector personalizado e publicar a versão atualizada do conector. Para melhorar ainda mais a experiência, a Microsoft adicionou a extensão de OpenAPI x-ms-dynamic-values.
Configurar valores dinâmicos
É possível configurar a extensão x-ms-dynamic-values em um parâmetro para que a lista de valores seja recuperada da API subjacente.
As vantagens dessa abordagem são:
É possível configurar um rótulo que o usuário veja, além do valor.
Os valores retornados sempre representam os valores corretos da API.
A API pode cortar a lista de valores com base na segurança ou em outras necessidades, por usuário ou por conexão.
Outros valores de parâmetro podem ser passados para a API para permitir a filtragem da lista retornada.
A saída de um campo pode ser usada como um parâmetro de entrada para outra chamada à API, tornando possível a criação de opções dependentes, como listas de país/região e estados.
A API com a qual você trabalha deve fornecer uma operação que retorne uma matriz de valores válidos e, opcionalmente, suas descrições. Como base ao exemplo anterior de ID do Tipo de Fatura, a API forneceu uma operação ListInvoiceTypes que retornou os dados a seguir.
No designer do conector personalizado do parâmetro ID do Tipo de Fatura, é possível configurar a extensão x-ms-dynamic-values selecionando Dinâmico e especificando uma ID de operação e as propriedades Valor e Nome de exibição do valor. A captura de tela a seguir mostra a configuração do ID do Tipo de Fatura.
Também é possível configurar a extensão x-ms-dynamic-values usando o editor Swagger.
O uso do editor Swagger ou o download e a edição do arquivo JSON serão necessários se você estiver configurando parâmetros na extensão.
Agora com a extensão configurada, o fabricante tem uma experiência mais amigável ao usar a ação.
Além da extensão x-ms-dynamic-values, a Microsoft também implementou uma extensão mais recente chamada x-ms-dynamic-list. Em termos de conceito, as duas têm a mesma finalidade de tornar o parâmetro da ação uma lista suspensa que o usuário pode selecionar. Considere a extensão x-ms-dynamic-values como a versão 1 e a extensão x-ms-dynamic-list como a versão 2. Se você tem fluxos existentes mais antigos, recomendamos que implemente as duas em sua definição. Se você tem somente fluxos recém-criados, use a x-ms-dynamic-list. A extensão x-ms-dynamic-list melhora o esquema dos parâmetros da ação, possibilitando a resolução de algumas referências ambíguas. Por exemplo, se uma solicitação tiver uma ID de parâmetro de caminho e uma ID de parâmetro como parte do corpo da solicitação, a especificação x-ms-dynamic-list permitirá diferenciar os dois parâmetros, mas a x-ms-dynamic-values não permitirá essa API.
Para configurar a extensão x-ms-dynamic-list, você deve alterar diretamente a definição de OpenAPI, pois o designer do conector personalizado configura apenas a x-ms-dynamic-values. A imagem a seguir mostra a configuração x-ms-dynamic-values que também adicionou uma configuração x-ms-dynamic-list.
Configurar valores dinâmicos em parâmetros para um conector personalizado pode torná-lo mais amigável para os fabricantes.