Usar esquema dinâmico
Ao configurar uma ação em um conector personalizado, você também pode configurar parâmetros. Esses parâmetros são configurados quando uma definição de OpenAPI ou uma solicitação de exemplo é importada. Seja qual for a abordagem usada, a lista de parâmetros é fixa. Ao usar essa ação, é exibida uma lista estática de parâmetros para o criador, conforme definido pelo conector. Para muitos cenários, essa abordagem é apropriada, pois os parâmetros da lista não variam. Em alguns casos, os parâmetros exibidos para entrada são variáveis.
Os casos de uso mais comuns são:
A lista de parâmetros varia de acordo com um tipo, como categoria ou tipo de fatura.
O estado do registro pode determinar quais parâmetros podem ser alterados. Por exemplo, uma ordem enviada pode ter parâmetros disponíveis diferentes de uma ordem não enviada.
A lista de parâmetros pode ser cortada por segurança.
Uma implementação de ação comum em alguns tipos de dados diferentes. Por exemplo, a API pode implementar uma ação Criar que se aplica a contas, contatos, ordens ou faturas. Os parâmetros de entrada serão definidos pelo tipo de objeto selecionado pelo criador.
Os conectores personalizados atendem a esses cenários, permitindo que você configure extensões de OpenAPI de esquema dinâmico. Quando as extensões de OpenAPI de esquema dinâmico são configuradas, o runtime do conector personalizado chama uma operação para recuperar o esquema que define quais parâmetros devem ser visíveis para a ação especificada. Os dados do esquema podem incluir outras opções, como o nome de exibição e a descrição do parâmetro.
No exemplo da API da Contoso Invoicing, depois que a definição de OpenAPI é importada, a ação é semelhante à imagem a seguir quando usada em um fluxo do Power Automate.
A imagem anterior mostra os parâmetros que não são relevantes ao adicionar uma fatura de ordem de compra, em relação a uma fatura não referente à ordem de compra. Além disso, nem todos os campos da fatura são entradas válidas para a criação da fatura. Por exemplo, createDate é um campo definido pela API e não deve fazer parte da entrada do usuário. Depois que você implementar valores dinâmicos para a ID do tipo de fatura e o esquema dinâmico para os outros parâmetros, a ação terá a seguinte aparência.
Quando o criador altera o tipo de fatura de ordem de compra para não referente à ordem de compra, o parâmetro Ordem de Compra é oculto ou exibido, conforme apropriado.
O runtime do conector personalizado permite duas extensões diferentes que podem ser usadas para configuração do esquema dinâmico. As duas têm a mesma meta, em que a extensão x-ms-dynamic-schema é a versão 1 e x-ms-dynamic-properties é a versão 2. Se você precisa usar fluxos mais antigos com a ação, pode configurar as duas versões no conector personalizado. Se você usa apenas fluxos novos, pode configurar somente a extensão -ms-dynamic-properties.
Suporte à API
Para que você configure o esquema dinâmico, a API subjacente deve definir a operação que retorna o esquema para permiti-lo. Se a API ainda não tiver uma ação adequada e você não tiver puder modificar a API ou solicitar as alterações, talvez não seja possível implementar o esquema dinâmico.
A operação que retorna o esquema pode usar um ou mais parâmetros que são passados do runtime do conector personalizado. Esses parâmetros podem ser constantes ou representar outros dados que são coletados no cartão de ação. A API pode usar os dados para filtrar a lista de parâmetros retornados como parte do esquema. No exemplo anterior, o Tipo de Fatura é passado como um parâmetro para que a operação obtenha o esquema dinâmico.
A resposta da operação usada no esquema dinâmico deve ser um esquema JSON válido. O exemplo a seguir mostra o que GetInvoiceSchema da API da Contoso retorna.
Observe os seguintes pontos principais sobre o conteúdo:
O tipo deve ser inserido e é usado para identificar o tipo de dados do parâmetro.
O resumo e a descrição são usados no designer do Power Automate para identificar os parâmetros para o criador.
A propriedade de extensão x-ms-visibility pode ser fornecida para indicar onde você acha que esse parâmetro sempre deve ser mostrado (valor "importante") ou se uma ação do usuário for necessária para mostrá-la ao criador, como Selecionar link avançado em um cartão de fluxo (valor "avançado"). Como essas informações são recuperadas de forma dinâmica, elas podem variar dependendo das informações de contexto disponíveis.
A matriz necessária retorna a lista dos parâmetros exigidos.
Configurar a extensão do esquema dinâmico
Para configurar as extensões x-ms-dynamic-schema ou x-ms-dynamic-properties, você deve editar diretamente a definição de OpenAPI do conector personalizado. No momento, o suporte ao designer de conector personalizado não está disponível para editar esses valores.
A imagem a seguir mostra a aparência da configuração do parâmetro AddInvoice após a definição de OpenAPI fornecida pela API que foi importada.
O exemplo anterior mostra que AddInvoice usa um objeto CreateInvoiceRequest como entrada. As propriedades são definidas por uma referência a #/definitions/Invoice, que é uma definição compartilhada de todas as propriedades da fatura.
Para implementar a chamada na extensão do esquema dinâmico, você pode substituir as propriedades pela extensão configurada.
Em vez de ter uma lista codificada de propriedades, a operação GetInvoiceSchema será chamada para obter a lista com base no parâmetro typeId.
Ao implementar o esquema dinâmico no conector personalizado, você pode esclarecer ao criador quais parâmetros precisam ser usados para a ação.