Aplicações lógicas de chamada, gatilho ou ninho utilizando pontos finais HTTPS em Azure Logic Apps

Aplica-se a: Azure Logic Apps (Consumo)

Para tornar a sua aplicação lógica callable através de um URL e capaz de receber pedidos de entrada de outros serviços, pode desinsutilar um ponto final https sincronizado utilizando um gatilho baseado em pedidos na sua aplicação lógica. Com esta capacidade, pode ligar para a sua aplicação lógica a partir de outras aplicações lógicas e criar um padrão de pontos finais callable. Para configurar um ponto final chamado para o manuseamento de chamadas de entrada, pode utilizar qualquer um destes tipos de gatilho:

Este artigo mostra como criar um ponto final chamado na sua aplicação lógica, utilizando o gatilho 'Pedido' e chamando esse ponto final de outra aplicação lógica. Todos os princípios aplicam-se de forma idêntica aos outros tipos de gatilho que pode utilizar para receber pedidos de entrada.

Para mais informações sobre segurança, autorização e encriptação para chamadas de entrada para a sua aplicação lógica, como a Transport Layer Security (TLS), anteriormente conhecida como Secure Sockets Layer (SSL), Azure Ative Directory Open Authentication (Azure AD OAuth), expondo a sua aplicação lógica com a Azure Gestão de API, ou restringindo os endereços IP que originam chamadas de entrada, ver Acesso seguro e dados - Acesso a chamadas de entrada para gatilhos baseados em pedidos.

Pré-requisitos

Criar um ponto final callable

  1. Inicie sessão no portal do Azure. Crie e abra uma aplicação lógica em branco no Logic App Designer.

  2. Sob a caixa de pesquisa, selecione Incorporado. Na caixa de pesquisa, introduza request como filtro. A partir da lista de gatilhos, selecione Quando receber um pedido HTTP.

    Localizar e selecionar o gatilho 'Pedido'

  3. Opcionalmente, na caixa de Esquema JSON do Corpo de Pedido , pode introduzir um esquema JSON que descreve a carga útil ou dados que espera que o gatilho receba.

    O designer usa este esquema para gerar fichas que representam saídas de gatilho. Em seguida, pode facilmente referenciar estas saídas através do fluxo de trabalho da sua aplicação lógica. Saiba mais sobre os tokens gerados a partir de esquemas JSON.

    Para este exemplo, insira este esquema:

       {
       "type": "object",
       "properties": {
          "address": {
             "type": "object",
             "properties": {
                "streetNumber": {
                   "type": "string"
                },
                "streetName": {
                   "type": "string"
                },
                "town": {
                   "type": "string"
                },
                "postalCode": {
                   "type": "string"
                }
             }
          }
       }
    }
    

    Fornecer esquema JSON para a ação Request

    Ou, pode gerar um esquema JSON fornecendo uma carga útil da amostra:

    1. No gatilho 'Pedido', selecione Utilize a carga útil da amostra para gerar esquema.

    2. Na caixa de carga JSON de amostra ou cole uma amostra , introduza a carga útil da amostra, por exemplo:

      {
         "address": {
            "streetNumber": "00000",
            "streetName": "AnyStreet",
            "town": "AnyTown",
            "postalCode": "11111-1111"
        }
      }
      
    3. Quando estiver pronto, selecione 'Fazer'.

      A caixa de esquemas JSON do Corpo de Pedido mostra agora o esquema gerado.

  4. Guarde a sua aplicação lógica.

    A caixa URL HTTP POST mostra agora o URL de retorno gerado que outros serviços podem usar para ligar e desencadear a sua aplicação lógica. Este URL inclui parâmetros de consulta que especificam uma chave assinatura de acesso partilhado (SAS), que é usada para autenticação.

    URL de retorno de chamada gerado para ponto final

  5. Para copiar o URL de retorno, tem estas opções:

    • À direita da caixa URL HTTP POST , selecione Copy Url (ícone de ficheiros de cópia).

    • Faça esta chamada utilizando o método que o gatilho do Pedido espera. Este exemplo utiliza o POST método:

      POST https://management.azure.com/{logic-app-resource-ID}/triggers/{endpoint-trigger-name}/listCallbackURL?api-version=2016-06-01

    • Copie o URL de retorno do painel de visão geral da sua aplicação lógica.

      1. No menu da sua aplicação lógica, selecione Overview.

      2. No painel de visão geral, selecione o histórico do Gatilho. Em url callback [POST], copie o URL:

        Screenshot mostrando o painel 'Overview' da aplicação lógica com 'Trigger history' selecionado.

Selecione o método de pedido esperado

Por predefinição, o gatilho Do Pedido espera um POST pedido. No entanto, pode especificar um método diferente que o chamador deve usar, mas apenas um único método.

  1. No gatilho 'Pedido', abra a nova lista de parâmetros e selecione Método, que adiciona esta propriedade ao gatilho.

    Adicione a propriedade

  2. Na lista De Métodos , selecione o método que o gatilho deve esperar. Ou, pode especificar um método personalizado.

    Por exemplo, selecione o método GET para que possa testar o URL do seu ponto final mais tarde.

    Selecione o método de pedido esperado pelo gatilho

Passar parâmetros através do URL do ponto final

Quando pretende aceitar valores de parâmetros através do URL do ponto final, tem estas opções:

  • Aceite valores através de parâmetros GET ou URL.

    Estes valores são passados como pares de valor-nome na URL do ponto final. Para esta opção, tem de utilizar o método GET no seu gatilho Pedido. Numa ação posterior, pode obter os valores dos parâmetros como saídas de gatilho utilizando a triggerOutputs() função numa expressão.

  • Aceite valores através de um caminho relativo para parâmetros no seu gatilho Pedido.

    Estes valores são passados por um caminho relativo na URL do ponto final. Também precisa de selecionar explicitamente o método que o gatilho espera. Numa ação subsequente, pode obter os valores dos parâmetros como saídas de gatilho, referindo-se diretamente a essas saídas.

Aceitar valores através de parâmetros GET

  1. No gatilho 'Pedido', abra a nova lista de parâmetros adicionar, adicione a propriedade Method ao gatilho e selecione o método GET .

    Para obter mais informações, consulte o método de pedido esperado.

  2. No detonador 'Pedido', adicione a ação onde pretende utilizar o valor do parâmetro. Para este exemplo, adicione a ação Resposta .

    1. No âmbito do gatilho 'Pedido', selecione Novo passo>Adicione uma ação.

    2. Em Seleção de uma ação, na caixa de pesquisa, introduza response como filtro. Na lista de ações, selecione a ação Resposta .

  3. Para construir a triggerOutputs() expressão que recupera o valor do parâmetro, siga estes passos:

    1. Clique dentro da propriedade 'Corpo ' de ação resposta para que a lista de conteúdos dinâmicos apareça e selecione Expressão.

    2. Na caixa 'Expressão ', introduza esta expressão, substituindo parameter-name o nome do seu parâmetro e selecione OK.

      triggerOutputs()['queries']['parameter-name']

      Adicione a expressão

      Na propriedade Body , a expressão resolve-se triggerOutputs() ao símbolo.

      Expressão

      Se guardar a aplicação lógica, navegar para longe do designer e voltar ao designer, o token mostra o nome do parâmetro que especificou, por exemplo:

      Expressão resolvida para nome de parâmetro

      Na visão de código, a propriedade body aparece na definição da ação resposta da seguinte forma:

      "body": "@{triggerOutputs()['queries']['parameter-name']}",

      Por exemplo, suponha que queira passar um valor para um parâmetro chamado postalCode. A propriedade Body especifica a cadeia, Postal Code: com um espaço de fuga, seguido da expressão correspondente:

      Adicione o exemplo de expressão

  4. Para testar o seu ponto final callable, copie o URL de retorno do gatilho 'Pedido' e cole o URL noutra janela do navegador. No URL, adicione o nome e o valor do parâmetro seguindo o ponto de interrogação (?) ao URL no seguinte formato e prima Enter.

    ...?{parameter-name=parameter-value}&api-version=2016-10-01...

    https://prod-07.westus.logic.azure.com:433/workflows/{logic-app-resource-ID}/triggers/manual/paths/invoke?{parameter-name=parameter-value}&api-version=2016-10-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={shared-access-signature}

    O navegador devolve uma resposta com este texto: Postal Code: 123456

    Resposta do envio de pedido para URL de retorno

  5. Para colocar o nome e o valor do parâmetro numa posição diferente dentro do URL, certifique-se de que utiliza o ampersand (&) como prefixo, por exemplo:

    ...?api-version=2016-10-01&{parameter-name=parameter-value}&...

    Este exemplo mostra o URL de retorno com o nome do parâmetro da amostra e valor postalCode=123456 em diferentes posições dentro do URL:

    • 1ª posição: https://prod-07.westus.logic.azure.com:433/workflows/{logic-app-resource-ID}/triggers/manual/paths/invoke?postalCode=123456&api-version=2016-10-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={shared-access-signature}

    • 2ª posição: https://prod-07.westus.logic.azure.com:433/workflows/{logic-app-resource-ID}/triggers/manual/paths/invoke?api-version=2016-10-01&postalCode=123456&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={shared-access-signature}

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

  1. No gatilho 'Pedido', abra a nova lista de parâmetros adicionar e selecione O caminho relativo, que adiciona esta propriedade ao gatilho.

    Adicione a propriedade

  2. Na propriedade relativa do caminho , especifique o caminho relativo para o parâmetro no seu esquema JSON que deseja que o seu URL aceite, por exemplo, /address/{postalCode}.

    Especificar o caminho relativo para o parâmetro

  3. No detonador 'Pedido', adicione a ação onde pretende utilizar o valor do parâmetro. Para este exemplo, adicione a ação Resposta .

    1. No âmbito do gatilho 'Pedido', selecione Novo passo>Adicione uma ação.

    2. Em Seleção de uma ação, na caixa de pesquisa, introduza response como filtro. Na lista de ações, selecione a ação Resposta .

  4. Na propriedade Body da ação resposta, inclua o token que representa o parâmetro especificado no caminho relativo do seu gatilho.

    Por exemplo, suponha que quer que a ação Resposta regresse Postal Code: {postalCode}.

    1. Na propriedade Corpo , entre Postal Code: com um espaço de fuga. Mantenha o cursor dentro da caixa de edição para que a lista de conteúdos dinâmicos permaneça aberta.

    2. Na lista de conteúdos dinâmicos, a partir da secção Quando é recebido um pedido HTTP , selecione o token postalCode .

      Adicione o parâmetro especificado ao corpo de resposta

      A propriedade Body inclui agora o parâmetro selecionado:

      Corpo de resposta de exemplo com parâmetro

  5. Guarde a sua aplicação lógica.

    No gatilho do Pedido, o URL de retorno é atualizado e agora inclui o caminho relativo, por exemplo:

    https://prod-07.westus.logic.azure.com/workflows/{logic-app-resource-ID}/triggers/manual/paths/invoke/address/{postalCode}?api-version=2016-10-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={shared-access-signature}

  6. Para testar o seu ponto final callable, copie o URL de retorno atualizado do gatilho 'Pedido', cole o URL noutra janela do navegador, substitua-o {postalCode} no URL com 123456, e prima Enter.

    O navegador devolve uma resposta com este texto: Postal Code: 123456

    Resposta do envio de pedido para URL de retorno

Nota

Se quiser incluir o hash ou o símbolo de libra ( # ) no URI, utilize esta versão codificada: %25%23

App lógica de chamada através de URL de ponto final

Depois de criar o ponto final, pode desencadear a aplicação lógica enviando um pedido HTTPS para o URL completo do ponto final. As aplicações lógicas têm suporte incorporado para pontos finais de acesso direto.

Fichas geradas a partir de esquema

Quando fornece um esquema JSON no gatilho 'Pedido', o Logic App Designer gera fichas para as propriedades nesse esquema. Em seguida, pode utilizar esses tokens para passar dados através do fluxo de trabalho da sua aplicação lógica.

Por exemplo, se adicionar mais propriedades, como, por "suite"exemplo, ao seu esquema JSON, os tokens para essas propriedades estão disponíveis para que possa utilizar nos passos posteriores para a sua aplicação lógica. Aqui está o esquema completo do JSON:

   {
   "type": "object",
   "properties": {
      "address": {
         "type": "object",
         "properties": {
            "streetNumber": {
               "type": "string"
            },
            "streetName": {
               "type": "string"
            },
            "suite": {
               "type": "string"
            },
            "town": {
               "type": "string"
            },
            "postalCode": {
               "type": "string"
            }
         }
      }
   }
}

Criar aplicativos de lógica aninhados

Pode nidificar fluxos de trabalho na sua aplicação lógica adicionando outras aplicações lógicas que podem receber pedidos. Para incluir estas aplicações lógicas, siga estes passos:

  1. Sob o passo em que pretende chamar outra aplicação lógica, selecione Novo passo>Adicione uma ação.

  2. Em Escolha uma ação, selecione Incorporado. Na caixa de pesquisa, introduza logic apps como filtro. A partir da lista de ações, selecione Escolha um fluxo de trabalho de Apps Lógicas.

    App lógica ninho dentro da app lógica atual

    O designer mostra as aplicações lógicas elegíveis para você selecionar.

  3. Selecione a aplicação lógica para ligar a partir da sua aplicação lógica atual.

    Selecione app lógica para ligar a partir da app lógica atual

Conteúdo de referência de um pedido de entrada

Se o tipo de conteúdo do pedido de entrada for application/json, pode referenciar as propriedades no pedido de entrada. Caso contrário, este conteúdo é tratado como uma única unidade binária que pode passar para outras APIs. Para fazer referência a este conteúdo dentro do fluxo de trabalho da sua aplicação lógica, é necessário converter primeiro esse conteúdo.

Por exemplo, se estiver a passar conteúdo que tenha application/xml tipo, pode usar a @xpath() expressão para realizar uma extração de XPath ou usar a @json() expressão para converter XML em JSON. Saiba mais sobre trabalhar com tipos de conteúdo suportados.

Para obter a saída de um pedido de entrada, pode usar a @triggerOutputs expressão. Por exemplo, suponha que tenha uma saída que se pareça com este exemplo:

{
   "headers": {
      "content-type" : "application/json"
   },
   "body": {
      "myProperty" : "property value"
   }
}

Para aceder especificamente à body propriedade, pode usar a @triggerBody() expressão como atalho.

Responder aos pedidos

Por vezes, pretende responder a determinados pedidos que desencadeiam a sua aplicação lógica devolvendo o conteúdo ao chamador. Para construir o código de estado, cabeçalho e corpo para a sua resposta, utilize a ação Resposta. Esta ação pode aparecer em qualquer lugar da sua aplicação lógica, não apenas no final do seu fluxo de trabalho. Se a sua aplicação lógica não incluir uma ação de Resposta, o ponto final responde imediatamente com o estado 202 Aceite .

Para que o chamador original obtenha com sucesso a resposta, todas as etapas necessárias para a resposta devem terminar dentro do prazo de tempo do pedido , a menos que a aplicação lógica desencadeada seja chamada como uma app lógica aninhada. Se nenhuma resposta for devolvida dentro deste limite, o pedido de entrada termina e recebe a resposta de tempo limite do Cliente 408 .

Para aplicações lógicas aninhadas, a aplicação lógica dos pais continua a aguardar uma resposta até que todos os passos estejam concluídos, independentemente do tempo necessário.

Construa a resposta

No corpo de resposta, pode incluir vários cabeçalhos e qualquer tipo de conteúdo. Por exemplo, o cabeçalho desta resposta especifica que o tipo de conteúdo da resposta é application/json e que o corpo contém valores para o town e postalCode propriedades, com base no esquema JSON descrito anteriormente neste tópico para o gatilho Do Pedido.

Fornecer conteúdo de resposta para ação https response

As respostas têm estas propriedades:

Propriedade (Exibição) Propriedade (JSON) Description
Código de Estado statusCode O código de estado HTTPS a utilizar na resposta ao pedido de entrada. Este código pode ser qualquer código de estado válido que comece com 2xx, 4xx ou 5xx. No entanto, não são permitidos códigos de estado 3xx.
Cabeçalhos headers Um ou mais cabeçalhos para incluir na resposta
Corpo body Um objeto corporal que pode ser uma corda, um objeto JSON, ou mesmo conteúdo binário referenciado a partir de um passo anterior

Para ver a definição JSON para a ação Resposta e a definição completa de JSON da sua aplicação lógica, na barra de ferramentas Logic App Designer, selecione a vista 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": {}
}

Q & A

P: E a segurança da URL?

R: O Azure gera de forma segura URLs de callback de aplicações lógicas utilizando a Assinatura de Acesso Partilhado (SAS). Esta assinatura passa como parâmetro de consulta e deve ser validada antes que a sua aplicação lógica possa ser executada. O Azure gera a assinatura usando uma combinação única de uma chave secreta por aplicação lógica, o nome do gatilho e a operação que é realizada. Portanto, a menos que alguém tenha acesso à chave de aplicações lógicas secretas, não pode gerar uma assinatura válida.

Importante

Para a produção e sistemas de segurança mais elevados, aconselhamos veementemente que não chame a sua aplicação lógica diretamente do navegador por estas razões:

  • A chave de acesso partilhada aparece na URL.
  • Não é possível gerir políticas de conteúdo de segurança devido a domínios partilhados em todos os clientes da Azure Logic Apps.

Para mais informações sobre segurança, autorização e encriptação para chamadas de entrada para a sua aplicação lógica, como a Transport Layer Security (TLS), anteriormente conhecida como Secure Sockets Layer (SSL), Azure Ative Directory Open Authentication (Azure AD OAuth), expondo a sua aplicação lógica com a Azure Gestão de API, ou restringindo os endereços IP que originam chamadas de entrada, ver Acesso seguro e dados - Acesso a chamadas de entrada para gatilhos baseados em pedidos.

P: Posso configurar ainda mais os pontos finais callable?

R: Sim, os pontos finais HTTPS suportam uma configuração mais avançada através do Azure Gestão de API. Este serviço também oferece a capacidade para gerir de forma consistente todas as suas APIs, incluindo aplicações lógicas, configurar nomes de domínio personalizados, usar mais métodos de autenticação, e muito mais, por exemplo:

Passos seguintes