Conectar ou chamar pontos de extremidade da API REST de fluxos de trabalho nos Aplicativos Lógicos do Azure

  • Artigo

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

Para chamar um ponto de extremidade da API REST a partir de um fluxo de trabalho de aplicativo lógico nos Aplicativos Lógicos do Azure, você pode usar as operações HTTP + Swagger internas para chamar qualquer ponto de extremidade da API REST por meio de um arquivo Swagger. O gatilho e a ação HTTP + Swagger funcionam da mesma forma que o gatilho e a ação HTTP, mas fornecem uma experiência melhor no designer de fluxo de trabalho expondo a estrutura e as saídas da API descritas pelo arquivo Swagger. Para implementar um gatilho de sondagem, siga o padrão de sondagem descrito em Criar APIs personalizadas para chamar outras APIs, serviços e sistemas a partir de fluxos de trabalho de aplicativos lógicos.

Limitações

As operações internas HTTP + Swagger atualmente suportam apenas OpenAPI 2.0, não OpenAPI 3.0.

Pré-requisitos

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

  • A URL do arquivo Swagger que descreve o ponto de extremidade da API REST de destino que você deseja chamar

    Normalmente, o ponto de extremidade REST precisa atender aos seguintes critérios para que o gatilho ou ação funcione:

    • O arquivo Swagger deve ser hospedado em uma URL HTTPS acessível publicamente.

    • O arquivo Swagger deve conter uma propriedade operationID para cada operação na definição. Caso contrário, o conector mostra apenas a última operação no arquivo Swagger.

    • O arquivo Swagger deve ter o CORS (Cross-Origin Resource Sharing) habilitado.

    Os exemplos neste guia usam o Azure AI Face, que requer uma chave de recurso e uma região de serviços de IA do Azure.

    Nota

    Para fazer referência a um arquivo Swagger que não está hospedado ou que não atende aos requisitos de segurança e origem cruzada, você pode carregar o arquivo Swagger em um contêiner de blob em uma conta de armazenamento do Azure e habilitar o CORS nessa conta de armazenamento para que você possa fazer referência ao arquivo.

  • O fluxo de trabalho do aplicativo lógico Consumo ou Padrão de onde você deseja chamar o ponto de extremidade de destino. Para começar com o gatilho HTTP + Swagger , crie um recurso de aplicativo lógico com um fluxo de trabalho em branco. Para usar a ação HTTP + Swagger, inicie seu fluxo de trabalho com qualquer gatilho desejado. Este exemplo usa o gatilho HTTP + Swagger como a primeira operação.

Adicionar um gatilho HTTP + Swagger

Esse gatilho interno envia uma solicitação HTTP para uma URL para um arquivo Swagger que descreve uma API REST. Em seguida, o gatilho retorna uma resposta que contém o conteúdo desse arquivo.

  1. No portal do Azure, abra seu recurso de aplicativo lógico padrão e um fluxo de trabalho em branco no designer.

  2. No designer, siga estas etapas gerais para adicionar o gatilho HTTP chamado HTTP + Swagger.

  3. Na caixa Ponto de extremidade do Swagger, digite a URL do arquivo Swagger desejado e selecione Adicionar ação.

    Certifique-se de usar ou criar seu próprio ponto de extremidade. Apenas como exemplo, estas etapas usam a seguinte URL Swagger da API do Azure AI Face localizada na região Oeste dos EUA e podem não funcionar em seu gatilho específico:

    https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/export?DocumentFormat=Swagger&ApiName=Face%20API%20-%20V1.0

    Screenshot shows Standard workflow designer with trigger named httpswaggeraction. The Swagger Endpoint property is set to a URL value.

  4. Quando o designer mostrar as operações descritas pelo arquivo Swagger, selecione a operação que você deseja usar.

    O exemplo a seguir renomeia o gatilho para Face - Detect para que o gatilho tenha um nome mais descritivo.

    Screenshot shows Standard workflow, Face - Detect trigger, and list with Swagger operations.

  5. Forneça os valores para os parâmetros de gatilho, que variam com base na operação selecionada, que você deseja incluir na chamada de ponto de extremidade. Configure a recorrência para a frequência com que você deseja que o gatilho chame o ponto de extremidade.

  6. Para adicionar outros parâmetros disponíveis, abra a lista Parâmetros avançados e selecione os parâmetros desejados.

    Para obter mais informações sobre os tipos de autenticação disponíveis para HTTP + Swagger, consulte Adicionar autenticação a chamadas de saída.

  7. Continue criando seu fluxo de trabalho com as ações que você deseja executar quando o gatilho for acionado.

  8. Quando tiver terminado, guarde o fluxo de trabalho. Na barra de ferramentas do estruturador, selecione Guardar.

Adicionar uma ação HTTP + Swagger

Essa ação interna envia uma solicitação HTTP para a URL do arquivo Swagger que descreve uma API REST. Em seguida, a ação retorna uma resposta que contém o conteúdo desse arquivo.

  1. No portal do Azure, abra o recurso e o fluxo de trabalho do aplicativo lógico padrão no designer.

  2. No designer, siga estas etapas gerais para adicionar a ação HTTP chamada HTTP + Swagger.

  3. Na caixa Ponto de extremidade do Swagger, digite a URL do arquivo Swagger desejado e selecione Adicionar ação.

    Certifique-se de usar ou criar seu próprio ponto de extremidade. Apenas como exemplo, estas etapas usam a seguinte URL Swagger da API do Azure AI Face localizada na região Oeste dos EUA e podem não funcionar em seu gatilho específico:

    https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/export?DocumentFormat=Swagger&ApiName=Face%20API%20-%20V1.0

    Screenshot shows Standard workflow designer with trigger named Face - Detect, and action named httpswaggeraction. The Swagger Endpoint property is set to a URL value.

  4. Quando o designer mostrar as operações descritas pelo arquivo Swagger, selecione a operação que você deseja usar.

    O exemplo a seguir renomeia a ação para Face - Identify para que a ação tenha um nome mais descritivo.

    Screenshot shows Standard workflow, Face - Identify action, and list with Swagger operations.

  5. Forneça os valores para os parâmetros de ação, que variam com base na operação selecionada, que você deseja incluir na chamada de ponto de extremidade.

  6. Para adicionar outros parâmetros disponíveis, abra a lista Parâmetros avançados e selecione os parâmetros desejados.

    Para obter mais informações sobre os tipos de autenticação disponíveis para HTTP + Swagger, consulte Adicionar autenticação a chamadas de saída.

  7. Continue a criar o seu fluxo de trabalho com quaisquer outras ações que pretenda executar.

  8. Quando tiver terminado, guarde o fluxo de trabalho. Na barra de ferramentas do estruturador, selecione Guardar.

Host Swagger no Armazenamento do Azure

Você ainda pode fazer referência a um arquivo Swagger que não esteja hospedado ou que não atenda aos requisitos de segurança e de origem cruzada. Carregue o arquivo Swagger no contêiner de blob em uma conta de armazenamento do Azure e habilite o CORS nessa conta de armazenamento. Para criar, configurar e armazenar arquivos Swagger no Armazenamento do Azure, siga estas etapas:

  1. Crie uma conta de armazenamento do Azure.

  2. Agora habilite o CORS para o blob. No menu da sua conta de armazenamento, selecione CORS. Na guia Serviço de Blob, especifique esses valores e selecione Salvar.

    Property valor
    Origens permitidas *
    Métodos permitidos GET, , HEADPUT
    Cabeçalhos permitidos *
    Cabeçalhos expostos *
    Idade máxima (em segundos) 200

    Embora este exemplo use o portal do Azure, você pode usar uma ferramenta como o Gerenciador de Armazenamento do Azure ou configurar automaticamente essa configuração usando este script PowerShell de exemplo.

  3. Crie um contêiner de blob. No painel Visão geral do contêiner, selecione Alterar nível de acesso. Na lista Nível de acesso público, selecione Blob (acesso de leitura anônimo somente para blobs) e selecione OK.

  4. Carregue o arquivo Swagger no contêiner de blob, por meio do portal do Azure ou do Gerenciador de Armazenamento do Azure.

  5. Para fazer referência ao arquivo no contêiner de blob, obtenha a URL HTTPS que segue esse formato, que diferencia maiúsculas de minúsculas, no Gerenciador de Armazenamento do Azure:

    https://<storage-account-name>.blob.core.windows.net/<blob-container-name>/<complete-swagger-file-name>?<query-parameters>

Referência técnica do conector

Esta seção fornece mais informações sobre as saídas de um gatilho e ação HTTP + Swagger .

Resultados

A chamada HTTP + Swagger retorna as seguintes informações:

Nome da propriedade Tipo Description
cabeçalhos Object Os cabeçalhos da solicitação
corpo Object O objeto com o conteúdo do corpo da solicitação
Código de status Número inteiro O código de status da solicitação
Código de estado Description
200 OK
202 Aceite
400 Mau pedido
401 Não autorizado
403 Proibido
404 Não Encontrado
500 Erro interno do servidor. Ocorreu um erro desconhecido.

Próximos passos