Chamar pontos de extremidade HTTP ou HTTPS externos de fluxos de trabalho 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 envie solicitações de saída para pontos de extremidade em outros serviços ou sistemas por HTTP ou HTTPS. Por exemplo, suponha que você deseje monitorar um ponto de extremidade de serviço do seu site verificando esse ponto em um agendamento específico. Quando um evento específico ocorrer nesse ponto de extremidade (por exemplo, quando seu site ficar inativo), o evento disparará o fluxo de trabalho do aplicativo lógico e executará as ações nesse fluxo.

Este guia mostra como usar o gatilho HTTP e a ação HTTP para que seu fluxo de trabalho possa enviar chamadas de saída para outros serviços e sistemas, por exemplo:

• Para verificar ou sondar um ponto de extremidade em um agendamento recorrente, adicione o gatilho HTTP como a primeira etapa no fluxo de trabalho. O gatilho chama ou envia uma solicitação para o ponto de extremidade a cada verificação. A resposta do ponto de extremidade determina se o fluxo de trabalho é executado. O gatilho passa qualquer conteúdo da resposta do ponto de extremidade para as ações no seu fluxo de trabalho.

• Para chamar um ponto de extremidade de qualquer outro lugar no fluxo de trabalho, adicione a ação HTTP. A resposta do ponto de extremidade determina como as ações restantes do fluxo de trabalho são executadas.

Pré-requisitos

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

• A URL do ponto de extremidade de destino que você deseja chamar

• O fluxo de trabalho do aplicativo lógico do qual você deseja chamar o ponto de extremidade de destino. Para começar com o gatilho HTTP, você precisa de um fluxo de trabalho em branco. Para usar a ação HTTP, inicie o fluxo de trabalho com o gatilho desejado. Este exemplo usa o gatilho HTTP como primeira etapa.

Referência técnica do conector

Para obter mais informações técnicas sobre parâmetros de ação e gatilho, confira as seguintes seções:

• Parâmetros de gatilho HTTP
• Parâmetros de ação HTTP

Adicionar um gatilho HTTP

Esse gatilho interno faz uma chamada HTTP para a URL especificada em um ponto de extremidade e retorna uma resposta.

Adicionar ação HTTP

Essa ação interna faz uma chamada HTTP para a URL especificada em um ponto de extremidade e retorna uma resposta.

Saídas de gatilho e ação

Saiba mais sobre as saídas de um gatilho ou ação HTTP, que retornam as seguintes informações:

Segurança de URL para chamadas de saída

Para saber mais sobre criptografia, segurança e autorização para chamadas de saída no seu fluxo de trabalho, como TLS (segurança de camada de transporte), anteriormente conhecido como SSL (Secure Sockets Layer), certificados autoassinados ou a Microsoft Entra ID Open Authentication (Microsoft Entra ID OAuth), confira Proteger o acesso e os dados – Acesso para chamadas de saída para outros serviços e sistemas.

Autenticação para ambiente de locatário único

Se você tiver um recurso de aplicativo lógico Standard nos Aplicativos Lógicos do Azure de locatário único e quiser usar uma operação HTTP com qualquer um dos tipos de autenticação a seguir, conclua as etapas de configuração extras para o tipo de autenticação correspondente. Caso contrário, a chamada falhará.

• Certificado TSL/SSL: adicione a configuração do aplicativo, WEBSITE_LOAD_ROOT_CERTIFICATES, e defina o valor para a impressão digital para seu certificado TSL/SSL.

• Certificado do cliente ou Microsoft Entra ID Open Authentication (Microsoft Entra ID OAuth) com o tipo de credencial "Certificado": adicione a configuração de aplicativo WEBSITE_LOAD_USER_PROFILE e defina o valor como 1.

Autenticação de certificado TSL/SSL

1. Nas configurações do aplicativo dos recursos de seu aplicativo lógico, adicione ou atualize a configuração do aplicativo, WEBSITE_LOAD_ROOT_CERTIFICATES.

2. Para o valor da configuração, forneça a impressão digital para seu certificado TSL/SSL como o certificado raiz que será considerado confiável.

   "WEBSITE_LOAD_ROOT_CERTIFICATES": "<thumbprint-for-TLS/SSL-certificate>"

Por exemplo, se você estiver trabalhando no Visual Studio Code, siga estas etapas:

1. Abra arquivo local.settings.json do projeto de seu aplicativo lógico.

2. No objeto JSON Values, adicione ou atualize a configuração WEBSITE_LOAD_ROOT_CERTIFICATES:

   {
      "IsEncrypted": false,
      "Values": {
         <...>
         "AzureWebJobsStorage": "UseDevelopmentStorage=true",
         "WEBSITE_LOAD_ROOT_CERTIFICATES": "<thumbprint-for-TLS/SSL-certificate>",
         <...>
      }
   }
   

   Observação

   Para localizar a impressão digital, siga estas etapas:

   1. No menu de recursos do aplicativo lógico, em Configurações, selecione configurações TLS/SSL>Certificados de chave privada (.pfx) ou Certificados de chave pública (.cer).

   2. Ache o certificado que você deseja utilizar e copie a impressão digital.

   Para obter mais informações, examine Localizar a impressão digital – Serviço de Aplicativo do Azure.

Para saber mais, consulte a seguinte documentação:

• Editar as configurações de host e de aplicativo de aplicativos lógicos nos Aplicativos Lógicos do Azure de locatário único
• Certificados de cliente privado - Serviço de Aplicativo do Azure

Certificado do cliente ou OAuth do Microsoft Entra ID com autenticação do tipo de credencial "Certificado"

1. Nas configurações do aplicativo dos recursos de seu aplicativo lógico, adicione ou atualize a configuração do aplicativo, WEBSITE_LOAD_USER_PROFILE.

2. Insira 1 no valor da configuração.

   "WEBSITE_LOAD_USER_PROFILE": "1"

Por exemplo, se você estiver trabalhando no Visual Studio Code, siga estas etapas:

1. Abra arquivo local.settings.json do projeto de seu aplicativo lógico.

2. No objeto JSON Values, adicione ou atualize a configuração WEBSITE_LOAD_USER_PROFILE:

   {
      "IsEncrypted": false,
      "Values": {
         <...>
         "AzureWebJobsStorage": "UseDevelopmentStorage=true",
         "WEBSITE_LOAD_USER_PROFILE": "1",
         <...>
      }
   }
   

Para saber mais, consulte a seguinte documentação:

• Editar as configurações de host e de aplicativo de aplicativos lógicos nos Aplicativos Lógicos do Azure de locatário único
• Certificados de cliente privado - Serviço de Aplicativo do Azure

Conteúdo com o tipo multipart/form-data

Para lidar com o conteúdo que tem o tipo multipart/form-data em solicitações HTTP, adicione um objeto JSON que inclui os atributos $content-type e $multipart ao corpo da solicitação HTTP usando esse formato.

"body": {
   "$content-type": "multipart/form-data",
   "$multipart": [
      {
         "body": "<output-from-trigger-or-previous-action>",
         "headers": {
            "Content-Disposition": "form-data; name=file; filename=<file-name>"
         }
      }
   ]
}

Por exemplo, imagine que você tem um fluxo de trabalho que envia uma solicitação HTTP POST de um arquivo do Excel a um site usando a API desse site, que é compatível com o tipo multipart/form-data. O exemplo a seguir mostra como essa ação pode aparecer:

Fluxo de trabalho Standard

Fluxo de trabalho de Consumo

Veja o mesmo exemplo que mostra a definição de JSON da ação HTTP na definição do fluxo de trabalho subjacente:

"HTTP_action": {
   "inputs": {
      "body": {
         "$content-type": "multipart/form-data",
         "$multipart": [
            {
               "body": "@trigger()",
               "headers": {
                  "Content-Disposition": "form-data; name=file; filename=myExcelFile.xlsx"
               }
            }
         ]
      },
      "method": "POST",
      "uri": "https://finance.contoso.com"
   },
   "runAfter": {},
   "type": "Http"
}

Conteúdo com o tipo application/x-www-form-urlencoded

Para inserir dados form-urlencoded no corpo de uma solicitação HTTP, é preciso especificar que os dados têm o tipo de conteúdo application/x-www-form-urlencoded. Na ação ou gatilho HTTP, adicione o cabeçalho content-type. Defina o valor do cabeçalho como application/x-www-form-urlencoded.

Por exemplo, imagine que você tem um aplicativo lógico que envia uma solicitação HTTP POST a um site compatível com o tipo application/x-www-form-urlencoded. Veja como essa ação pode acontecer:

Fluxo de trabalho Standard

Fluxo de trabalho de Consumo

Comportamento assíncrono de solicitação-resposta

Para fluxos de trabalho com estado em Aplicativos Lógicos do Azure multilocatário e de locatário único, todas as ações baseadas em HTTP seguem a operação assíncrona padrão como o comportamento padrão. Esse padrão especifica que depois que uma ação HTTP chama ou envia uma solicitação para o ponto de extremidade, serviço, sistema ou API, o destinatário retorna imediatamente uma resposta "202 ACEITO". Esse código confirma que o destinatário aceitou a solicitação, mas não concluiu o processamento. A resposta pode incluir um cabeçalho location que especifica o URI e uma ID de atualização que o autor da chamada pode usar para sondar ou verificar o status da solicitação assíncrona até que o destinatário pare de processar e retorne uma resposta de sucesso "200 OK" ou outra resposta não 202. No entanto, o autor da chamada não precisa esperar o processamento da solicitação. Ele pode continuar e executar a próxima ação. Para saber mais, confira A integração assíncrona de microsserviço impõe autonomia de microsserviço.

Para fluxos de trabalho sem estado em Aplicativos Lógicos do Azure de locatário único, as ações baseadas em HTTP não usam o padrão de operação assíncrona. Em vez disso, elas só são executados de forma síncrona, retornam a resposta "202 - Aceito" como estão e prosseguem para a próxima etapa na execução do fluxo de trabalho. Se a resposta incluir um cabeçalho location, um fluxo de trabalho sem estado não sondará o URI especificado para verificar o status. Para seguir o padrão de operação assíncrona padrão, use um fluxo de trabalho com estado.

• A definição de JSON (JavaScript Object Notation) subjacente da ação HTTP segue implicitamente o padrão assíncrono de operação.

• A ação HTTP, mas não o gatilho, tem uma configuração Padrão Assíncrono, que é habilitada por padrão. Essa configuração especifica que o autor da chamada não aguarda o processamento ser concluído e pode passar para a próxima ação, mas continua verificando o status até que o processamento seja interrompido. Se desabilitada, essa configuração especifica que o chamador aguarda o processamento ser concluído antes de passar para a próxima ação.

  Para localizar a configuração Padrão Assíncrono, siga as seguintes etapas, com base em se você tem um fluxo de trabalho Padrão ou de Consumo:

  Fluxo de trabalho Standard*

  1. No designer de fluxo de trabalho, selecione a ação HTTP. No painel de informações que é aberto, selecione Configurações.

  2. Em Rede, localize a configuração Padrão Assíncrono.

  Fluxo de trabalho de Consumo

  1. No designer do fluxo de trabalho, na barra de título da ação HTTP, selecione o botão de reticências (...), que abre as configurações da ação.

  2. Localize a configuração Padrão Assíncrono.

Desabilitar operações assíncronas

É possível que você queira desabilitar ocasionalmente o comportamento assíncrono da ação HTTP em cenários específicos, por exemplo, para o seguinte:

• Evitar tempos limite de HTTP para tarefas de longa duração
• Desabilitar verificação de cabeçalhos de localização

Desativar a configuração Padrão assíncrono

Desabilitar o padrão assíncrono na definição de JSON da ação

Na definição de JSON subjacente da ação HTTP, adicione a opção de operação"DisableAsyncPattern" à definição da ação para que ela siga o padrão síncrono de operação. Para saber mais, confira também Executar ações em um padrão síncrono de operação.

Evitar tempos limite de HTTP para tarefas de longa duração

As solicitações HTTP têm um limite de tempo. Se você tiver uma ação HTTP de execução prolongada que atinge tempo limite, terá estas opções:

• Desabilitar o padrão assíncrono de operação da ação HTTP para que a ação não seja sondada continuamente ou verificar o status da solicitação. Em vez disso, a ação aguarda o destinatário responder com o status e os resultados após o processamento da solicitação.

• Substituir a ação HTTP pela Ação de Webhook HTTP, que aguarda o destinatário responder com o status e os resultados após o processamento da solicitação.

Configurar intervalo entre tentativas de repetição com o cabeçalho Retry-After

Para especificar o número de segundos entre as tentativas de repetição, você pode adicionar o cabeçalho Retry-After à resposta de ação HTTP. Por exemplo, se o ponto de extremidade de destino retornar o código de status 429 - Too many requests, você poderá especificar um intervalo mais longo entre as repetições. O cabeçalho Retry-After também funciona com o código de status 202 - Accepted.

Este é o mesmo exemplo que mostra a resposta de ação HTTP que contém Retry-After:

{
    "statusCode": 429,
    "headers": {
        "Retry-After": "300"
    }
}

Suporte à paginação

Às vezes, o serviço de destino responde retornando os resultados uma página por vez. Se a resposta especificar a próxima página com a propriedade nextLink ou @odata.nextLink, você poderá ativar a configuração Paginação na ação HTTP. Essa configuração faz com que a ação HTTP siga automaticamente esses links e obtém a próxima página. No entanto, se a resposta especificar a próxima página com qualquer outra marca, talvez seja necessário adicionar um loop ao fluxo de trabalho. Faça esse loop seguir essa marca e obter manualmente cada página até que a marca seja nula.

Desabilitar verificação de cabeçalhos de localização

Alguns pontos de extremidade, serviços, sistemas ou APIs retornam uma resposta 202 ACCEPTED que não tem um cabeçalho location. Para evitar que uma ação HTTP verifique continuamente o status da solicitação quando o cabeçalho location não existe, você tem estas opções:

• Desabilitar o padrão assíncrono de operação da ação HTTP para que a ação não seja sondada continuamente ou verificar o status da solicitação. Em vez disso, a ação aguarda o destinatário responder com o status e os resultados após o processamento da solicitação.

• Substituir a ação HTTP pela Ação de Webhook HTTP, que aguarda o destinatário responder com o status e os resultados após o processamento da solicitação.

Problemas conhecidos

Cabeçalhos HTTP omitidos

Se uma ação ou gatilho HTTP incluir esses cabeçalhos, os Aplicativos Lógicos do Azure removerão esses cabeçalhos da mensagem de solicitação gerada sem mostrar nenhum aviso ou erro:

• Cabeçalhos Accept-*, exceto Accept-version
• Allow
• Cabeçalhos Content-*, exceto Content-Disposition, Content-Encoding e Content-Type, que são respeitados quando você usa as operações POST e PUT. No entanto, os Aplicativos Lógicos do Azure descartam esses cabeçalhos quando você usa a operação GET.
• Cabeçalho Cookie, mas os Aplicativos Lógicos do Azure respeitam qualquer valor especificado usando a propriedade Cookie.
• Expires
• Host
• Last-Modified
• Origin
• Set-Cookie
• Transfer-Encoding

Embora os Aplicativos Lógicos do Azure não impeçam que você salve os aplicativos lógicos que têm uma ação ou um gatilho HTTP com esses cabeçalhos, os Aplicativos Lógicos do Azure ignoram esses cabeçalhos.

O conteúdo da resposta não corresponde ao tipo de conteúdo esperado

A ação HTTP gerará um erro BadRequest se a ação HTTP chamar a API de back-end com o cabeçalho Content-Type definido como application/json, mas a resposta do back-end não contiver o conteúdo no formato JSON, o que falhará na validação do formato JSON interno.

Próximas etapas

• Conectores gerenciados dos Aplicativos Lógicos do Azure
• Conectores internos de Aplicativos Lógicos do Azure