Receber e responder a chamadas HTTPS de entrada para fluxos de trabalho nos Aplicativos Lógicos do Azure

Artigo
07/18/2024

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

Este guia de instruções mostra como criar um fluxo de trabalho de aplicativo lógico que pode receber e lidar com uma solicitação HTTPS de entrada ou chamada de outro serviço usando o gatilho interno Solicitação. Quando o fluxo de trabalho usa esse gatilho, você pode responder à solicitação HTTPS usando a ação interna resposta.

Observação

A ação de Resposta funciona somente quando você usa o gatilho de Solicitação.

A lista a seguir descreve algumas tarefas de exemplo que seu fluxo de trabalho pode executar ao usar o gatilho de Solicitação e a ação de Resposta:

Receber e responder a uma solicitação HTTPS para dados em um banco de dado local.
Receber e responder a uma solicitação HTTPS de outro fluxo de trabalho de aplicativo lógico.
Disparar uma execução de fluxo de trabalho quando ocorrer um evento de webhook externo.

Para executar o fluxo de trabalho enviando uma solicitação de saída ou enviada, use o gatilho interno HTTP ou a ação interna HTTP.

Pré-requisitos

Uma conta e uma assinatura do Azure. Se você não tem uma assinatura, inscreva-se em uma conta gratuita do Azure.
O fluxo de trabalho do aplicativo lógico no qual você deseja receber a solicitação HTTPS de entrada. Para iniciar seu fluxo de trabalho com um gatilho de Solicitação, você precisará começar com um fluxo de trabalho em branco. Para usar a ação de Resposta, seu fluxo de trabalho deve começar com o gatilho de Solicitação.

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

Para cenários em que você tem dados confidenciais, como credenciais, segredos, tokens de acesso, chaves de API e outras informações semelhantes, use uma ferramenta que proteja seus dados com os recursos de segurança necessários, funcione offline ou localmente, não sincronize seus dados com a nuvem e não exija que você entre em uma conta online. Dessa forma, você reduz o risco de expor dados confidenciais ao público.

Adicionar um gatilho de Solicitação

O gatilho de Solicitação cria um ponto de extremidade que pode ser chamado manualmente e que pode receber apenas solicitações de entrada de HTTPS. Quando um chamador envia uma solicitação para esse ponto de extremidade, o gatilho de Solicitação é acionado e executa o aplicativo lógico. Para saber sobre como chamar este gatilho, revise o Chamar, disparar ou aninhar fluxos de trabalho com pontos de extremidade HTTPS em Aplicativos Lógicos do Azure.

Consumo
Standard

No portal do Azure, abra o fluxo de trabalho em branco do aplicativo lógico de Consumo no designer.
No designer, siga estas etapas gerais para localizar e adicionar o gatilho interno de Solicitação denominado Quando uma solicitação HTTP é recebida.

Depois que a caixa de informações do gatilho for exibida, forneça as seguintes informações conforme necessário:

Nome da propriedade	Nome da propriedade JSON	Obrigatório	Descrição
HTTP POST URL	{none}	Sim	O URL do ponto de extremidade gerada depois que você salva o fluxo de trabalho e é usada para enviar uma solicitação que dispara seu fluxo de trabalho.
Esquema JSON do corpo da solicitação	`schema`	Não	O esquema JSON que descreve as propriedades e os valores no corpo da solicitação de entrada. O designer usa esse esquema para gerar tokens para as propriedades na solicitação. Dessa forma, o fluxo de trabalho pode analisar, consumir e passar as saídas do gatilho de Solicitação para o fluxo de trabalho. Se você não tiver um esquema JSON, poderá gerar o esquema a partir de um payload de amostra com o recurso Usar payload de amostra para gerar o esquema.

O exemplo a seguir mostra um esquema JSON de exemplo:

Captura de tela mostrando o fluxo de trabalho de Consumo e o gatilho de Solicitação com esquema JSON de exemplo.

O exemplo a seguir mostra o esquema JSON de exemplo completo:

{
   "type": "object",
   "properties": {
      "account": {
         "type": "object",
         "properties": {
            "name": {
               "type": "string"
            },
            "ID": {
               "type": "string"
            },
            "address": {
               "type": "object",
               "properties": {
                  "number": {
                     "type": "string"
                  },
                  "street": {
                     "type": "string"
                  },
                  "city": {
                     "type": "string"
                  },
                  "state": {
                     "type": "string"
                  },
                  "country": {
                     "type": "string"
                  },
                  "postalCode": {
                     "type": "string"
                  }
               }
            }
         }
      }
   }
}

Quando você insere um esquema JSON, o designer mostra um lembrete para incluir o cabeçalho Tipo de Conteúdo em sua solicitação e definir esse valor de cabeçalho como aplicativo/json. Para saber mais, veja Lidar com tipos de conteúdo.

Captura de tela mostrando o fluxo de trabalho de Consumo, o gatilho de Solicitação e o lembrete para incluir o cabeçalho “Tipo de Conteúdo”.

O exemplo a seguir mostra como o cabeçalho Tipo de Conteúdo aparece no formato JSON:

{
   "Content-Type": "application/json"
}

Para gerar um esquema JSON baseado no payload esperado (dados), você pode usar uma ferramenta como JSONSchema.net, ou pode seguir estas etapas:

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

Insira o payload de exemplo e selecione Concluído.

Captura de tela mostrando o fluxo de trabalho de Consumo, o gatilho de Solicitação e o payload de amostra inserido para gerar esquema.

O exemplo a seguir mostra o payload de amostra:

{
   "account": {
      "name": "Contoso",
      "ID": "12345",
      "address": {
         "number": "1234",
         "street": "Anywhere Street",
         "city": "AnyTown",
         "state": "AnyState",
         "country": "USA",
         "postalCode": "11111"
      }
   }
}

Para verificar se a chamada de entrada tem um corpo de solicitação correspondente ao esquema especificado, siga estas etapas:
1. Para impor a mensagem de entrada para ter exatamente os mesmos campos que seu esquema descreve, em seu esquema, adicione a propriedade required e especifique os campos obrigatórios. Adicione a propriedade additionalProperties e defina o valor para false.
  
  Por exemplo, o esquema a seguir especifica que a mensagem de entrada deve ter o campo msg e não qualquer outro campo:
```
{
   "properties": {
     "msg": {
        "type": "string"
     }
   },
   "type": "object",
   "required": ["msg"],
   "additionalProperties": false
}
```
2. Na barra de legenda do gatilho de Solicitação, selecione o botão de reticências (...).
3. Nas configurações do gatilho, ative a validação de esquemae selecione Concluído.
  
  Se o corpo da solicitação da chamada de entrada não corresponder ao seu esquema, o gatilho retornará um erro Solicitação inválida de HTTP 400.

Para adicionar outras propriedades ou parâmetros ao gatilho, abra a lista Adicionar novo parâmetro e selecione os parâmetros que você deseja adicionar.

Nome da propriedade	Nome da propriedade JSON	Obrigatório	Descrição
Método	`method`	Não	O método que as solicitações de entrada devem usar para chamar seu aplicativo lógico
Caminho relativo	`relativePath`	Não	O caminho relativo para o parâmetro que a URL do seu ponto de extremidade pode aceitar

O exemplo a seguir adiciona a propriedade Método:

Captura de tela mostrando o fluxo de trabalho de Consumo, o gatilho de Solicitação e a adição do parâmetro

A propriedade Método aparece no gatilho para que você possa selecionar um método na lista.

Captura de tela mostrando o fluxo de trabalho de Consumo, o gatilho de Solicitação e a lista

Quando estiver pronto, salve o fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Esta etapa gera o URL que é possível usar depois para enviar uma solicitação que dispara o fluxo de trabalho.
Para copiar o URL gerado, selecione o ícone de cópia ao lado do URL.

Observação

Se quiser incluir o símbolo de hashtag ou libra (#) no URI ao fazer uma chamada para o gatilho de Solicitação, use esta versão codificada: %25%23

No portal do Azure, abra o recurso de aplicativo lógico Standard e o fluxo de trabalho em branco no designer.
No designer, siga estas etapas gerais para localizar e adicionar o gatilho interno de Solicitação denominado Quando uma solicitação HTTP é recebida.

Depois que a caixa de informações do gatilho for exibida, forneça as seguintes informações conforme necessário:

Nome da propriedade	Nome da propriedade JSON	Obrigatório	Descrição
HTTP POST URL	{none}	Sim	O URL do ponto de extremidade gerada depois que você salva o fluxo de trabalho e é usada para enviar uma solicitação que dispara seu fluxo de trabalho.
Esquema JSON do corpo da solicitação	`schema`	Não	O esquema JSON que descreve as propriedades e os valores no corpo da solicitação de entrada. O designer usa esse esquema para gerar tokens para as propriedades na solicitação. Dessa forma, o fluxo de trabalho pode analisar, consumir e passar as saídas do gatilho de Solicitação para o fluxo de trabalho. Se você não tiver um esquema JSON, poderá gerar o esquema a partir de um payload de amostra com o recurso Usar payload de amostra para gerar o esquema.

O exemplo a seguir mostra um esquema JSON de exemplo:

Captura de tela mostrando o fluxo de trabalho Standard e o gatilho de Solicitação com esquema JSON de exemplo.

O exemplo a seguir mostra o esquema JSON de exemplo completo:

{
   "type": "object",
   "properties": {
      "account": {
         "type": "object",
         "properties": {
            "name": {
               "type": "string"
            },
            "ID": {
               "type": "string"
            },
            "address": {
               "type": "object",
               "properties": {
                  "number": {
                     "type": "string"
                  },
                  "street": {
                     "type": "string"
                  },
                  "city": {
                     "type": "string"
                  },
                  "state": {
                     "type": "string"
                  },
                  "country": {
                     "type": "string"
                  },
                  "postalCode": {
                     "type": "string"
                  }
               }
            }
         }
      }
   }
}

Captura de tela mostrando o fluxo de trabalho Standard, o gatilho de Solicitação e o lembrete para incluir o cabeçalho “Tipo de Conteúdo”.

O exemplo a seguir mostra como o cabeçalho Tipo de Conteúdo aparece no formato JSON:

{
   "Content-Type": "application/json"
}

Para gerar um esquema JSON baseado no payload esperado (dados), você pode usar uma ferramenta como JSONSchema.net, ou pode seguir estas etapas:

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

Insira o payload de exemplo e selecione Concluído.

Captura de tela mostrando o fluxo de trabalho Standard, o gatilho de Solicitação e o payload de amostra inserido para gerar esquema.

O exemplo a seguir mostra o payload de amostra:

{
   "account": {
      "name": "Contoso",
      "ID": "12345",
      "address": {
         "number": "1234",
         "street": "Anywhere Street",
         "city": "AnyTown",
         "state": "AnyState",
         "country": "USA",
         "postalCode": "11111"
      }
   }
}

Para verificar se a chamada de entrada tem um corpo de solicitação correspondente ao esquema especificado, siga estas etapas:
1. Para impor a mensagem de entrada para ter exatamente os mesmos campos que seu esquema descreve, em seu esquema, adicione a propriedade required e especifique os campos obrigatórios. Adicione a propriedade additionalProperties e defina o valor para false.
  
  Por exemplo, o esquema a seguir especifica que a mensagem de entrada deve ter o campo msg e não qualquer outro campo:
```
{
   "properties": {
     "msg": {
        "type": "string"
     }
   },
   "type": "object",
   "required": ["msg"],
   "additionalProperties": false
}
```
2. No designer, selecione o gatilho de Solicitação. No painel de informações que é aberto, selecione a guia Configurações.
3. Expanda Tratamento de Dados e defina a Validação de Esquema como Ativada.
  
  Se o corpo da solicitação da chamada de entrada não corresponder ao seu esquema, o gatilho retornará um erro Solicitação inválida de HTTP 400.

Para adicionar outras propriedades ou parâmetros ao gatilho, selecione a guia Parâmetros, aba a lista Adicionar novo parâmetro e selecione os parâmetros que você deseja adicionar.

Nome da propriedade	Nome da propriedade JSON	Obrigatório	Descrição
Método	`method`	Não	O método que as solicitações de entrada devem usar para chamar seu aplicativo lógico
Caminho relativo	`relativePath`	Não	O caminho relativo para o parâmetro que a URL do seu ponto de extremidade pode aceitar

O exemplo a seguir adiciona a propriedade Método:

Captura de tela mostrando o fluxo de trabalho Standard, o gatilho de Solicitação e a adição do parâmetro

A propriedade Método aparece no gatilho para que você possa selecionar um método na lista.

Captura de tela mostrando o fluxo de trabalho Standard, o gatilho de Solicitação e a lista

Quando estiver pronto, salve o fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Esta etapa gera o URL que é possível usar depois para enviar uma solicitação que dispara o fluxo de trabalho.
Para copiar o URL gerado, selecione o ícone de cópia ao lado do URL.

Observação

Se quiser incluir o símbolo de hashtag ou libra (#) no URI ao fazer uma chamada para o gatilho de Solicitação, use esta versão codificada: %25%23

A URL do gatilho de Solicitação está associada à conta de armazenamento do fluxo de trabalho. Essa URL será alterada se a conta de armazenamento for alterada. Por exemplo, com Aplicativos lógicos Standard, se você alterar manualmente sua conta de armazenamento e copiar seu fluxo de trabalho para a nova conta de armazenamento, a URL do gatilho de Solicitação também será alterada para refletir a nova conta de armazenamento. O mesmo fluxo de trabalho tem uma URL diferente.

Validação de esquema para fluxos de trabalho sem estado

Para habilitar a validação de esquema para fluxos de trabalho sem estado, verifique se o arquivo host.json no recurso de aplicativo lógico ou projeto tem a seguinte configuração de host:

"extensions": {
   "workflow": {
      "Settings": {
         "Runtime.StatelessFlowEvaluateTriggerCondition": "true"
      }
   }
}

Agora, continue criando seu fluxo de trabalho adicionando outra ação como a próxima etapa. Por exemplo, você pode responder à solicitação adicionando uma ação de Resposta, que pode ser usada para retornar uma resposta personalizada e é descrita posteriormente neste artigo.

Observação

Seu fluxo de trabalho mantém uma solicitação de entrada aberta apenas por tempo limitado. Supondo que seu fluxo de trabalho também inclua uma ação de Resposta, se o fluxo de trabalho não retornar uma resposta ao chamador após esse período expirar, seu fluxo de trabalho retornará o status 504 GATEWAY TIMEOUT para o chamador. Se o fluxo de trabalho não incluir uma ação de Resposta, o fluxo de trabalho retornará imediatamente o status 202 ACCEPTED para o chamador.

Para saber mais sobre segurança, autenticação e criptografia para chamadas de entrada para o fluxo de trabalho, como o protocolo TLS, anteriormente conhecido como SSL, OAuth com o Microsoft Entra ID, SAS (Assinatura de Acesso Compartilhado) expondo seu recurso de aplicativo lógico com o Gerenciamento de API do Azure ou restringindo os endereços IP que originam chamadas de entrada, confira Proteger o acesso e os dados – Acesso de chamadas de entrada para gatilhos baseados em solicitação.

Saídas do gatilho

A tabela a seguir lista as saídas do gatilho de Solicitação:

Nome da propriedade JSON	Tipo de dados	Descrição
headers	Objeto	Um objeto JSON que descreve os cabeçalhos da solicitação
Corpo	Objeto	Um objeto JSON que descreve o conteúdo do corpo da solicitação

Adicionar uma ação de resposta

Ao usar o gatilho de Solicitação para receber solicitações de entrada, é possível modelar a resposta e retornar os resultados do conteúdo ao chamador usando a ação interna de Resposta, que funciona apenas com o gatilho de Solicitação. Essa combinação com o gatilho de Solicitação e a ação de Resposta cria o padrão de solicitação-resposta. Com exceção dos loops Foreach e Until e branches paralelos, é possível adicionar a ação de resposta em qualquer lugar no seu fluxo de trabalho.

Importante

Se sua ação de resposta incluir esses cabeçalhos a seguir, os Aplicativos Lógicos do Azure removerão automaticamente esses cabeçalhos da mensagem de resposta gerada sem mostrar nenhum aviso ou erro. Os Aplicativos Lógicos do Azure não incluirão esses cabeçalhos, embora o serviço não impeça você de salvar fluxos de trabalho que têm uma ação de resposta com esses cabeçalhos.
- Allow
- Cabeçalhos de Content-*, com exceção de Content-Disposition, Content-Encoding e Content-Type ao usar operações POST e PUT, mas não são incluídos para operações GET
- Cookie
- Expires
- Last-Modified
- Set-Cookie
- Transfer-Encoding
Se você tiver uma ou mais ações de resposta em um fluxo de trabalho complexo com branches, verifique se a o fluxo de trabalho processa, pelo menos, uma ação de resposta durante o runtime. Caso contrário, se todas as ações de resposta forem ignoradas, o chamador receberá o erro 502 Gateway Inválido, mesmo que o fluxo de trabalho seja concluído com êxito.
Em um fluxo de trabalho sem estado do aplicativo lógico Standard, a ação Resposta deve aparecer por último no fluxo de trabalho. Se a ação aparecer em qualquer outro lugar, os Aplicativos Lógicos do Azure não executarão a ação até que todas as outras ações terminem de ser executadas.

Consumo
Standard

No designer de fluxo de trabalho, siga estas etapas gerais para localizar e adicionar a ação interna de Solicitação denominada Resposta.

Para simplificar, os exemplos a seguir mostram um gatilho de Solicitação recolhido.

Na caixa de informações de ação de Resposta, adicione os valores necessários para a mensagem de resposta.

Nome da propriedade	Nome da propriedade JSON	Obrigatório	Descrição
Código de status	`statusCode`	Sim	O código de status a ser retornado na resposta
Cabeçalhos	`headers`	Não	Um objeto JSON que descreve um ou mais cabeçalhos a serem incluídos na resposta
Corpo	`body`	Não	O corpo da resposta

Quando você seleciona dentro de qualquer campo de texto, a lista de conteúdo dinâmico é aberta automaticamente. Em seguida, você pode selecionar tokens que representam as saídas disponíveis de etapas anteriores no fluxo de trabalho. As propriedades do esquema que você especificar também aparecem nesta lista de conteúdo dinâmico. Você pode selecionar essas propriedades para usar em seu fluxo de trabalho.

Por exemplo, para a caixa Cabeçalhos, inclua Tipo de Conteúdo como o nome da chave e defina o valor da chave como aplicativo/json, conforme mencionado anteriormente neste artigo. Para a caixa Corpo, você pode selecionar a saída do corpo do gatilho na lista de conteúdo dinâmico.

Captura de tela mostrando o portal do Azure, fluxo de trabalho de Consumo e as informações de ação de Resposta.

Para exibir os cabeçalhos no formato JSON, selecione Alternar para exibição de texto.

Captura de tela mostrando o portal do Azure, fluxo de trabalho de Consumo e os cabeçalhos de ação de Resposta na exibição

Para adicionar mais propriedades para a ação, como um esquema JSON para o corpo da resposta, abra a lista Adicionar novo parâmetro e selecione os parâmetros que você deseja adicionar.
Quando terminar, salve o fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

No designer, siga estas etapas gerais para localizar e adicionar a ação interna de Solicitação denominada Resposta.

Na caixa de informações de ação de Resposta, adicione os valores necessários para a mensagem de resposta:

Nome da propriedade	Nome da propriedade JSON	Obrigatório	Descrição
Código de status	`statusCode`	Sim	O código de status a ser retornado na resposta
Cabeçalhos	`headers`	Não	Um objeto JSON que descreve um ou mais cabeçalhos a serem incluídos na resposta
Corpo	`body`	Não	O corpo da resposta

Quando você seleciona dentro de qualquer campo de texto, você obtém a opção de abrir a lista de conteúdo dinâmico (ícone relâmpago). Em seguida, você pode selecionar tokens que representam as saídas disponíveis de etapas anteriores no fluxo de trabalho. As propriedades do esquema que você especificar também aparecem nesta lista de conteúdo dinâmico. Você pode selecionar essas propriedades para usar em seu fluxo de trabalho.

Por exemplo, para a caixa Cabeçalhos, inclua Content-Type como o nome da chave e defina o valor da chave como application/json, conforme mencionado anteriormente neste artigo. Para a caixa Corpo, você pode selecionar a saída do corpo do gatilho na lista de conteúdo dinâmico.

Captura de tela mostrando o portal do Azure, fluxo de trabalho Standard e as informações de ação de Resposta.

Para exibir os cabeçalhos no formato JSON, selecione Alternar para exibição de texto.

Captura de tela mostrando o portal do Azure, fluxo de trabalho Standard e os cabeçalhos de ação de Resposta na exibição

Para adicionar mais propriedades para a ação, como um esquema JSON para o corpo da resposta, abra a lista Adicionar novo parâmetro e selecione os parâmetros que você deseja adicionar.
Quando terminar, salve o fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Testar seu fluxo de trabalho

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

Para obter mais informações sobre a definição JSON subjacente do gatilho e como chamar esse gatilho, consulte os tópicos tipo de gatilho de solicitação e Chamar, disparar gatilho ou aninhar fluxos de trabalho com pontos de extremidade HTTP nos Aplicativos Lógicos do Azure.

Segurança e autenticação

Em um Fluxo de trabalho de aplicativo lógico Standard que começa com o gatilho de Solicitação (mas não um gatilho de webhook), você pode usar o provisionamento do Azure Functions para autenticar chamadas de entrada enviadas para o ponto de extremidade criado por esse gatilho usando uma identidade gerenciada. Essa provisão também é conhecida como "Autenticação Fácil". Para obter mais informações, examine os fluxos de trabalho do Gatilho em aplicativos lógicos Standard com o Easy Auth.

Para obter mais informações sobre segurança, autorização e criptografia para chamadas de entrada para seu fluxo de trabalho de aplicativo lógico, como Transport Layer Security (TLS), anteriormente conhecido como Secure Sockets Layer (SSL), Open Authentication do Microsoft Entra ID (OAuth do Microsoft Entra ID), expor a sua aplicação lógica com a Azure API Management ou restringir os endereços IP que originam chamadas de entrada, consulte Acesso e dados seguros – Acesso para chamadas de entrada a gatilhos baseados em solicitações.

Compartilhar via