Utilizar um acionador de consultas personalizado

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 Power Automate assinatura.
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. Entre https://services.odata.org/TripPinRESTierService na barra de endereço do seu navegador. 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:

Em Power Automate, selecione a guia Conectores personalizados de > dados .
No painel Conectores personalizados , selecione Novo conector personalizado e, em seguida, selecione Criar a partir do espaço em branco.
Na caixa de diálogo Criar um conector personalizado, digite o nome do conector personalizado (neste exemplo, você pode usar o Teste de Sondagem) e selecione Continuar.
Na página Geral , especifique uma descrição e um host. 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 gatilho e preencha a descrição do gatilho. 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 gatilho	"Consulta"

A propriedade Visibility para operações e parâmetros em um fluxo tem as seguintes opções:

nenhum: exibido normalmente no fluxo
Avançado: oculto sob um menu adicional
interna: oculta do utilizador
Importante: Sempre mostrado ao utilizador primeiro

A área Solicitação exibe informações com base na solicitação HTTP para a ação. Escolha Importar da amostra.
No painel Importar de exemplo , você definirá a solicitação para o gatilho de sondagem. Para o verbo, selecione GET. A partir dos metadados recebidos quando criou dinamicamente as URLs necessárias para o serviço, copie o endereço URL nos metadados para URL no painel de exemplo Importar de. Após o 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 usar o número real de seus metadados em vez do número <de> serviço na URL.

Neste exemplo de URL, você está a criar uma solicitação para uma pessoa individual e {Person} é uma variável de tempo de execução 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 $filter=TripId gt 0 expressão obtém as novas viagens devolvendo os TripIds de quaisquer viagens que sejam maiores do que os TripIds pesquisados anteriormente. O número 0 usado aqui será atualizado automaticamente sempre que ocorrer um gatilho de sondagem.

Além disso, a $orderby=TripId desc expressão indica que a ordem dos dados é retornada como o TripId em 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 de solicitação, selecione o parâmetro de consulta $filter e escolha Editar para abrir a caixa de diálogo Parâmetro .
Na caixa de diálogo Parâmetro para $filter, defina a seleção 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, consulte a extensão x-ms-visibility OpenAPI .

Selecione Voltar para retornar à área de solicitação.
Na área de solicitação, selecione o parâmetro de consulta $orderby e escolha Editar para abrir a caixa de diálogo Parâmetro .
Na caixa de diálogo Parâmetro para $orderby, defina a opção É necessário? seleção para Sim e a seleção Visibilidade para interno. Mais uma vez, estas definições impedem o utilizador de fazer alterações ao parâmetro.

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

Selecione Voltar para voltar à área anterior.
A área Resposta exibe informações com base na resposta HTTP para a ação. Selecione Adicionar resposta padrão.

Defina a resposta para o gatilho de sondagem 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 usar o número real de seus metadados em vez do número <de> serviço na URL.

Na área Configuração do gatilho , selecione o parâmetro usado para monitorar a alteração de estado do TripPin. Neste exemplo, o parâmetro a ser inserido é $filter.

Neste exemplo, use a seguinte expressão no valor Specify para passar para o 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 você está a usar aqui, quando TripId for maior do que o valor retornado pelo restante da expressão, o gatilho será executado. Se TripId não for maior que o valor retornado pelo restante da expressão, nenhum gatilho ocorrerá.

Na coleção Select que contém a seleção de dados de gatilho, 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 Iniciar 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, digite Gatilhos quando uma nova viagem for adicionada.

Selecione o item na lista para o utilizar como acionador.
Na caixa Fluxo de pessoas , digite russellwhyte para a pessoa cujas viagens você examinará e selecione + Nova etapa.
Na caixa de diálogo Escolha uma ação , selecione a guia Interno e, em seguida, selecione Data e Hora .
Em Data Hora, selecione Hora atual.
Selecione Salvar para salvar o novo fluxo.

Verificar e resolver problemas

Para verificar se tudo está configurado corretamente, escolha Meus fluxos e, em seguida, escolha os Gatilhos quando uma nova viagem for adicionada -> Fluxo de tempo atual para visualizar o histórico de execução. 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.

Em Postman, selecione o + ícone ao lado da guia Barra Inicial.
No pedido sem título, selecione POST na caixa pendente à esquerda e, em seguida, introduza o seguinte endereço na caixa Introduzir URL do pedido:
```
https://services.odata.org/TripPinRESTierService/(S(<Service number))/People('russellwhyte')/Trips
```
Nota

Certifique-se de usar o número real de seus metadados em vez do número <de> serviço na URL.
Na solicitação POST, selecione a guia Corpo e escolha bruto. Na lista pendente à direita de raw, 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 do TripPin.

A resposta deve retornar com um estatuto de 201 Created.

Agora, quando você abrir Meus fluxos, escolha os Gatilhos quando uma nova viagem for adicionada -> Fluxo de tempo atual, você verá no histórico de execução que um gatilho ocorreu.

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 fornecer comentários, vá para Enviar problemas ou obter ajuda com conectores e selecione seu tipo de feedback.

Last updated on 2025-03-24

Partilhar via