Criar fluxos de trabalho que você pode chamar, disparar ou aninhar usando pontos de extremidade HTTPS nos Aplicativos Lógicos do Azure
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:
- Solicitar
- Webhook HTTP
- Gatilhos de conector gerenciados que têm o tipo ApiConnectionWebhook e podem receber solicitações HTTPS de entrada
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 baseado em solicitação para criar o ponto de extremidade chamável. 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.
Para testar a URL do ponto de extremidade chamável que você criou, você precisará de uma ferramenta ou aplicativo, como o Postman.
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:
No portal do Azure, abra o recurso de aplicativo lógico Standard e o fluxo de trabalho em branco no designer.
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" } } } } }
Ou, você pode gerar um esquema JSON fornecendo um conteúdo de exemplo:
No gatilho de Solicitação, selecione Usar conteúdo de amostra para gerar o esquema.
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" } }Quando estiver pronto, selecione Concluído.
A caixa Esquema JSON do Corpo da Solicitação agora mostra o esquema gerado.
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.
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.
No menu do fluxo de trabalho, selecione Visão geral.
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:
Para testar a URL de retorno de chamada que você tem agora para o gatilho da solicitação, use uma ferramenta ou aplicativo como o Postman e envie a solicitação usando o método esperado pelo gatilho da solicitação.
Esse exemplo usa o método
POST: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 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.
No gatilho Solicitação, abra a lista Parâmetros avançados e selecione o Método, que adiciona essa propriedade ao gatilho.
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 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 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
No gatilho Solicitação, abra a Parâmetros avançados, adicione a propriedade Método para o gatilho e selecione o método GET.
Para obter mais informações, confira Selecionar o método de solicitação esperado.
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.
Para criar a expressão
triggerOutputs()que recupera o valor do parâmetro, siga estas etapas: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.
Na caixa de expressão, insira a expressão a seguir, substituindo
parameter-namepelo nome do parâmetro e selecione OK.triggerOutputs()['queries']['parameter-name']
Na propriedade Corpo, a expressão é resolvida para o token
triggerOutputs().
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:
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:
Testar o ponto de extremidade chamável
No gatilho 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
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
No gatilho Solicitação, abra a lista Parâmetros avançados e selecione o Caminho relativo, que adiciona essa propriedade ao gatilho.
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}.
No gatilho 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.
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}.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.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 propriedade Corpo agora inclui o parâmetro selecionado:
Salve seu fluxo de trabalho.
No gatilho 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}Para testar seu ponto de extremidade chamável, copie a URL de retorno de chamada atualizada do gatilho Solicitação, cole-a em outra janela do navegador, substitua
%7BpostalCode%7Dna URL por123456e pressione Enter.O navegador retorna uma resposta com este texto:
Postal Code: 123456
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:
-
A lista Nome do Fluxo de Trabalho mostra os fluxos de trabalho que você pode selecionar.
Na lista Nome do Fluxo de Trabalho, selecione o fluxo de trabalho que você deseja chamar, por exemplo:
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 Solicitação.
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:
- Alterar o método de solicitação
- Alterar os segmentos de URL da solicitação
- Configurar os domínios de API Management no portal do Azure
- Configurar a política para verificar a autenticação Básica