Partekatu honen bidez:

Cree flujos de trabajo a los que pueda llamar, desencadenar o anidar usando puntos de conexión HTTPS en Azure Logic Apps

  • Artikulua

Se aplica a: Azure Logic Apps (consumo + estándar)

Algunos escenarios pueden requerir que cree un flujo de trabajo de aplicación lógica que pueda recibir solicitudes entrantes de otros servicios o flujos de trabajo, o un flujo de trabajo al que pueda llamar usando una URL. Para esta tarea, puede exponer un punto de conexión HTTPS sincrónico nativo en el flujo de trabajo cuando use cualquiera de los siguientes tipos de desencadenador basados en solicitudes:

Esta guía muestra cómo crear un punto de conexión invocable para su flujo de trabajo añadiendo el desencadenador Request y después llamar a ese punto de conexión desde otro flujo de trabajo. Todos los principios se aplican de forma idéntica a los demás tipos de desencadenador basados en solicitudes que pueden recibir solicitudes entrantes.

Requisitos previos

  • Una cuenta y una suscripción de Azure. Si aún no tiene una, regístrese para obtener una cuenta de Azure gratuita.

  • Un flujo de trabajo de aplicación lógica en el que desea usar el desencadenador de solicitudes para crear el punto de conexión al que se puede llamar. Puede empezar con un flujo de trabajo en blanco o con uno existente en el que pueda reemplazar el desencadenador actual. Este ejemplo comienza con una flujo de trabajo en blanco.

  • Instale o use una herramienta que pueda enviar solicitudes HTTP para probar la solución, por ejemplo:

    Precaución

    En escenarios en los que tiene datos confidenciales, como credenciales, secretos, tokens de acceso, claves de API y otra información similar, asegúrese de usar una herramienta que proteja los datos con las características de seguridad necesarias, funcione sin conexión o localmente, no sincronice los datos en la nube y no requiera que inicie sesión en una cuenta en línea. De este modo, se reduce el riesgo de exponer datos confidenciales al público.

Creación de un punto de conexión al que se puede llamar

En función de si tiene un flujo de trabajo de aplicación lógica Estándar o de Consumo, siga los pasos correspondientes:

  1. En Azure Portal, abra su recurso de aplicación lógica Estándar y el flujo de trabajo en blanco en el diseñador.

  2. Siga estos pasos generales para agregar el desencadenador de Solicitudes denominado Cuando se recibe una solicitud HTTP.

  3. De manera opcional, en el cuadro Esquema JSON de cuerpo de solicitud, puede especificar un esquema JSON que describa la carga o los datos que espera que reciba el desencadenador.

    El diseñador usa este esquema para generar tokens que representan los resultados del desencadenador. Luego puede hacer referencia fácilmente a estos resultados en el flujo de trabajo de la aplicación lógica. Obtenga más información sobre tokens generados a partir de esquemas JSON.

    En este ejemplo, escriba el esquema siguiente:

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

    Captura de pantalla que muestra el flujo de trabajo Estándar con el desencadenador de solicitud y el parámetro de esquema JSON del cuerpo de la solicitud con esquema de ejemplo.

    O bien, puede generar un esquema JSON si proporciona una carga de ejemplo:

    1. En el desencadenador Solicitud, seleccione Usar una carga de ejemplo para generar el esquema.

    2. En el cuadro Especificar o pegar una carga de JSON de ejemplo, proporcione una carga de muestra, por ejemplo:

      {
   "address": {
      "streetNumber": "00000",
      "streetName": "AnyStreet",
      "town": "AnyTown",
      "postalCode": "11111-1111"
  }
}

    3. Cuando lo tenga todo preparado, seleccione Listo.

      El cuadro Esquema JSON de cuerpo de solicitud muestra ahora el esquema generado.

  4. Guarde el flujo de trabajo.

    En el cuadro Dirección URL de HTTP POST aparece la URL de devolución de llamada generada que otros servicios pueden usar para llamar al flujo de trabajo de la aplicación lógica y desencadenarla. Esta dirección URL incluye parámetros de consulta que especifican una clave de firma de acceso compartido (SAS), la cual se usa para la autenticación.

    Captura de pantalla que muestra el flujo de trabajo Estándar, el desencadenador de solicitud y la dirección URL de devolución de llamada generada para el punto de conexión.

  5. Para copiar la dirección URL de devolución de llamada, tiene estas opciones:

    • A la derecha del cuadro Dirección URL de HTTP POST, seleccione Copiar dirección URL (icono Copiar archivos).

    • Copie la URL de devolución de llamada de la página de Información general de su flujo de trabajo.

      1. En el menú del flujo de trabajo, seleccione Información general.

      2. En la página Información general, en dirección URL de flujo de trabajo, mueva el puntero sobre la dirección URL y seleccione Copiar en el Portapapeles:

        Captura de pantalla que muestra la página Flujo de trabajo Estándar e Información general con la dirección URL del flujo de trabajo.

  6. Para probar la dirección URL de devolución de llamada y desencadenar el flujo de trabajo, envíe una solicitud HTTP a la dirección URL, incluido el método que espera el desencadenador Solicitud mediante la herramienta de solicitud HTTP y sus instrucciones.

    En este ejemplo, use el método POST con la dirección URL copiada, que es similar al siguiente ejemplo:

    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}

Seleccionar método de solicitud esperado

De manera predeterminada, el desencadenador de solicitud espera una solicitud POST. Sin embargo, puede especificar un método distinto que el autor de la llamada debe usar, pero solo un método.

  1. En el desencadenador de solicitud, abra la lista Parámetros avanzados y seleccione Método, que agrega esta propiedad al desencadenador.

  2. En la lista Método, seleccione el método que el desencadenador debe esperar en su lugar. O bien, puede especificar un método personalizado.

    Por ejemplo, seleccione el método GET para que pueda probar la dirección URL del punto de conexión más adelante.

Pasar parámetros a través de la dirección URL del punto de conexión

Si desea aceptar valores de parámetros a través de la dirección URL del punto de conexión, tiene estas opciones:

  • Acepte valores a través de los parámetros GET o parámetros de URL.

    Estos valores se pasan como pares de nombre-valor en la dirección URL del punto de conexión. Para esta opción, debe usar el método GET en el desencadenador de solicitud. En una acción posterior, puede obtener los valores de parámetro como salidas del desencadenador mediante la función triggerOutputs() en una expresión.

  • Acepte valores a través de una ruta de acceso relativa para los parámetros en el desencadenador de solicitud.

    Estos valores se pasan a través de una ruta de acceso relativa en la dirección URL del punto de conexión. También debe seleccionar explícitamente el método que espera el desencadenador. En una acción posterior, puede obtener los valores de parámetro como salidas del desencadenador al hacer referencia directamente a esas salidas.

Aceptar valores a través de los parámetros GET

  1. En el desencadenador de solicitud, abra Parámetros avanzados, agregue la propiedad Método al desencadenador y seleccione el método GET.

    Para obtener más información, consulte Seleccionar método de solicitud esperado.

  2. En el diseñador, siga estos pasos generales para agregar la acción en la que desea usar el valor del parámetro.

    En este ejemplo, seleccione la acción denominada Respuesta.

  3. Para compilar la expresión triggerOutputs() que recupera el valor de parámetro, siga estos pasos:

    1. En la acción Respuesta, seleccione dentro de la propiedad Cuerpo para que aparezcan las opciones de contenido dinámico (icono de rayo) y el editor de expresiones (icono de fórmula). Seleccione el icono de fórmula para abrir el editor de expresiones.

    2. En el cuadro de expresiones, escriba la expresión siguiente, reemplace parameter-name por el nombre del parámetro y seleccione Aceptar.

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

      Captura de pantalla que muestra el flujo de trabajo Estándar, la acción Respuesta y la expresión triggerOutputs().

      En la propiedad Cuerpo, la expresión se resuelve en el token de triggerOutputs().

      Captura de pantalla que muestra el flujo de trabajo Estándar con la expresión triggerOutputs() resuelta de la acción Respuesta.

      Si guarda el flujo de trabajo, sale del diseñador y vuelve al diseñador, el token muestra el nombre del parámetro especificado, por ejemplo:

      Captura de pantalla que muestra el flujo de trabajo Estándar con la expresión resuelta de la acción Respuesta para el nombre del parámetro.

      En la vista de código, la propiedad Cuerpo aparece en la definición de la acción de respuesta de la manera siguiente:

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

      Por ejemplo, supongamos que desea pasar un valor para un parámetro denominado postalCode. La propiedad Cuerpo especifica la cadena Postal Code: con un espacio al final, seguido de la expresión correspondiente:

      Captura de pantalla que muestra el flujo de trabajo Estándar con la acción Respuesta y la expresión triggerOutputs().

Prueba de su punto de conexión invocable

  1. En el desencadenador de solicitud, copie la dirección URL del flujo de trabajo y pegue la dirección URL en otra ventana del explorador. En la dirección URL, agregue el nombre y el valor del parámetro a la dirección URL con el siguiente formato y presione Entrar.

    ...invoke/{parameter-name}/{parameter-value}?api-version=2022-05-01...

    Por ejemplo:

    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}

    El explorador devuelve una respuesta con este texto: Postal Code: 123456

    Captura de pantalla que muestra el explorador con la respuesta de flujo de trabajo Estándar de la solicitud a la dirección URL de devolución de llamada.

Nota:

Si quiere incluir la almohadilla o numeral ( # ) en el URI, use esta versión codificada en su lugar: %25%23.

Aceptar valores a través de una ruta de acceso relativa

  1. En el desencadenador de solicitud, abra la lista Parámetros avanzados y seleccione Ruta de acceso relativa, que agrega esta propiedad al desencadenador.

    Captura de pantalla que muestra el flujo de trabajo Estándar, el desencadenador de solicitud y la propiedad agregada denominada Ruta de acceso relativa.

  2. En la propiedad Ruta de acceso relativa, especifique la ruta de acceso relativa para el parámetro en el esquema JSON que quiera que acepte la dirección URL, por ejemplo, /address/{postalCode}.

    Captura de pantalla que muestra el valor del parámetro Flujo de trabajo Estándar, Desencadenador de solicitud y Ruta de acceso relativa.

  3. En el desencadenador de solicitud, siga estos pasos generales para agregar la acción en la que quiere usar el valor del parámetro.

    En este ejemplo, agregue la acción Respuesta.

  4. En la propiedad Cuerpo de la acción de respuesta, incluya el token que representa el parámetro especificado en la ruta de acceso relativa del desencadenador.

    Por ejemplo, supongamos que quiere que la acción de respuesta devuelva Postal Code: {postalCode}.

    1. En la propiedad Cuerpo, escriba Postal Code: con un espacio al final. Mantenga el cursor dentro del cuadro de edición para que la lista de contenido dinámico permanezca abierta.

    2. En la lista de contenido dinámico, en la sección Cuando se recibe una solicitud HTTP, seleccione la salida del desencadenador Parámetros de ruta de acceso postalCode.

      Captura de pantalla que muestra el flujo de trabajo Estándar, la acción respuesta y la salida del desencadenador especificada para incluir en el cuerpo de la respuesta.

      La propiedad Cuerpo ahora incluye el parámetro seleccionado:

      Captura de pantalla que muestra el flujo de trabajo estándar y el cuerpo de respuesta de ejemplo con el parámetro.

  5. Guarde el flujo de trabajo.

    En el desencadenador de solicitud, la dirección URL de devolución de llamada se actualiza y ahora incluye la ruta de acceso relativa, por ejemplo:

    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}

  6. Para probar el punto de conexión al que se puede llamar, copie la URL de devolución de llamada actualizada del desencadenador de solicitud, pegue la dirección URL en otra ventana del explorador, reemplace %7BpostalCode%7D en la dirección URL con 123456 y presione Entrar.

    El explorador devuelve una respuesta con este texto: Postal Code: 123456

    Captura de pantalla que muestra el explorador con la respuesta de flujo de trabajo Estándar de la solicitud a la dirección URL de devolución de llamada.

Nota:

Si quiere incluir la almohadilla o numeral ( # ) en el URI, use esta versión codificada en su lugar: %25%23.

Llamada al flujo de trabajo a través del punto de conexión URL

Después de crear el punto de conexión, puede desencadenar el flujo de trabajo mediante el envío de una solicitud HTTPS a la dirección URL completa del punto de conexión. Los flujos de trabajo de Azure Logic Apps tienen compatibilidad integrada con puntos de conexión de acceso directo.

Tokens generados a partir de un esquema

Cuando se proporciona un esquema JSON en el desencadenador de solicitud, el diseñador de flujo de trabajo genera tokens para las propiedades de ese esquema. Después puede usar esos tokens para pasar datos a través del flujo de trabajo.

Por ejemplo, si agrega más propiedades, como "suite", al esquema JSON, los tokens de esas propiedades estarán disponibles para su uso en los pasos posteriores del flujo de trabajo. Este es el 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"
            }
         }
      }
   }
}

Llamada a otros flujos de trabajo

Puede llamar a otros flujos de trabajo que puedan recibir solicitudes anidándolos dentro del flujo de trabajo actual. Para llamar a estos flujos de trabajo, siga estos pasos:

  1. En el diseñador, siga estos pasos generales para agregar la acción Operaciones de flujo de trabajo denominada Invocar un flujo de trabajo en esta aplicación de flujo de trabajo.

    La lista Nombre del flujo de trabajo muestra los flujos de trabajo elegibles para que los seleccione.

  2. En la lista Nombre del flujo de trabajo, seleccione el flujo de trabajo que quiere llamar, por ejemplo:

    Captura de pantalla que muestra el flujo de trabajo Estándar, la acción llamada Invocar un flujo de trabajo en esta aplicación de flujo de trabajo, abrir la lista Nombre del flujo de trabajo y los flujos de trabajo disponibles para llamar.

Referencia al contenido de una solicitud entrante

Si el tipo de contenido de la solicitud entrante es application/json, puede hacer referencia a las propiedades en la solicitud entrante. En caso contrario, este contenido se trata como una sola unidad binaria que se puede pasar a otras API. Para hacer referencia a este contenido dentro del flujo de trabajo de la aplicación lógica, primero debe convertir el contenido.

Por ejemplo, si va a pasar contenido de tipo application/xml, puede usar la expresión @xpath() para realizar una extracción de XPath, o bien puede usar la expresión @json() para convertir XML a JSON. Obtenga más información sobre cómo trabajar con los tipos de contenido admitidos.

Para obtener la salida de una solicitud entrante, puede usar la expresión @triggerOutputs. Por ejemplo, supongamos que tiene un resultado similar al de este ejemplo:

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

Para acceder específicamente a la propiedad body, puede usar la expresión @triggerBody() como un acceso directo.

Respuesta a solicitudes

Es posible que a veces quiera responder a determinadas solicitudes que desencadenan el flujo de trabajo mediante la devolución de contenido al autor de la llamada. Para construir el código de estado, el encabezado y el cuerpo de la respuesta, use la acción de respuesta. Esta acción puede aparecer en cualquier lugar del flujo de trabajo, no solo al final del flujo de trabajo. Si el flujo de trabajo no incluye una acción de respuesta, el punto de conexión responde inmediatamente con un estado 202 - Aceptado.

Para que el autor original de la llamada obtenga la respuesta de forma correcta, todos los pasos necesarios para la respuesta deben terminar dentro del límite del tiempo de espera de la solicitud, a menos que se llame al el flujo de trabajo desencadenado como un el flujo de trabajo anidado. Si no se devuelve ninguna respuesta dentro de este límite, la solicitud entrante agota el tiempo de espera y recibe la respuesta 408 - Tiempo de espera del cliente agotado.

En cuanto a los flujos de trabajo anidados, el flujo de trabajo principal seguirá esperando una respuesta hasta que se completen todos los pasos, independientemente del tiempo que se necesite.

Construcción de la respuesta

En el cuerpo de la respuesta, puede incluir varios encabezados y cualquier tipo de contenido. Por ejemplo, el siguiente encabezado de respuesta especifica que el tipo de contenido de la respuesta es application/json y que el cuerpo contiene valores de las propiedades town y postalCode, en función del esquema JSON descrito anteriormente en este tema para el desencadenador de solicitud.

Captura de pantalla que muestra la acción Respuesta y el tipo de contenido de respuesta.

Las respuestas tienen estas propiedades:

Propiedad (nombre) Propiedad (JSON) Descripción
Código de estado statusCode Código de estado HTTPS que se usará en la respuesta para la solicitud entrante. Este código puede ser cualquier código de estado válido que comience con 2xx, 4xx o 5xx. En cambio, no se permiten códigos de estado 3xx.
Encabezados headers Uno o más encabezados que se incluirán en la respuesta.
Cuerpo body Un objeto de cuerpo que puede ser una cadena, un objeto JSON o incluso contenido binario al que se hace referencia desde un paso anterior.

Para ver la definición JSON de la acción Respuesta y la definición JSON completa de su flujo de trabajo, cambie de la vista de diseñador a la 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": {}
}

Preguntas y respuestas

P: ¿Qué ocurre con la seguridad de direcciones URL para las llamadas entrantes?

R. : Azure genera direcciones URL de devolución de llamada de la aplicación lógica de manera segura con una firma de acceso compartido (SAS). Esta firma pasa como un parámetro de consulta y debe validarse antes de que se pueda ejecutar el flujo de trabajo. Azure genera la firma mediante una combinación única de una clave secreta por aplicación lógica, el nombre del desencadenador y la operación que se realiza. Por tanto, a menos que alguien tenga acceso a la clave de aplicación lógica secreta, no se puede generar una firma válida.

Importante

En sistemas de más alta seguridad y de producción, se recomienda encarecidamente no llamar al flujo de trabajo directamente desde el explorador. Los motivos son estos:

  • La clave de acceso compartido aparece en la dirección URL.
  • No puede administrar directivas de contenido de seguridad debido a los dominios compartidos entre los clientes de Azure Logic Apps.

Para más información sobre la seguridad, la autorización y el cifrado de llamadas entrantes para el flujo de trabajo, como la Seguridad de la capa de transporte (TLS), conocida anteriormente como Capa de sockets seguros (SSL) o la Autenticación abierta de Microsoft Entra ID (Microsoft Entra ID OAuth), exponer el flujo de trabajo de la aplicación lógica con Azure API Management o restringir las direcciones IP que originan las llamadas entrantes, consulte Proteger el acceso y los datos: acceso de las llamadas entrantes a desencadenadores basados en solicitudes.

P: ¿Puedo configurar más puntos de conexión que se puedan llamar?

R. : Sí, los puntos de conexión HTTPS admiten una configuración más avanzada con Azure API Management. Este servicio también ofrece la funcionalidad de administrar de forma coherente todas las API, incluidas las aplicaciones lógicas, configurar nombres de dominio personalizados, usar varios métodos de autenticación y muchas más, como, por ejemplo:

Pasos siguientes