Gatilho de sondagem
Um gatilho de sondagem é uma implementação que chama regularmente seu serviço API REST e verifica se há novos dados. Depois que a plataforma determina que novos dados estão disponíveis, o gatilho dispara e passa os novos dados coletados a um fluxo da nuvem ou a um fluxo de trabalho de Aplicativos Lógicos.
O diagrama a seguir mostra um fluxo de processo básico de como um gatilho de sondagem adquire novos dados.
Um gatilho de sondagem começa recuperando os dados e definindo um estado. Em seguida, ele verifica periodicamente se há atualizações solicitando todos os dados desde a última atualização de estado. Depois que os novos dados são recuperados, o novo estado é definido e o processo continua. A API precisa ser capaz de retornar os dados de forma incremental, com base em um valor de parâmetro. O Power Automate ou os Aplicativos Lógicos do Azure mantêm o estado para que a API não tenha requisitos especiais de gerenciamento de estado.
Diferente de um gatilho de webhook, um gatilho de sondagem não tem requisitos de configuração ou de subdivisão, e o processamento pode ser interrompido a qualquer momento. A simplicidade dos requisitos é uma vantagem importante do gatilho de sondagem.
Requisitos de API
Um gatilho de sondagem requer que uma API tenha um método de recuperação de dados que possa filtrar os dados usando um parâmetro de cadeia de consulta. Também deve haver uma forma de extrair o próximo valor do parâmetro dos dados retornados. A implementação pode ser fornecida por um método de ação dedicado ou existente.
Por exemplo, considere uma implementação de loja online em que os pedidos têm números de pedidos cada vez maiores. A API da loja pode incluir um método chamado ListOrders que retorna pedidos criados na loja.
ListOrders retorna os pedidos classificados por número do pedido em ordem decrescente. Como resultado, o número do ordem mais alto pertence ao primeiro pedido na lista.
ListOrders aceita um parâmetro de cadeia de consulta para recuperar os pedidos em que o número do pedido é maior do que o valor do parâmetro.
Essas duas qualidades permitem que a ação seja usada como um gatilho de sondagem. A plataforma pode extrair o número do pedido mais alto dos dados retornados e passá-lo como um parâmetro para a próxima solicitação. Efetivamente, o método "selecionará todos os pedidos que foram criados desde o último".
Implementação
Um gatilho de sondagem é criado usando um assistente no Power Automate. O processo inclui as seguintes etapas:
Defina a solicitação HTTP que será usada para recuperar os dados.
A cadeia de consulta da solicitação inclui o parâmetro fromWidget, que habilita a pré-geração da definição de parâmetro. Esse parâmetro garante que os dados retornados sejam incrementais, que ele "retornará todos os widgets que foram criados desde aquele especificado pelo parâmetro".
Altere a visibilidade do parâmetro para Interna, impedindo que os usuários façam alterações neste parâmetro, que é usado apenas internamente pelo conector.
Defina os dados retornados pelo serviço. Esses dados devem incluir a propriedade a ser usada como valor para fromWidget nas solicitações consecutivas.
Neste exemplo, a propriedade é chamada ID.
Conclua a configuração do gatilho. Selecione o parâmetro de consulta, defina um valor ou uma expressão que retorne um valor e selecione uma coleção que contenha os dados do gatilho.
Este exemplo inclui os seguintes parâmetros:
fromWidget é selecionado como o parâmetro de consulta, que receberá o valor extraído dos resultados do laboratório.
A expressão @{triggerBody().widgets[0].id} extrai a ID de widget mais alta atual. Como a coleção retornada é classificada por valor de ID decrescente, extrair o valor do primeiro elemento ajuda a garantir que ela seja a ID atual mais alta.
A expressão @triggerBody().widgets define a coleção de dados.
Os parâmetros precisam ser extraídos e processados, e essa transformação só pode ser implementada usando uma política de conector. Consequentemente, a configuração do gatilho de sondagem é armazenada como um modelo de política separado da definição do conector OpenAPI. Uma implicação é que não é possível editar manualmente todas as configurações do gatilho de sondagem no Swagger Editor.
Uma limitação que você precisa saber é que o corpo do gatilho não pode ser uma matriz. Por exemplo, considere um método chamado ListOrders que retorna os seguintes dados:
[
{"value" : 42.00, "id" : "2", ... },
{"value" : 10.00, "id" : "1", ... }
]
O corpo do gatilho não será processado, e o gatilho gerará um erro no fluxo do Power Automate ou no fluxo de trabalho dos Aplicativos Lógicos no momento da execução.
Em vez disso, o método precisa retornar uma propriedade que contenha a matriz de registros. Por exemplo:
{
"orders": [
{ "value" : 42.00, "id" : "2", ... },
{ "value" : 10.00, "id" : "1", ... }
]
}
Essa estrutura de dados pode ser usada como parte da implementação do gatilho de sondagem.
Processamento em lotes
Semelhante ao gatilho do webhook, o gatilho de sondagem é definido pela extensão x-ms-trigger para OpenAPI. O valor definido por um gatilho de sondagem é um lote, indicando que o método retornará uma matriz em vez de um objeto individual, como ocorre em uma resposta do webhook.
/trigger/ListInvoices:
post:
x-ms-trigger: batch
Esse processo ocorre porque é possível ter vários registros que são retornados por uma única chamada para o serviço. Quando um gatilho de sondagem é usado no Power Automate ou nos Aplicativos Lógicos, a configuração de Dividir Em do gatilho permite configurar o modo de processamento.
A divisão da matriz de entrada nas várias implementações paralelas é feita por motivos de desempenho. Cada instância do fluxo da nuvem neste cenário receberá um único objeto. Se a opção Dividir Em não estiver definida, uma única instância do fluxo da nuvem receberá uma matriz de valores.
Os gatilhos de sondagem são mais fáceis de definir que os gatilhos de webhook. No entanto, eles são menos granulares e geralmente não têm um bom desempenho. A decisão de criar e usar um tipo de gatilho ou outro depende dos recursos, da estrutura e da funcionalidade da API de serviço.