Transfiere 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:

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

Al crear su respuesta a la solicitud a la API, el servicio de backend puede mostrar datos al cliente de la API, que incluye lo siguiente:

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

En este documento, se describe cómo se pasan estos datos desde y hacia 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, corresponde al servicio de backend analizar los datos de la solicitud como parte del manejo de esta.

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

Todos los datos recibidos en la respuesta del servicio de backend se pasan sin cambios al cliente de la API. Luego, depende del cliente de la API procesar cualquier que se muestran en la respuesta.

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

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

Cómo configurar 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, debes usar la extensión x-google-backend para especificar la URL del servicio de backend. Por ejemplo, puedes especificar el servicio de backend de la siguiente forma:

Backend x-google-backend
Funciones de Cloud Run 
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 región de GCP para el backend implementado.
  2. PROJECT_ID especifica el ID del proyecto de Google Cloud.
  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 en la especificación de OpenAPI especifica el extremo o recurso, compatibles con 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}:

Cómo generar 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 ruta de acceso:

  • APPEND_PATH_TO_ADDRESS: La URL del servicio de backend se genera agregando el Ruta de acceso del recurso de la solicitud del cliente a la URL address de 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 al recurso que especifica el cliente de la API.

  • CONSTANT_ADDRESS: La URL del servicio de backend es constante, tal como lo define la URL address de la extensión x-google-backend. Si la solicitud del cliente contiene una ruta de acceso al recurso, La ruta del recurso se agrega a la URL del servicio de backend mediante 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 del recurso de solicitud del cliente de la 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 la 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 la 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 del recurso de solicitud del cliente de la 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, el valor predeterminado de path_translation es APPEND_PATH_TO_ADDRESS.

  • Cuando x-google-backend se usa a nivel de operación de la especificación de OpenAPI, La configuración predeterminada de path_translation es CONSTANT_ADDRESS.