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: 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ê 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:
- Pedir
- Webhook de HTTP
- Gatilhos de conector gerenciado que têm o tipo ApiConnectionWebhook e podem receber solicitações HTTPS de entrada
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 do Azure gratuita.
Um fluxo de trabalho de aplicativo lógico onde você deseja usar o gatilho Request para 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:
- Código do Visual Studio com uma extensão do Visual Studio Marketplace
- PowerShell Invoke-RestMethod
- Microsoft Edge - Ferramenta Network Console
- Adriano
- ondulação
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, 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 exposição de 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:
No portal do Azure, abra o recurso do aplicativo lógico padrão 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 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" } } } } }
Ou, você pode gerar um esquema JSON fornecendo uma carga útil de exemplo:
No gatilho Solicitação, selecione Usar carga útil de exemplo para gerar esquema.
Na caixa Inserir ou colar uma carga JSON de exemplo, insira sua carga útil de amostra, 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 HTTP POST URL agora mostra a URL de retorno de chamada gerada que outros serviços podem usar para chamar e acionar o fluxo de trabalho do aplicativo lógico. Esse URL inclui parâmetros de consulta que especificam uma chave SAS (Assinatura de Acesso Compartilhado), que é usada para autenticação.
Para copiar o URL de retorno de chamada, você tem estas opções:
À direita da caixa HTTP POST URL , selecione Copiar URL (ícone de cópia de arquivos).
Copie o 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 Visão geral, em URL do fluxo de trabalho, mova o ponteiro sobre o URL e selecione Copiar para a área de transferência:
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.
No gatilho Request, abra a lista Advanced parameters e selecione Method, que adiciona essa propriedade ao trigger.
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 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
No gatilho Request , abra os parâmetros Advanced, adicione a propriedade Method ao gatilho e selecione o método GET .
Para obter mais informações, consulte Selecionar método de solicitação esperado.
No designer, siga estas etapas gerais para adicionar a ação onde você deseja usar o valor do parâmetro.
Para este exemplo, selecione a ação chamada Resposta.
Para criar a
triggerOutputs()expressão que recupera o valor do parâmetro, execute 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, digite a seguinte expressão, substituindo
parameter-namepelo nome do parâmetro, e selecione OK.triggerOutputs()['queries']['parameter-name']
Na propriedade Body, a expressão é resolvida para o
triggerOutputs()token.
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:
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:
Teste seu ponto de extremidade chamável
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:
Postal Code: 123456
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
No gatilho Solicitação , abra a lista Parâmetros avançados e selecione Caminho relativo, que adiciona essa propriedade ao gatilho.
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}.
No gatilho Solicitação , siga estas etapas gerais para adicionar a ação onde você deseja usar o valor do parâmetro.
Para este exemplo, adicione a ação Resposta .
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}.Na propriedade Body, entre
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.Na lista de conteúdo dinâmico, na seção Quando uma solicitação HTTP é recebida , selecione a saída do gatilho Path Parameters postalCode .
A propriedade Body 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 o ponto de extremidade chamável, copie a URL de retorno de chamada atualizada do gatilho Solicitação , cole a URL em outra janela do navegador, substitua
%7BpostalCode%7Da URL por123456e pressione Enter.O navegador retorna uma resposta com este texto:
Postal Code: 123456
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:
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 qualificados para você selecionar.
Na lista Nome do Fluxo de Trabalho, selecione o fluxo de trabalho que você deseja chamar, por exemplo:
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 de Resposta, o ponto de extremidade responderá imediatamente com o status 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 .
As respostas têm estas propriedades:
| Propriedade (Display) | Propriedade (JSON) | Description |
|---|---|---|
| Código de Estado | 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 e Respostas
P: E quanto à segurança de URL para chamadas recebidas?
R: 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), anteriormente conhecido como Secure Sockets Layer (SSL), 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 para chamadas de entrada a gatilhos baseados em solicitação.
P: Posso configurar ainda mais os pontos de extremidade chamáveis?
R: Sim, os pontos de extremidade HTTPS suportam 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:
- Alterar o método de solicitação
- Alterar os segmentos de URL da solicitação
- Configurar seus domínios de Gerenciamento de API no portal do Azure
- Configurar a política para verificar a autenticação Básica