Partilhar via

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

Aplica-se a: Azure Logic Apps (Consumo e Standard)

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ê possa chamar usando uma URL. Para esta tarefa, você pode expor um ponto de extremidade HTTPS síncrono nativo em seu fluxo de trabalho quando usar qualquer um dos seguintes tipos de gatilho baseados em solicitação:

Este guia mostra como criar um ponto de extremidade chamável para seu fluxo de trabalho adicionando o gatilho Request e, em seguida, chamando esse ponto de extremidade de outro fluxo de trabalho. Todos os princípios se aplicam de forma idêntica aos outros tipos de gatilho baseados em solicitação que podem receber solicitações de entrada.

Pré-requisitos

  • Uma conta e subscrição do Azure. Se não tiver uma subscrição, inscreva-se numa conta gratuita do Azure.

  • O recurso do aplicativo lógico com o fluxo de trabalho onde você deseja criar o ponto de extremidade chamável.

    Você pode começar com um fluxo de trabalho em branco ou um fluxo de trabalho existente onde você pode substituir o gatilho atual. Este exemplo começa com um fluxo de trabalho em branco.

  • Instale ou use uma ferramenta que possa enviar solicitações HTTP para testar sua solução, por exemplo:

    Atenção

    Para cenários em que você tem dados confidenciais, como credenciais, segredos, tokens de acesso, chaves de API e outras informações semelhantes, certifique-se de usar uma ferramenta que proteja seus dados com os recursos de segurança necessários. A ferramenta deve funcionar offline ou localmente e não requer login em uma conta online ou sincronização de dados com a nuvem. Ao usar uma ferramenta com essas características, você reduz o risco de expor dados confidenciais ao público.

Criar um ponto de extremidade chamável

Com base no fato de você ter um fluxo de trabalho do aplicativo lógico Padrão ou de Consumo, siga as etapas correspondentes:

  1. No portal do Azure, abra seu recurso de aplicativo lógico padrão.

  2. No menu da barra lateral do recurso, em Fluxos de trabalho, selecione Fluxos de trabalho e, em seguida, selecione o fluxo de trabalho em branco.

  3. No menu da barra lateral do fluxo de trabalho, em Ferramentas, selecione o designer para abrir o fluxo de trabalho.

  4. Adicione o gatilho Request ao seu fluxo de trabalho seguindo as etapas gerais para adicionar um gatilho.

    Este exemplo continua com o gatilho chamado Quando uma solicitação HTTP é recebida.

  5. Opcionalmente, na caixa Esquema JSON do Corpo da Solicitação , você pode inserir um esquema JSON que descreva a carga útil ou os dados que você espera que o gatilho receba.

    O designer usa esse esquema para gerar tokens que representam saídas de gatilho. Em seguida, você pode facilmente referenciar essas saídas em todo o fluxo de trabalho do seu aplicativo lógico. Saiba mais sobre tokens gerados a partir 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 padrão com o gatilho Request e o parâmetro Request Body JSON Schema com esquema de exemplo.

    Ou, você pode gerar um esquema JSON fornecendo uma carga útil de exemplo:

    1. No gatilho Solicitação selecione Usar exemplo de carga útil para gerar o esquema.

    2. Na caixa Inserir ou colar uma carga JSON de exemplo insira a sua carga 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.

  6. Salve seu fluxo de trabalho.

    A caixa URL HTTP agora mostra a URL de retorno de chamada gerada que outros serviços podem usar para chamar e acionar o fluxo de trabalho da aplicação lógica. Esse 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 padrão, o gatilho de solicitação e a URL de retorno de chamada gerada para o ponto de extremidade.

  7. Copie a URL de callback ao selecionar o ícone para copiar arquivos ao lado da caixa de URL HTTP.

  8. Para testar a URL de retorno de chamada e acionar 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 exemplo a seguir:

    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 método de solicitação esperado

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

  1. No gatilho Request, na lista Método, selecione o método que o gatilho deve esperar em vez disso. Ou, você pode especificar um método personalizado.

    Por exemplo, selecione o método GET para que você possa testar a URL do seu ponto de extremidade mais tarde.

Passar parâmetros através do URL do ponto de extremidade

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

  • Aceite valores através de parâmetros GET ou parâmetros de 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 no gatilho Request. Em uma ação subsequente, você pode obter os valores de parâmetro como saídas de gatilho usando a triggerOutputs() função em uma expressão.

  • Aceite valores através de um caminho relativo para parâmetros no gatilho Request.

    Esses valores são passados por um caminho relativo na URL do ponto de extremidade. Você também precisa selecionar explicitamente o método que o gatilho espera. Em uma ação subsequente, você pode obter os valores dos parâmetros como saídas de gatilho fazendo referência a essas saídas diretamente.

Aceitar valores através de parâmetros GET

  1. No gatilho Request , na lista Método , selecione o método GET .

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

  2. Adicione a ação Resposta ao seu fluxo de trabalho seguindo as etapas gerais para adicionar uma ação.

  3. Para criar a triggerOutputs() expressão que recupera o valor do parâmetro, execute 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, digite a seguinte expressão, substituindo parameter-name pelo nome do parâmetro, e selecione OK.

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

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

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

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

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

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

      Na visualização de código, a propriedade Body aparece na definição da ação Response da seguinte maneira:

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

      Por exemplo, suponha que você queira passar um valor para um parâmetro chamado postalCode. A propriedade Body 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 padrão com a ação Response e a expressão triggerOutputs de exemplo.

Teste seu ponto de extremidade chamável

  1. No gatilho Solicitação , copie a URL do fluxo de trabalho e cole a URL em outra janela do navegador. No URL, adicione o nome e o valor do parâmetro ao URL no seguinte formato 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: "Código Postal: 123456"

    A captura de ecrã mostra o navegador com a resposta do workflow padrão desde o pedido até ao URL de retorno de chamada.

Nota

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

Aceitar valores através de um caminho relativo

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

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

  2. Na propriedade Relative path , especifique o caminho relativo para o parâmetro em seu esquema JSON que você deseja que sua URL aceite, por exemplo, /address/{postalCode}.

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

  3. Na propriedade Body da ação Response, inclua o token que representa o parâmetro especificado no caminho relativo do gatilho.

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

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

    2. Selecione o ícone de relâmpago para abrir a lista de conteúdo dinâmico. Na secção Quando for recebida uma solicitação HTTP, selecione o gatilho da saída postalCode.

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

      A propriedade Body agora inclui o parâmetro selecionado:

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

  4. Salve seu fluxo de trabalho.

    No disparador 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}

  5. Para testar o endpoint chamável, copie a URL de retorno de chamada atualizada do gatilho Solicitação, cole a URL noutra janela do navegador, substitua %7BpostalCode%7D na URL por 123456 e pressione Enter.

    O navegador retorna uma resposta com este texto: "Código Postal: 123456"

    A captura de ecrã mostra o navegador com a resposta do workflow padrão desde o pedido até ao URL de retorno de chamada.

Nota

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

Fluxo de trabalho de chamadas através do URL do ponto de extremidade

Depois de criar o ponto de extremidade, você pode acionar o fluxo de trabalho enviando uma solicitação HTTPS para a URL completa do ponto de extremidade. Os fluxos de trabalho das Aplicações Lógicas do Azure têm suporte incorporado para pontos de extremidade de acesso direto.

Tokens gerados a partir do esquema

Quando você fornece um esquema JSON no gatilho Request , o designer de fluxo de trabalho gera tokens para as propriedades nesse esquema. Em seguida, você pode usar esses tokens para passar dados pelo seu fluxo de trabalho.

Por exemplo, se você adicionar mais propriedades, como "suite", ao seu esquema JSON, os tokens dessas propriedades estarão disponíveis para uso nas etapas posteriores do seu fluxo de trabalho. Aqui está 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-os dentro do fluxo de trabalho atual. Para chamar esses fluxos de trabalho, siga estas etapas:

  1. No designer, adicione a ação Operações de fluxo de trabalho chamada Chamar fluxo de trabalho neste aplicativo lógico.

    A lista Nome do Fluxo de Trabalho mostra os fluxos de trabalho qualificados para você 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 padrão, a ação chamada 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.

Conteúdo de referência 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, esse 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 seu aplicativo lógico, você precisa primeiro converter esse conteúdo.

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

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

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

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

Responder a pedidos

Às vezes, você deseja responder a determinadas solicitações que acionam seu fluxo de trabalho retornando o conteúdo para o 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 do fluxo de trabalho, não apenas no final do fluxo de trabalho. Se o fluxo de trabalho não incluir uma ação Resposta, o endpoint responderá imediatamente com o estado 202 Aceito.

Para que o chamador original obtenha a resposta com êxito, todas as etapas necessárias para a resposta devem ser concluídas dentro do limite de tempo limite da solicitação , a menos que o fluxo de trabalho acionado seja chamado como um fluxo de trabalho aninhado. Se nenhuma resposta for retornada dentro desse limite, a solicitação de entrada expirará e receberá a resposta de tempo limite do Cliente 408 .

Para fluxos de trabalho aninhados, o fluxo de trabalho pai continua a aguardar uma resposta até que todas as etapas sejam concluídas, independentemente de quanto tempo é 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 town propriedades e postalCode , com base no esquema JSON descrito anteriormente neste tópico para o gatilho Request.

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

As respostas têm estas propriedades:

Propriedade (Display) 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. Esse código pode ser qualquer código de status válido que comece com 2xx, 4xx ou 5xx. No entanto, códigos de status 3xx não são permitidos.
Cabeçalhos headers Um ou mais cabeçalhos a incluir na resposta
Corpo body Um objeto body que pode ser uma cadeia de caracteres, um objeto JSON ou até mesmo conteúdo binário referenciado de uma etapa anterior

Para exibir a definição JSON para a ação Resposta e a definição JSON completa do seu fluxo de trabalho, mude da visualização de designer para a visualizaçã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 frequentes

E quanto à segurança de URL para chamadas recebidas?

O Azure gera URLs de retorno de chamada de aplicativo lógico com segurança usando a assinatura de acesso compartilhado (SAS). Essa assinatura passa como um parâmetro de consulta e deve ser validada antes que seu fluxo de trabalho possa 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 executada. Portanto, a menos que alguém tenha acesso à chave secreta do aplicativo lógico, não poderá gerar uma assinatura válida.

Importante

Para sistemas de produção e de segurança superior, recomendamos vivamente que não ligue para o seu fluxo de trabalho diretamente a partir do navegador pelas seguintes razões:

  • A chave de acesso compartilhada aparece na URL.
  • Não é possível gerenciar políticas de conteúdo de segurança devido a domínios compartilhados entre clientes do Azure Logic Apps.

Para obter mais informações sobre segurança, autorização e criptografia para chamadas de entrada para seu fluxo de trabalho, como Transport Layer Security (TLS),Microsoft Entra ID Open Authentication (Microsoft Entra ID OAuth), expondo seu fluxo de trabalho de aplicativo lógico com o Gerenciamento de API do Azure ou restringindo os endereços IP que originam chamadas de entrada, consulte Acesso seguro e dados - Acesso de entrada para gatilhos baseados em solicitação.

Posso configurar ainda mais os endpoints invocáveis?

Sim, os pontos de extremidade HTTPS oferecem suporte a configurações mais avançadas por meio do Gerenciamento de API do Azure. Este serviço também oferece a capacidade de gerenciar consistentemente todas as suas APIs, incluindo aplicativos lógicos, configurar nomes de domínio personalizados, usar mais métodos de autenticação e muito mais, por exemplo:

Conteúdo relacionado

  • Last updated on