Pasar datos hacia y desde el servicio de backend

Cuando un cliente de API realiza una solicitud a la API implementada en API Gateway, el cliente puede pasar toda la siguiente información, como parte, de la solicitud:

• Encabezados de la solicitud
• Parámetros de consulta
• Datos de formulario
• Cargas útiles de XML o JSON
• Rutas de solicitud

Cuando se compila la respuesta a la solicitud a la API, el servicio de backend puede devolver datos al cliente de API, incluidos los siguientes:

• Encabezados de respuesta
• Cargas útiles de XML o JSON

En este documento, se describe cómo se pasan estos datos hacia y desde el servicio de backend.

¿Cómo se pasan los datos de solicitud al servicio de backend?

Todos los datos de la solicitud del cliente de API se pasan sin cambios al servicio de backend. Luego, el servicio de backend debe analizar los datos de la solicitud como parte de su procesamiento.

¿Cómo se devuelven los datos de respuesta al cliente de API?

Todos los datos que se reciben en la respuesta del servicio de backend se pasan sin cambios al cliente de API. Luego, el cliente de API debe procesar los datos que se devuelven en la respuesta.

¿Cómo se pasa la URL de la solicitud al servicio de backend?

La URL que se usa para realizar una solicitud al servicio de backend se controla con la extensión x-google-backend. En esta sección, se describen las opciones para configurar la URL del servicio de backend.

Establece la dirección y la ruta de acceso del servicio de backend en la especificación de OpenAPI

En la especificación de OpenAPI que usas para crear una configuración de API, usas la extensión x-google-backend para especificar la URL del servicio de backend. Por ejemplo, especifica el servicio de backend de la siguiente manera:

Backend	x-google-backend
Cloud Run Functions	x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
Cloud Run	Uno de los siguientes: x-google-backend: address: APP_URL x-google-backend: address: DETERMINISTIC_URL
Entorno estándar de App Engine	x-google-backend: address: https://PROJECT_ID.appspot.com

En estos ejemplos, sucede lo siguiente:

• APP_URL especifica la URL real de tu servicio de Cloud Run (la ruta de acceso completa de la API a la que se llama), también conocida como la URL no determinista. Por ejemplo: https://hello-abc1def2gh-uc.a.run.app.
• DETERMINISTIC_URL es la URL determinística del backend de tu servicio de Cloud Run.

Nota: Si planeas usar la URL determinística para controlar las versiones del backend del servicio de Cloud Run, debes especificar una de las siguientes opciones:

• OpenAPI 2.0: campo jwt_audience junto a address en la sección x-google-backend
• OpenAPI 3.x: Campo jwtAudience junto con address en la definición del backend en x-google-api-management.backends

Establece el campo jwt_audience o jwtAudience en el nombre de host del servicio de Cloud Run. Por ejemplo, para OpenAPI 2.0:

...
  x-google-backend:
      address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
      jwt_audience: https://SERVICE_HOSTNAME
...

Si el campo jwt_audience o jwtAudience no está presente, el campo se establece de forma predeterminada en el valor del campo address para la reclamación de público del JWT. Esto puede generar una reclamación de público de JWT inesperada para Cloud Run si se usa la URL de la etiqueta de revisión para address y no se especifica jwt_audience ni jwtAudience.

Además, el parámetro path en la especificación de OpenAPI indica el extremo o recurso que admite tu API. Puedes especificar una ruta de acceso absoluta o una que use parámetros de ruta de acceso:

Ruta	Ruta con parámetros
paths: /hello:	paths: /hello/{name}:

Genera la URL del servicio de backend a partir de una solicitud a la API

Como API Gateway controla una solicitud del cliente de API, toma la URL de la solicitud que envía el cliente de la API y la traduce a la URL que se usa para realizar la solicitud al servicio de backend. La forma exacta en la que ocurre esta traducción depende de la estrategia de traducción de ruta de acceso que uses.

La opción path_translation de la extensión x-google-backend admite dos estrategias de traducción de rutas de acceso:

• APPEND_PATH_TO_ADDRESS: La URL del servicio de backend se genera agregando la ruta de acceso del recurso de la solicitud del cliente a la URL de address de la extensión x-google-backend.

  La mayoría de los servicios de backend usan APPEND_PATH_TO_ADDRESS porque significa que el backend recibe la misma ruta de acceso de recursos que especifica el cliente de API.

• CONSTANT_ADDRESS: La URL del servicio de backend es constante, como se define en la URL address de la extensión x-google-backend. Si la solicitud del cliente contiene una ruta de acceso al recurso, esta se agrega a la URL del servicio de backend con parámetros de consulta.

  Por lo general, las funciones de Cloud Run usan este método.

Por ejemplo:

• APPEND_PATH_TO_ADDRESS
  • address: https://PROJECT_ID.appspot.com
  • Sin parámetros de ruta de acceso de OpenAPI
    • Ruta de acceso de OpenAPI: /hello
    • Ruta de acceso del recurso de la solicitud del cliente de API: /hello
    • URL de solicitud del servicio de backend: https://PROJECT_ID.appspot.com/hello
  • Con parámetros de ruta de acceso de OpenAPI
    • Ruta de acceso de OpenAPI: /hello/{name}
    • Ruta de acceso del recurso de la solicitud del cliente de API: /hello/Dave
    • URL de solicitud del servicio de backend: https://PROJECT_ID.appspot.com/hello/Dave
• CONSTANT_ADDRESS
  • address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  • Sin parámetros de ruta de acceso de OpenAPI
    • Ruta de acceso de OpenAPI: /hello
    • Ruta de acceso del recurso de la solicitud del cliente de API: /hello
    • URL de solicitud del servicio de backend: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  • Con parámetros de ruta de acceso de OpenAPI
    • Ruta de acceso de OpenAPI: /hello/{name}
    • Ruta de acceso del recurso de la solicitud del cliente de API: /hello/Dave
    • URL de solicitud del servicio de backend: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

Configura path_translation

Establece path_translation como parte de la configuración de x-google-backend:

x-google-backend:
  address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]`

El valor predeterminado de path_translation depende de dónde configures x-google-backend en tu especificación de OpenAPI:

• Cuando se usa x-google-backend en el nivel superior de la especificación de OpenAPI, path_translation se establece de forma predeterminada en APPEND_PATH_TO_ADDRESS.

• Cuando se usa x-google-backend en el nivel de operación de la especificación de OpenAPI, path_translation se establece de forma predeterminada en CONSTANT_ADDRESS.