Utilizar um acionador de consultas personalizado

Artigo
03/22/2024

Na essência, um acionador de consultas é um evento que faz, periodicamente, uma chamada para o seu serviço à procura de dados novos. Os acionadores de consultas diferem dos webhooks no sentido em que estes iniciam um evento para determinar se estão disponíveis dados novos, ao passo que os segundos respondem a emissões de dados novos por parte do serviço. Quando o fluxo determina que há dados novos, pode realizar ações com os mesmos. Este tutorial demonstra como utilizar um acionador de consultas para obter dados novos proativamente.

Pré-requisitos

Uma subscrição do Power Automate.
Experiência básica na construção de fluxos e conectores personalizados.

Saiba como um acionador de consultas adquire novos dados

Os acionadores de consultas começam por definir um estado e, depois, verificam periodicamente a existência de atualizações ao longo de um intervalo. Em seguida, pede os dados novos desde a última atualização de estado. Além disso, também mantêm o contexto do estado entre os pedidos.

O exemplo seguinte mostra uma descrição geral de como os acionadores de consultas adquirem dados novos.

Como os acionadores de consultas adquirem dados

O runtime do fluxo invoca uma chamada inicial no acionador para a API no conector.
O conector chama, então, o serviço de back-end.
Este, por sua vez, devolve todos os dados atuais ao conector.
O conector devolve uma mensagem 202 Aceite, um intervalo de repetição e um cabeçalho de localização que inclui o estado atual. O intervalo de repetição está em segundos. Esta primeira chamada é sempre utilizada para estabelecer o estado preliminar dos dados.
Depois de expirado o intervalo de repetição, o runtime do fluxo faz outra chamada para o conector com o cabeçalho de localização e o estado atual, que, neste exemplo, é igual a 1.
Uma vez que este estado é agora igual a 1, o conector sabe qual é a API certa a chamar e que fará a filtragem adequada para que seja devolvido o conjunto de dados correto. No exemplo, o conector traduz para uma consulta filtrada que diz que a data de criação é maior do que um determinado carimbo de data/hora.
Neste exemplo, não há dados novos desde a data de criação, pelo que é devolvido ao conector um conjunto de valores vazio.
Em seguida, o conector devolve uma mensagem 202 Aceite, um intervalo de repetição e um cabeçalho de localização, no qual o estado não sofreu alterações.
Quando o intervalo de repetição expirar novamente, o runtime do fluxo faz outra chamada para o conector com o mesmo cabeçalho de localização e o mesmo estado.
Mais uma vez, o conector realiza a filtragem adequada com a data de criação.
Agora, estão disponíveis dados novos desde a data de criação, pelo que o back-end devolve os valores de todos esses dados ao conector.
O conector, por sua vez, devolve uma mensagem 200 OK, um intervalo de repetição, a localização com um valor de estado novo e uma matriz de valores que contêm todos os dados novos que ficaram disponíveis após a data de criação. Nesta fase, o fluxo tem início.

Criar acionadores de consultas a partir da IU

Esta secção demonstra como criar um acionador de consultas na IU do Power Automate. Neste procedimento, vai utilizar o serviço TripPin de exemplo como ponto de partida. O serviço TripPin é uma API REST muito simples que contém uma lista de pessoas e as viagens que fizeram.

Para utilizar este serviço, tem primeiro de criar dinamicamente os URLs necessários para o mesmo. Introduza https://services.odata.org/TripPinRESTierService na barra de endereço do browser. São devolvidos os metadados necessários para a demonstração. Copie e guarde os metadados num ficheiro, para utilização posterior.

Para configurar o serviço TripPin e criar o acionador de consultas:

No Power Automate, selecione o separador Dados > Conectores personalizados.
No painel Conectores personalizados, selecione Novo conector personalizado e Criar do zero.
Na caixa de diálogo Criar um conector personalizado, introduza o nome do conector personalizado (neste exemplo, pode utilizar Teste de Consulta) e selecione Continuar.
Na página Geral, especifique uma descrição e um anfitrião. Neste exemplo, vai utilizar o URL services.odata.org que foi devolvido nos metadados de TripPin como o anfitrião.

Parâmetro Value

Descrição "O TripPin é um site de viagens de exemplo".

Anfitrião "services.odata.org"
Na página Segurança, escolha Sem autenticação como o tipo de autenticação.

Parâmetro	Value
Descrição	"O TripPin é um site de viagens de exemplo".
Anfitrião	"services.odata.org"

Na página definição, escolha + novo acionador e preencha a descrição do acionador. Neste exemplo, vai criar um acionador que é acionado quando é adicionada uma viagem nova ao itinerário de uma pessoa.

Criar um acionador novo

Parâmetro	Value
Resumo	"É acionado quando é adicionada uma viagem nova"
Descrição	"É acionado quando é adicionada uma viagem nova"
ID da operação	"OnNewTrip"
Visibilidade	"nenhum" (consulte a lista de verificação para obter mais informações)
Tipo de acionador	"Consulta"

A propriedade Visibilidade para operações e parâmetros num fluxo tem as seguintes opções:

nenhum: exibido normalmente no fluxo
avançada: ocultada num menu adicional
interna: ocultada do utilizador
importante: sempre mostrada primeiro ao utilizador

A área de Pedido apresenta informações com base no pedido HTTP para a ação. Selecione Importar a partir de exemplo.
No painel Importar a partir de exemplo, vai definir o pedido para o acionador de consultas. No verbo, selecione GET. Nos metadados que recebeu quando criou dinamicamente os URLs necessários para o serviço, copie o endereço do URL nos metadados para URL no painel Importar a partir de exemplo. A seguir ao endereço, adicione /People('{Person}')/Trips?$filter=TripId gt 0&$orderby=TripId desc. Por exemplo:
```
https://services.odata.org/TripPinRESTierService/(S(<service number>))/People('{Person}')/Trips?$filter=TripId gt 0&$orderby=TripId desc
```
Nota

Certifique-se de que utiliza o número real dos metadados em vez de <service number> no URL.

No URL de exemplo, está a criar um pedido para uma pessoa individual e {Person} é uma variável de runtime que um utilizador pode especificar no fluxo. Em seguida, vai especificar que pretende obter as viagens relativas à pessoa específica que o utilizador introduzir.

Contudo, a sua ideia não é obter todas as viagens. Só quer aquelas que sejam novas desde a última vez que as viagens foram consultadas. A expressão $filter=TripId gt 0 obtém as viagens novas ao devolver os TripIds de todas as viagens que sejam maiores do que os TripIds consultados anteriormente. O número 0 utilizado aqui será atualizado automaticamente sempre que ocorrer um acionador de consultas.

Além disso, a expressão $orderby=TripId desc indica que a ordem dos dados é devolvida como o TripId por ordem decrescente. A devolução por ordem decrescente é exigida pelo acionador. Isto quer dizer que os resultados que o serviço de back-end devolve têm de ser ordenados por ordem inversa no parâmetro do acionador, de modo a que o primeiro valor devolvido na matriz de dados seja o parâmetro mais recente (como o TripId neste exemplo).

Selecione o botão Importar para importar os dados de exemplo. A área do pedido mostra agora o verbo, o URL, o caminho e os parâmetros da consulta.
Na área do pedido, selecione o parâmetro de consulta $filter e escolha Editar para mostrar a caixa de diálogo Parâmetro.
Na caixa de diálogo Parâmetro de $filter, defina a seleção de Visibilidade como interna. Este parâmetro só é utilizado internamente pelo conector, o que impede o utilizador de fazer alterações. Para obter mais informações sobre as definições de visibilidade, veja a extensão de OpenAPI x-ms-visibility.

Selecione Voltar para regressar à área do pedido.
Na área do pedido, selecione o parâmetro de consulta $orderby e escolha Editar para mostrar a caixa de diálogo Parâmetro.
Na caixa de diálogo Parâmetro de $orderby, defina a seleção de É obrigatório? como Sim e a seleção de Visibilidade como interna. Mais uma vez, estas definições impedem o utilizador de fazer alterações ao parâmetro.

Além disso, introduza TripId desc como o valor na caixa Valor predefinido. Estas definições garantem que os resultados são dados em ordem inversa.

Selecione Voltar para regressar à área anterior.
A área de Resposta apresenta informações com base na resposta HTTP para a ação. Selecione Adicionar resposta predefinida.

Defina a resposta para o acionador de consultas e escolha Importar. Utilize o exemplo fornecido abaixo para o corpo da resposta, o que cria automaticamente um esquema para a resposta.

Adicionar o corpo da resposta da consulta


{
    "@odata.context":"https://services.odata.org/TripPinRESTierService/(S(<service number>))/$metadata#Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Trip)",
    "value":[
        {
            "TripId":2,
            "ShareId":"9ce142c3-5fd6-4a71-848e-220ebf1e9f3",
            "Name":"Honeymoon",
            "Budget":2650,
            "Description":"Happy honeymoon trip",
            "Tags":[
                "Travel",
                "honeymoon"
            ],
            "StartsAt":"2014-02-01T00:00:00Z",
            "EndsAt":"2014-02-04T00:00:00Z"
        },
        {
            "TripId":1,
            "ShareId":"f94e9116-8bdd-4dac-ab61-08438d0d9a71",
            "Name":"Trip in Beijing",
            "Budget":2000,
            "Description":"Trip from Shanghai to Beijing",
            "Tags":[
                "Travel",
                "Beijing"
            ],
            "StartsAt":"2014-02-01T00:00:00Z",
            "EndsAt":"2014-02-04T00:00:00Z"
        }
    ]
}

Nota

Certifique-se de que utiliza o número real dos metadados em vez de <service number> no URL.

Na área Configuração do acionador, selecione o parâmetro que é utilizado para monitorizar a alteração de estado de TripPin. Neste exemplo, o parâmetro a introduzir é $filter.

Neste exemplo, utilize a expressão seguinte em Especificar o valor a transmitir ao parâmetro de consulta selecionado:

TripId gt @{triggerBody().value[0].TripId}

Esta expressão é utilizada para obter os resultados mais recentes sempre que o acionador é executado. Na expressão que está a utilizar aqui, o acionador será executado quando TripId for maior do que o valor devolvido pelo resto da expressão. Se TripId não for maior do que o valor devolvido pelo resto da expressão, nenhum acionador é executado.

Na seleção Selecionar a coleção que contém os dados do acionador, escolha @triggerBody().value. Esta é a matriz que contém os dados do acionador que o serviço de back-end devolve.
Na parte superior do assistente, selecione Criar conector.

Utilizar o acionador de consultas

Agora que já tem tudo configurado, pode utilizar o acionador de consultas num fluxo. Nesta secção, vai criar um fluxo que vai consultar o serviço de back-end relativamente a alterações sempre que é registada uma viagem nova para uma pessoa específica.

Em flow.microsoft.com, no lado esquerdo da página, escolha Criar.
Em Começar com aplicação em branco, escolha Fluxo instantâneo.
Na caixa de diálogo Criar um fluxo instantâneo, selecione o botão Ignorar.
Na caixa de pesquisa, introduza É acionado quando é adicionada uma viagem nova.

Selecione o item na lista para o utilizar como acionador.
Na caixa do fluxo Pessoa, introduza russellwhyte na pessoa cujas viagens pretende examinar e selecione + Novo passo.
Na caixa de diálogo Escolher uma ação, selecione o separador Incorporada e, em seguida, selecione Data Hora.
Em Data Hora, selecione Hora atual.
Selecione Guardar para guardar o fluxo novo.

Verificar e resolver problemas

Para verificar que tudo está configurado corretamente, escolha Os meus fluxos e o fluxo É acionado quando é adicionada uma viagem nova -> Hora atual para ver o histórico de execuções. Uma vez que o fluxo não foi executado, não deve aparecer nada atualmente no histórico.

Para testar o fluxo, tem de abrir a aplicação Postman para adicionar dados novos a TripPin.

No Postman, selecione o ícone +, junto ao separador Launchpad.
No pedido sem nome, selecione POST na caixa pendente do lado esquerdo e introduza o endereço seguinte na caixa Introduzir URL do pedido:
```
https://services.odata.org/TripPinRESTierService/(S(<Service number))/People('russellwhyte')/Trips
```
Nota

Certifique-se de que utiliza o número real dos metadados em vez de <service number> no URL.
No pedido POST, selecione o separador Corpo e escolha em bruto. No menu pendente à direita de em bruto, escolha JSON.

Introduza o texto seguinte na caixa de texto:

{
     "TripId": 190,
     "ShareId": "9d9b2fa0-efbf-490e-a5e3-bac8f7d47354",
     "Name": "Trip in US",
     "Budget": 5000,
     "Description": "Trip from San Francisco to New York City",
     "Tags": [
         "business",
         "New York meeting"
     ],
     "StartsAt": "2014-01-01T00:00:00Z",
     "EndsAt": "2014-01-04T00:00:00Z"
}

Selecione Enviar para enviar a mensagem POST para o site TripPin.

A resposta deverá ser devolvida com o estado 201 Created.

Agora, quando abre Os meus fluxos e escolhe o fluxo É acionado quando é adicionada uma viagem nova -> Hora atual, verá no histórico de execuções que ocorreu um acionador.

Ocorreu um acionador

Nota

Se executar outro pedido POST no Postman para a mesma pessoa, tem de alterar o valor de TripId no corpo do JSON. Caso contrário, ocorre o erro 409 Conflito.

Se estiver tudo bem configurado, recebe agora notificações no Microsoft Power Automate sempre que for adicionada uma viagem nova a TripPin.

Consulte também

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para enviar comentários, aceda a Submeter problemas ou obter ajuda com conectores e selecione o tipo de comentários.

Partilhar via