Transferir datos al servicio de backend y desde ese servicio

Cuando un cliente de API hace una solicitud a tu API implementada en API Gateway, puede enviar toda o parte de la siguiente información como parte de la solicitud:

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

Al crear su respuesta a la solicitud de la API, el servicio de backend puede devolver datos al cliente de la API, como los siguientes:

• Encabezados de respuesta
• Cargas útiles XML o JSON

En este documento se describe cómo se transfieren estos datos al servicio de backend y desde ese servicio.

¿Cómo se transfieren los datos de las solicitudes al servicio de backend?

Todos los datos de la solicitud del cliente de la API se transfieren sin cambios al servicio de backend. A continuación, el servicio de backend debe analizar los datos de la solicitud como parte de la gestión de la solicitud.

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

Todos los datos recibidos en la respuesta del servicio de backend se transfieren sin cambios al cliente de la API. A continuación, el cliente de la API debe procesar los datos devueltos en la respuesta.

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

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

Definir la dirección y la ruta 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, se usa la extensión x-google-backend para especificar la URL del servicio backend. Por ejemplo, puede especificar el servicio de backend de la siguiente forma:

Backend	x-google-backend
Cloud Run Functions	x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
Cloud Run	x-google-backend: address: https://hello-HASH.a.run.app
Entorno estándar de App Engine	x-google-backend: address: https://PROJECT_ID.appspot.com

En estos ejemplos:

1. GCP_REGION especifica la Google Cloud región del backend implementado.
2. PROJECT_ID especifica el Google Cloud ID del proyecto.
3. HASH especifica el código hash único que se genera cuando se crea el servicio de Cloud Run.

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

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

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

Cuando API Gateway gestiona una solicitud del cliente de la API, toma la URL de la solicitud enviada por el cliente de la API y la traduce a la URL que se usa para enviar la solicitud al servicio de backend. La forma exacta en que se produce esta traducción depende de la estrategia de traducción de rutas que utilices.

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

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

  La mayoría de los servicios backend usan APPEND_PATH_TO_ADDRESS porque significa que el backend recibe la misma ruta de recurso que la especificada por el cliente de la API.

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

  Este método suele utilizarse en Cloud Run Functions.

Por ejemplo:

• APPEND_PATH_TO_ADDRESS
  • address: https://PROJECT_ID.appspot.com
  • Sin parámetros de ruta de OpenAPI:
    • Ruta de OpenAPI: /hello
    • Ruta del recurso de solicitud de cliente de API: /hello
    • URL de solicitud del servicio de backend: https://PROJECT_ID.appspot.com/hello
  • Con parámetros de ruta de OpenAPI:
    • Ruta de OpenAPI: /hello/{name}
    • Ruta del recurso de solicitud de 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 OpenAPI
    • Ruta de OpenAPI: /hello
    • Ruta del recurso de solicitud de 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 OpenAPI
    • Ruta de OpenAPI: /hello/{name}
    • Ruta del recurso de solicitud de cliente de API: /hello/Dave
    • URL de solicitud del servicio de backend: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

Configurando path_translation

Configura 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 definas 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 tiene el valor predeterminado APPEND_PATH_TO_ADDRESS.

• Cuando se usa x-google-backend en el nivel de operación de la especificación de OpenAPI, path_translation tiene el valor predeterminado CONSTANT_ADDRESS.