Compartilhar via

Criar fluxos de trabalho que você pode chamar, disparar ou aninhar usando pontos de extremidade HTTPS nos Aplicativos Lógicos do Azure

  • Artigo

Aplica-se a: Aplicativos Lógicos do Azure (Consumo + Padrão)

Alguns cenários podem exigir que você crie um fluxo de trabalho de aplicativo lógico que possa receber solicitações de entrada de outros serviços ou fluxos de trabalho ou um fluxo de trabalho que você pode chamar usando uma URL. Para esta tarefa, você pode expor um ponto de extremidade HTTPS síncrono nativo em seu fluxo de trabalho ao usar qualquer um dos seguintes tipos de gatilho baseados em solicitação:

Este guia mostra como criar um ponto de extremidade que possa ser chamado para o fluxo de trabalho adicionando o gatilho Solicitação e, em seguida, chamar esse ponto de extremidade por meio de outro fluxo de trabalho. Todos os princípios se aplicam de maneira idêntica aos outros tipos de gatilho baseados em solicitação que podem receber solicitações de entrada.

Pré-requisitos

  • Uma conta e uma assinatura do Azure. Se você não tem uma assinatura, inscreva-se em uma conta gratuita do Azure.

  • Um fluxo de trabalho de aplicativo lógico em que você deseja usar o gatilho de Solicitação para criar o ponto de extremidade que pode ser chamado. Você pode começar com um fluxo de trabalho em branco ou existente, em que pode substituir o gatilho atual. Este exemplo começa com um fluxo de trabalho em branco.

Criar um ponto de extremidade que pode ser chamado

Com base em se você tem um fluxo de trabalho de aplicativo lógico Standard ou de Consumo, siga as etapas correspondentes:

  1. No portal do Azure, abra o recurso de aplicativo lógico Standard e o fluxo de trabalho em branco no designer.

  2. Siga estas etapas gerais para adicionar o gatilho Solicitação chamado Quando uma solicitação HTTP for recebida.

  3. Opcionalmente, na caixa Esquema JSON do Corpo da Solicitação, você pode inserir um esquema JSON que descreve o conteúdo os dados que você espera que o gatilho receba.

    O designer usa esse esquema para gerar tokens que representam saídas de gatilho. Você pode fazer referência facilmente a essas saídas em todo o fluxo de trabalho do aplicativo lógico. Saiba mais sobre tokens gerados de esquemas JSON.

    Para este exemplo, insira o seguinte esquema:

    {
   "type": "object",
   "properties": {
      "address": {
         "type": "object",
         "properties": {
            "streetNumber": {
               "type": "string"
            },
            "streetName": {
               "type": "string"
            },
            "town": {
               "type": "string"
            },
            "postalCode": {
               "type": "string"
            }
         }
      }
   }
}

    A captura de tela mostra o fluxo de trabalho Standard com o gatilho de Solicitação e o parâmetro Esquema JSON do Corpo da Solicitação com um exemplo de esquema.

    Ou, você pode gerar um esquema JSON fornecendo um conteúdo de exemplo:

    1. No gatilho de Solicitação, selecione Usar conteúdo de amostra para gerar o esquema.

    2. Na caixa Inserir ou colar um conteúdo JSON de exemplo, insira seu conteúdo de exemplo, por exemplo:

      {
   "address": {
      "streetNumber": "00000",
      "streetName": "AnyStreet",
      "town": "AnyTown",
      "postalCode": "11111-1111"
  }
}

    3. Quando estiver pronto, selecione Concluído.

      A caixa Esquema JSON do Corpo da Solicitação agora mostra o esquema gerado.

  4. Salve seu fluxo de trabalho.

    A caixa URL DE HTTP POST agora mostra a URL de retorno de chamada gerada que outros serviços podem usar para chamar e disparar seu fluxo de trabalho do aplicativo lógico. Essa URL inclui parâmetros de consulta que especificam uma chave SAS (Assinatura de Acesso Compartilhado), que é usada para autenticação.

    A captura de tela mostra o fluxo de trabalho Standard, o gatilho de Solicitação e o URL de retorno de chamada gerado para o ponto de extremidade.

  5. Para copiar a URL de retorno de chamada, você tem estas opções:

    • À direita da caixa URL DE HTTP POST, selecione Copiar URL (ícone de copiar arquivos).

    • Copie a URL de retorno de chamada da página visão geral do fluxo de trabalho.

      1. No menu do fluxo de trabalho, selecione Visão geral.

      2. Na página de visão geral, na URL do Fluxo de Trabalho, mova o ponteiro sobre a URL e selecione Copiar para área de transferência:

        A captura de tela mostra o fluxo de trabalho Standard e a página Visão geral com a URL do fluxo de trabalho.

  6. Para testar a URL de retorno de chamada e disparar o fluxo de trabalho, envie uma solicitação HTTP para a URL, incluindo o método que o gatilho de Solicitação espera, usando sua ferramenta de solicitação HTTP e suas instruções.

    Este exemplo usa o método POST com a URL copiada, que se parece com o seguinte exemplo:

    POST https://{logic-app-name}.azurewebsites.net:443/api/{workflow-name}/triggers/{trigger-name}/invoke?api-version=2022-05-01&sp=%2Ftriggers%2F{trigger-name}%2Frun&sv=1.0&sig={shared-access-signature}

Selecionar o método de solicitação esperado

Por padrão, o gatilho de Solicitação espera uma solicitação POST. No entanto, você pode especificar um método diferente que o chamador deve usar, mas apenas um único método.

  1. No gatilho de Solicitação, abra a lista Parâmetros avançados e selecione Método, o que adiciona essa propriedade ao gatilho.

  2. Na lista Método, selecione o método que o gatilho deve esperar. Ou, você pode especificar um método personalizado.

    Por exemplo, selecione o método GET para que você possa testar posteriormente sua URL de ponto de extremidade.

Passar parâmetros por meio da URL do ponto de extremidade

Quando você quiser aceitar valores de parâmetro por meio da URL do ponto de extremidade, terá estas opções:

  • Aceitar valores por meio de parâmetros GET ou parâmetros da URL.

    Esses valores são passados como pares nome-valor na URL do ponto de extremidade. Para essa opção, você precisa usar o método GET em seu gatilho de Solicitação. Em uma ação subsequente, você pode obter os valores de parâmetro como saídas do gatilho usando a função triggerOutputs() em uma expressão.

  • Aceitar valores por meio de um caminho relativo para parâmetros em seu gatilho de Solicitação.

    Esses valores são passados por meio de um caminho relativo na URL do ponto de extremidade. Você também precisa selecionar explicitamente o método esperado pelo gatilho. Em uma ação subsequente, você pode obter os valores de parâmetro como saídas do gatilho referenciando essas saídas diretamente.

Aceitar valores por meio de parâmetros GET

  1. No gatilho de Solicitação, abra a lista Parâmetros avançados, adicione a propriedade Método ao gatilho e selecione o método GET.

    Para obter mais informações, confira Selecionar o método de solicitação esperado.

  2. No designer, siga estas etapas gerais para adicionar a ação na qual você deseja usar o valor do parâmetro.

    Para este exemplo, selecione a ação denominada Resposta.

  3. Para criar a expressão triggerOutputs() que recupera o valor do parâmetro, siga estas etapas:

    1. Na ação Resposta, selecione dentro da propriedade Corpo para que as opções de conteúdo dinâmico (ícone de relâmpago) e editor de expressão (ícone de fórmula) apareçam. Selecione o ícone de fórmula para abrir o editor de expressões.

    2. Na caixa de expressão, insira a expressão a seguir, substituindo parameter-name pelo nome do parâmetro e selecione OK.

      triggerOutputs()['queries']['parameter-name']

      A captura de tela mostra o fluxo de trabalho Standard, a ação de Resposta e a expressão triggerOutputs().

      Na propriedade Corpo, a expressão é resolvida para o token triggerOutputs().

      A captura de tela mostra o fluxo de trabalho Standard com a expressão triggerOutputs() resolvida da ação de Resposta.

      Se você salvar o fluxo de trabalho, sair do designer e retornar a ele, o token mostrará o nome do parâmetro que você especificou, por exemplo:

      A captura de tela mostra o fluxo de trabalho Standard com a expressão resolvida da ação de Resposta para o nome do parâmetro.

      Na exibição de código, a propriedade Corpo é exibida na definição da ação da Resposta da seguinte maneira:

      "body": "@{triggerOutputs()['queries']['parameter-name']}",

      Por exemplo, suponha que você deseje passar um valor para um parâmetro chamado postalCode. A propriedade Corpo especifica a cadeia de caracteres, Postal Code: com um espaço à direita, seguido pela expressão correspondente:

      A captura de tela mostra o fluxo de trabalho Standard com a ação de Resposta e a expressão triggerOutputs() de exemplo.

Testar o ponto de extremidade chamável

  1. No gatilho de Solicitação, copie a URL do fluxo de trabalho e cole-a em outra janela do navegador. Na URL, adicione o nome e o valor do parâmetro à URL no formato a seguir e pressione Enter.

    ...invoke/{parameter-name}/{parameter-value}?api-version=2022-05-01...

    Por exemplo:

    https://mystandardlogicapp.azurewebsites.net/api/Stateful-Workflow/triggers/When_a_HTTP_request_is_received/invoke/address/12345?api-version=2022-05-01&sp=%2Ftriggers%2FWhen_a_HTTP_request_is_received%2Frun&sv=1.0&sig={shared-access-signature}

    O navegador retorna uma resposta com este texto: Postal Code: 123456

    A captura de tela mostra o navegador com a resposta do fluxo de trabalho Standard da solicitação para a URL de retorno de chamada.

Observação

Se você quiser incluir o hash ou símbolo de libra ( # ) no URI, use esta versão codificada: %25%23

Aceitar valores por meio de um caminho relativo

  1. No gatilho de Solicitação, abra a lista Parâmetros avançados e selecione Caminho relativo, o que adiciona essa propriedade ao gatilho.

    A captura de tela mostra o fluxo de trabalho Standard, o gatilho de Solicitação e a propriedade adicionada chamada Caminho relativo.

  2. Na propriedade Caminho relativo, especifique o caminho relativo para o parâmetro no esquema JSON que você deseja que a URL aceite, por exemplo, /address/{postalCode}.

    A captura de tela mostra o fluxo de trabalho Standard, o gatilho de Solicitação e o valor do parâmetro Caminho relativo.

  3. No gatilho de Solicitação, siga estas etapas gerais para adicionar a ação em que você deseja usar o valor do parâmetro.

    Para este exemplo, adicione a ação Resposta.

  4. Na propriedade Corpo da ação Resposta, inclua o token que representa o parâmetro especificado no caminho relativo do gatilho.

    Por exemplo, suponha que você deseje que a ação Resposta retorne Postal Code: {postalCode}.

    1. Na propriedade Corpo, insira Postal Code: com um espaço à direita. Mantenha o cursor na caixa de edição para que a lista de conteúdo dinâmico permaneça aberta.

    2. Na lista de conteúdo dinâmico, na seção Quando uma solicitação HTTP é recebida, selecione a saída do gatilho postalCode de parâmetros de caminho.

      A captura de tela mostra o fluxo de trabalho padrão, a ação de Resposta e a saída do gatilho especificada para incluir no corpo da resposta.

      A propriedade Corpo agora inclui o parâmetro selecionado:

      A captura de tela mostra o fluxo de trabalho padrão e o exemplo de corpo da resposta com parâmetro.

  5. Salve seu fluxo de trabalho.

    No gatilho de Solicitação, a URL de retorno de chamada é atualizada e agora inclui o caminho relativo, por exemplo:

    https://mystandardlogicapp.azurewebsites.net/api/Stateful-Workflow/triggers/When_a_HTTP_request_is_received/invoke/address/%7BpostalCode%7D?api-version=2022-05-01&sp=%2Ftriggers%2FWhen_a_HTTP_request_is_received%2Frun&sv=1.0&sig={shared-access-signature}

  6. Para testar o ponto de extremidade que pode ser chamado, copie a URL de retorno de chamada atualizada do gatilho de Solicitação, cole-a em outra janela do navegador, substitua %7BpostalCode%7D na URL por 123456 e pressione Enter.

    O navegador retorna uma resposta com este texto: Postal Code: 123456

    A captura de tela mostra o navegador com a resposta do fluxo de trabalho Standard da solicitação para a URL de retorno de chamada.

Observação

Se você quiser incluir o hash ou símbolo de libra ( # ) no URI, use esta versão codificada: %25%23

Chamar fluxo de trabalho por meio da URL do ponto de extremidade

Depois de criar o ponto de extremidade, você pode disparar o fluxo de trabalho enviando uma solicitação HTTPS para a URL completa do ponto de extremidade. Os fluxos de trabalho dos Aplicativos Lógicos do Azure têm suporte interno para pontos de extremidade de acesso direto.

Tokens gerados do esquema

Quando você fornece um esquema JSON no gatilho Solicitação, o designer de fluxo de trabalho gera tokens para as propriedades no esquema. Assim, você pode usar esses tokens para transmitir dados por meio do fluxo de trabalho.

Por exemplo, se você adicionar outras propriedades, como "suite", ao seu esquema JSON, os tokens para essas propriedades estarão disponíveis para uso nas etapas posteriores para seu fluxo de trabalho. Veja o esquema JSON completo:

{
   "type": "object",
   "properties": {
      "address": {
         "type": "object",
         "properties": {
            "streetNumber": {
               "type": "string"
            },
            "streetName": {
               "type": "string"
            },
            "suite": {
               "type": "string"
            },
            "town": {
               "type": "string"
            },
            "postalCode": {
               "type": "string"
            }
         }
      }
   }
}

Chamar outros fluxos de trabalho

Você pode chamar outros fluxos de trabalho que podem receber solicitações aninhando-as dentro do fluxo de trabalho atual. Para chamar esses fluxos de trabalho, siga estas etapas:

  1. No designer, siga estas etapas gerais para adicionar a ação Operações de Fluxo de Trabalho chamada Invocar um fluxo de trabalho neste aplicativo de fluxo de trabalho.

    A lista Nome do Fluxo de Trabalho mostra os fluxos de trabalho que você pode selecionar.

  2. Na lista Nome do Fluxo de Trabalho, selecione o fluxo de trabalho que você deseja chamar, por exemplo:

    A captura de tela mostra o fluxo de trabalho Standard, a ação denominada Invocar um fluxo de trabalho neste aplicativo de fluxo de trabalho, a lista Nome do Fluxo de Trabalho aberta e os fluxos de trabalho disponíveis para chamar.

Referenciar conteúdo por meio de uma solicitação de entrada

Se o tipo de conteúdo da solicitação de entrada for application/json, você poderá fazer referência às propriedades na solicitação de entrada. Caso contrário, o conteúdo será tratado como uma única unidade binária que você pode passar para outras APIs. Para fazer referência a esse conteúdo dentro do fluxo de trabalho do aplicativo lógico, primeiro você precisa converter esse conteúdo.

Por exemplo, se você estiver passando o conteúdo que tem o tipo application/xml, poderá usar a expressão @xpath() para executar uma extração de XPath ou usar a expressão @json() para converter XML em JSON. Saiba mais sobre trabalhar com tipos de conteúdo com suporte.

Para obter a saída de uma solicitação de entrada, você pode usar a expressão @triggerOutputs. Por exemplo, suponha que você tem uma saída semelhante a este exemplo:

{
   "headers": {
      "content-type" : "application/json"
   },
   "body": {
      "myProperty" : "property value"
   }
}

Para acessar especificamente a propriedade body, você pode usar a expressão @triggerBody() como um atalho.

Responder às solicitações

Às vezes, você deseja responder a certas solicitações que disparam o fluxo de trabalho retornando conteúdo ao chamador. Para construir o código de status, o cabeçalho e o corpo da resposta, use a ação Resposta. Essa ação pode aparecer em qualquer lugar no fluxo de trabalho, não apenas no fim dele. Se o fluxo de trabalho não incluir uma ação Resposta, o ponto de extremidade HTTP responderá imediatamente com um status 202 Aceito.

Para que o chamador original receba a resposta com êxito, todas as etapas necessárias para a resposta devem ser concluídas dentro do limite de tempo da solicitação, a menos que o fluxo de trabalho disparado seja chamado como um fluxo de trabalho aninhado. Se não houver resposta dentro desse limite, a solicitação de entrada atingirá o tempo limite e receberá a resposta 408 Tempo limite de cliente.

Em fluxos de trabalho aninhados, o fluxo de trabalho pai continuará a aguardar uma resposta até a conclusão de todas as etapas, independentemente de quanto tempo for necessário.

Construir a resposta

No corpo da resposta, você pode incluir vários cabeçalhos e qualquer tipo de conteúdo. Por exemplo, o cabeçalho da resposta a seguir especifica que o tipo de conteúdo da resposta é application/json e que o corpo contém valores para as propriedades town e postalCode, com base no esquema JSON descrito anteriormente nesse tópico para o gatilho de Solicitação.

A captura de tela mostra a ação Resposta e o tipo de conteúdo da resposta.

As respostas têm estas propriedades:

Propriedade (exibição) Propriedade (JSON) Descrição
Código de status statusCode O código de status HTTPS a ser usado na resposta para a solicitação de entrada. Este código pode ser qualquer código de status válido que comece com 2xx, 4xx ou 5xx. No entanto, não há permissão para códigos de status 3xx.
Cabeçalhos headers Um ou mais cabeçalhos para incluir na resposta
Corpo body Um objeto de corpo que pode ser uma cadeia de caracteres, um objeto JSON ou até mesmo um conteúdo binário referenciado em uma etapa anterior

Para exibir a definição JSON para a ação Resposta e a definição JSON completa do fluxo de trabalho, saia do modo de exibição do designer e vá para o modo de exibição de código.

"Response": {
   "type": "Response",
   "kind": "http",
   "inputs": {
      "body": {
         "postalCode": "@triggerBody()?['address']?['postalCode']",
         "town": "@triggerBody()?['address']?['town']"
      },
      "headers": {
         "content-type": "application/json"
      },
      "statusCode": 200
   },
   "runAfter": {}
}

Perguntas e respostas

P: O que dizer sobre a segurança da URL para chamadas de entrada?

R: O Azure gera com segurança URLs de retorno de chamada do aplicativo lógico usando a SAS (Assinatura de Acesso Compartilhado). Essa assinatura é transmitida como um parâmetro de consulta e deve ser validada antes do fluxo de trabalho ser executado. O Azure gera a assinatura usando uma combinação exclusiva de uma chave secreta por aplicativo lógico, o nome do gatilho e a operação que é executada. Portanto, a menos que alguém tenha acesso à chave secreta do aplicativo lógico, não será possível gerar uma assinatura válida.

Importante

Para sistemas de produção e de maior segurança, aconselhamos fortemente a chamar o fluxo de trabalho diretamente do navegador por esses motivos:

  • A chave de acesso compartilhado é exibida na URL.
  • Você não pode gerenciar políticas de conteúdo de segurança devido a domínios compartilhados entre clientes de Aplicativos Lógicos do Azure.

Para saber mais sobre segurança, autorização e criptografia para chamadas de entrada para o fluxo de trabalho, como o protocolo TLS, anteriormente conhecido como protocolo SSL, OAuth do Microsoft Entra ID (Open Authentication do Microsoft Entra ID), expondo seu fluxo de trabalho com o Gerenciamento de API do Azure ou restringindo os endereços IP que originam chamadas de entrada, acesse Proteger o acesso e os dados – Acesso de chamadas de entrada para gatilhos baseados em solicitação.

P: Posso configurar ainda mais os pontos de extremidade chamáveis?

R: Sim, os pontos de extremidade HTTP dão suporte à configuração mais avançada por meio do Azure API Management. Esse serviço também oferece a capacidade de gerenciar todas as suas APIs de modo consistente, incluindo aplicativos lógicos, configurar os nomes de domínio personalizados, usar mais métodos de autenticação e mais, por exemplo:

Próximas etapas