Usar um gatilho de sondagem para o Microsoft Power Automate

  • Artigo

Um gatilho de sondagem é basicamente um evento que faz uma chamada periodicamente para seu serviço para procurar novos dados. Os gatilhos de sondagem são diferentes dos webhooks, pois o gatilho de sondagem inicia um evento para determinar se novos dados estão disponíveis, enquanto os webhooks respondem a um push de novos dados do serviço. Depois que o fluxo determinar que novos dados estão disponíveis, você poderá executar uma ação com esses dados. Este tutorial demonstra como usar um gatilho de sondagem para recuperar novos dados de forma proativa.

Pré-requisitos

Como os gatilhos de sondagem funcionam

O gatilho de sondagem começa definindo um estado e verifica periodicamente se há atualizações em um intervalo de tempo. Em seguida, o gatilho solicita todos os novos dados desde a última atualização de estado. Além disso, o gatilho também mantém o contexto do estado entre as solicitações.

O exemplo a seguir fornece uma visão geral básica de como um gatilho de sondagem obtém novos dados.

Como os gatilhos de sondagem obtêm dados

  1. O runtime do fluxo invoca uma chamada inicial no gatilho para a API no conector.

  2. O conector chama então o serviço de back-end.

  3. O serviço de back-end retorna todos os dados atuais para o conector.

  4. O conector, por sua vez, retorna a mensagem "202 Aceito", um intervalo de repetição e um cabeçalho de local que inclui o estado atual. O intervalo de repetição é em segundos. A primeira chamada é sempre usada para estabelecer o estado preliminar dos dados.

  5. Depois que o intervalo de repetição atingir o tempo limite, o runtime de fluxo fará outra chamada para o conector usando o cabeçalho de local e o estado atual, que neste exemplo é igual a 1.

  6. Como estado é igual a 1, o conector agora sabe como chamar a API adequada que fará a filtragem adequada para que o conjunto de dados correto seja retornado. Neste exemplo, o conector converte-o em uma consulta filtrada que indica que a data de criação é maior que um determinado carimbo de data/hora.

  7. Neste exemplo, não há nenhum novo dado desde a data de criação, portanto, um conjunto vazio de valores é enviado de volta para o conector.

  8. O conector retorna a mensagem "202 Aceito", um intervalo de repetição e um cabeçalho de local no qual o estado não mudou.

  9. Depois que o intervalo de repetição atingir o tempo limite novamente, o runtime de fluxo fará outra chamada para o conector usando o mesmo cabeçalho e estado de local.

  10. Novamente, o conector faz a filtragem adequada usando a data de criação.

  11. Desta vez, novos dados são disponibilizados desde a data de criação, portanto, o back-end retorna os valores de todos os novos dados ao conector.

  12. Em seguida, o conector retorna uma mensagem "200 OK", um intervalo de repetição, o local com um novo valor de estado e uma matriz de valores que contém todos os novos dados que foram disponibilizados após a data de criação. Neste ponto, o fluxo será iniciado.

Criar gatilhos de sondagem por meio da interface do usuário

Esta seção demonstra como criar um gatilho de sondagem na interface do usuário do Power Automate. Neste procedimento, você usará o exemplo de serviço TripPin como um ponto de partida. O serviço TripPin é uma API REST muito simples que contém uma lista de pessoas e suas respectivas viagens.

Para usar o serviço TripPin, primeiramente você deverá criar dinamicamente as URLs necessárias para o serviço. Insira https://services.odata.org/TripPinRESTierService na barra de endereços do navegador. Isso retornará os metadados necessários para essa demonstração. Copie e salve os metadados em um arquivo para usá-los posteriormente.

Para configurar o serviço TripPin e criar o gatilho de sondagem:

  1. No Power Automate, selecione a guia Dados > Conectores personalizados.

  2. No painel Conectores personalizados, selecione Novo conector personalizado e Criar do zero.

  3. Na caixa de diálogo "Criar um conector personalizado", insira o nome do conector personalizado (neste exemplo, você pode usar Teste de sondagem) e selecione Continuar.

  4. Na página Geral, especifique uma descrição e um host. Neste exemplo, você usará a URL services.odata.org que foi retornada nos metadados do TripPin como o host.

    Parâmetro Valor
    Descrição "TripPin é um exemplo de site de viagens."
    Host "services.odata.org"

    Adicionando uma descrição e um host

  5. Na página Segurança, escolha Sem autenticação como o tipo de autenticação.

    Autenticação da sondagem

  6. Na página Definição, escolha + Novo gatilho e preencha a descrição do seu gatilho. Neste exemplo, você criará um gatilho que será acionado quando uma nova viagem for adicionada ao itinerário de uma pessoa.

    Criar um gatilho

    Parâmetro Valor
    Resumo "Dispara quando uma nova viagem é adicionada"
    Descrição "Dispara quando uma nova viagem é adicionada"
    ID da Operação "OnNewTrip"
    Visibilidade "nenhum" (consulte para obter mais informações)
    Tipo de gatilho "Sondagem”

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

    • nenhum: exibido normalmente no fluxo
    • avançado: oculto em um menu adicional
    • interno: ocultado do usuário
    • importante: sempre exibido para o usuário primeiro

  7. A área Solicitação exibe informações com base na solicitação HTTP para a ação. Escolha Importar da amostra.

    Página de definição - importar da amostra

  8. No painel Importar da amostra, você definirá a solicitação para o gatilho de sondagem. Para o verbo, selecione GET. Por meio dos metadados recebidos quando você criou dinamicamente as URLs necessárias para o serviço, copie o endereço da URL dos metadados em URL no painel Importar da amostra. 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

    Observação

    Certifique-se de usar o número real de seus metadados em vez do <número do serviço> na URL.

    Neste exemplo de URL, você está criando uma solicitação para um indivíduo e {Person} é uma variável de runtime que um usuário pode especificar no fluxo. Em seguida, você está especificando que deseja obter as viagens para a pessoa específica inserida pelo usuário.

    Mas, você não quer obter todas as viagens, somente as viagens novas desde a última vez em que foram sondadas. A expressão $filter=TripId gt 0 obtém as novas viagens, retornando os TripIds de qualquer viagem que seja maior do que os TripIds sondados anteriormente. O número 0 usado aqui será atualizado automaticamente toda vez que ocorrer um gatilho de sondagem.

    Além disso, a expressão $orderby=TripId desc indica que a ordem dos dados é retornada como o TripId em ordem decrescente. O retorno em ordem decrescente é exigido pelo gatilho. Ou seja, os resultados retornados pelo serviço de back-end devem ser ordenada na ordem inversa no parâmetro do gatilho para que o parâmetro mais recente (como o TripId neste exemplo) seja o primeiro valor retornado na matriz de dados.

    Importar do menu de exemplo

    Selecione o botão Importar para importar os dados de exemplo. A área de solicitação agora exibe o verbo, a URL, o caminho e os parâmetros de consulta.

  9. Na área de solicitação, selecione o parâmetro de consulta $filter e escolha Editar para abrir a caixa de diálogo Parâmetro.

    Editar o parâmetro de filtro

  10. Na caixa de diálogo Parâmetro, em $filter, defina a seleção Visibilidade como interna. Esse parâmetro é usado somente internamente pelo conector, o que impede que o usuário faça alterações. Para obter mais informações sobre as configurações de visibilidade, consulte a extensão x-ms-visibility de OpenAPI.

    Selecione Voltar para retornar à área de solicitação.

    Editar o parâmetro de filtro

  11. Na área de solicitação, selecione o parâmetro de consulta $orderby e escolha Editar para abrir a caixa de diálogo Parâmetro.

  12. Na caixa de diálogo Parâmetro, em $orderby, defina a seleção É necessário? como Sim e a seleção Visibilidade como interna. Novamente, essas configurações impedirão que o usuário faça alterações nesse parâmetro.

    Além disso, insira TripId desc como o valor na caixa Valor padrão. Essas configurações garantirão que os resultados sejam fornecidos na ordem inversa.

    Selecione Voltar para retornar à área anterior.

    Editando o parâmetro orderby

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

    Adicionar resposta de sondagem padrão

  14. Defina a resposta para o gatilho de sondagem e escolha Importar. Use o exemplo fornecido abaixo para o corpo da resposta, que criará automaticamente um esquema para a resposta.

    Adicionar o corpo da resposta de sondagem

    
{
    "@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"
        }
    ]
}

    Observação

    Certifique-se de usar o número real de seus metadados em vez do <número do serviço> na URL.

  15. 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 em Especificar valor a ser passado para o parâmetro de consulta selecionado:

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

    Essa expressão é usada para obter os resultados mais recentes sempre que o gatilho é executado. Na expressão sendo usada aqui, quando TripId for maior 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, não ocorrerá nenhum gatilho.

    Na seleção Selecionar coleção que contém dados de gatilho, escolha @triggerBody().value. Essa é a matriz que contém os dados de gatilho que são retornados pelo serviço de back-end.

    Configuração do gatilho de sondagem

  16. Na parte superior do assistente, selecione Criar conector.

Usar o gatilho de sondagem

Agora que tudo está configurado, você pode usar o gatilho de sondagem em um fluxo. Nesta seção, você criará um fluxo que sondará o serviço de back-end em busca de alterações sempre que uma nova viagem for registrada para uma pessoa específica.

  1. Em flow.microsoft.com, no lado esquerdo da página, escolha Criar.

  2. Em Iniciar em branco, escolha Fluxo instantâneo.

  3. Na caixa de diálogo Criar um fluxo instantâneo, selecione o botão Ignorar.

  4. Na caixa de pesquisa, insira Dispara quando uma nova viagem é adicionada.

    Captura de tela que mostra o texto de pesquisa na caixa de pesquisa.

    Escolha o item na lista para usá-lo como um gatilho.

  5. Na caixa de fluxo Pessoa, digite russellwhyte para a pessoa cujas viagens você analisará e selecione + Nova etapa.

    Captura de tela que mostra a caixa Pessoa e o botão Nova etapa.

  6. Na caixa de diálogo Escolha uma ação, selecione a guia Interno e selecione Data e Hora.

    Captura de tela que mostra a caixa de diálogo Escolher uma ação.

  7. Em Data e Hora, selecione Hora atual.

    Captura de tela que mostra o botão Hora atual.

  8. Selecione Salvar para salvar o novo fluxo.

Verificação e solução de problemas

Para verificar se tudo está configurado corretamente, escolha Meus fluxos e escolha o fluxo Dispara quando uma nova viagem é adicionada -> Hora atual para exibir o histórico de execuções. Como o fluxo ainda não foi executado, nada deve aparecer no histórico.

Para testar o fluxo, será necessário abrir o aplicativo Postman para adicionar novos dados ao TripPin.

  1. No Postman, selecione o ícone + próximo à guia Barra inicial.

  2. Na solicitação sem título, selecione POST, na caixa suspensa à esquerda, e insira o seguinte endereço na caixa Digite a URL da solicitação:

    https://services.odata.org/TripPinRESTierService/(S(<Service number))/People('russellwhyte')/Trips

    Observação

    Certifique-se de usar o número real de seus metadados em vez do <número do serviço> na URL.

  3. Abaixo da solicitação POST, selecione a guia Corpo e escolha raw. No menu suspenso à direita de raw, escolha JSON.

  4. Na caixa de texto, insira o seguinte:

    {
     "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"
}

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

    Enviar a mensagem POST

    A resposta deve ser retornada com um status 201 Created.

Agora, quando você abrir Meus fluxos e escolher o fluxo Dispara quando uma nova viagem é adicionada -> Hora atual, você verá no histórico de execuções que ocorreu um gatilho.

Um gatilho ocorreu

Observação

Se executar outra solicitação POST no Postman para a mesma pessoa, você deverá alterar o valor do TripId no corpo JSON. Caso contrário, ocorrerá um erro de Conflito 409.

Resumo

Se tudo estiver configurado corretamente, você receberá notificações no Microsoft Power Automate sempre que uma nova viagem for adicionada ao TripPin.

Próximas etapas

Enviar comentários

Agradecemos muito os comentários sobre problemas com nossa plataforma de conectores ou novas ideias de recursos. Para fornecer comentários, acesseEnviar problemas ou obter ajuda com conectores e selecione o tipo de comentário.