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 de um fluxo de trabalho de aplicativo lógico nos Aplicativos Lógicos do Azure, você pode usar as operações internas HTTP + Swagger 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ção HTTP, mas fornecem uma experiência melhor no Designer de fluxo de trabalho ao expor a estrutura da API e as saídas 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 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 você não tiver uma assinatura do Azure, inscreva-se em uma conta gratuita do Azure.

  • 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 ação funcione:

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

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

    • O arquivo Swagger deve ter o CORS (compartilhamento de recursos entre origens) habilitado.

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

    Observação

    Para fazer referência a um arquivo Swagger que não está hospedado ou que não atende aos requisitos de segurança e entre origens, 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 seja possível referenciar o 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 o gatilho que você quiser. 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 do 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, insira 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, essas etapas usam a seguinte URL do 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 de acordo com a operação selecionada) que você deseja incluir na chamada do ponto de extremidade. Configure a recorrência para definir 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, confira 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 terminar, salve o fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Selecionar uma ação HTTP + Swagger

Esse ação interna envia uma solicitação HTTP para a URL para um arquivo do 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 de aplicativo lógico Standard e o fluxo de trabalho 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, insira 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, essas etapas usam a seguinte URL do 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 conforme a operação selecionada) que você deseja incluir na chamada do 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, confira Adicionar autenticação a chamadas de saída.

  7. Continue criando seu fluxo de trabalho com quaisquer outras ações que você deseja executar.

  8. Quando terminar, salve o fluxo de trabalho. Selecione Salvar na barra de ferramentas do designer.

Hospedar o Swagger no Armazenamento do Azure

Você ainda pode fazer referência a um arquivo do Swagger que não está hospedado ou que não atende aos requisitos de segurança e entre origens. Upload o arquivo do Swagger para o contêiner de blob em uma conta de armazenamento do Azure e habilitar CORS nessa conta de armazenamento. Para criar, configurar e armazenar arquivos Swagger no Armazenamento do Azure, siga estas etapas:

  1. Criar 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 Blob, especifique estes valores e, em seguida, selecione Salvar.

    Propriedade Valor
    Origens permitidas *
    Métodos permitidos GET, HEAD, PUT
    Cabeçalhos permitidos *
    Cabeçalhos expostos *
    Idade máxima (em segundos) 200

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

  3. Criar 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 este 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 .

Saídas

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

Nome da propriedade Type Descrição
headers Objeto Os cabeçalhos da solicitação
Corpo Objeto O objeto com o conteúdo do corpo da solicitação
código de status Inteiro O código de status da solicitação
Código de status Descrição
200 OK
202 Accepted
400 Solicitação inválida
401 Não Autorizado
403 Proibido
404 Não encontrado
500 Erro interno do servidor. Ocorreu um erro desconhecido.

Próximas etapas