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 las solicitudes
Cuando se compila su respuesta a la solicitud a la API, el servicio de backend puede mostrar 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 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 en el cliente de la API se pasan sin cambios al servicio de backend. Luego, el servicio de backend debe analizar los datos de la solicitud como parte del control de la solicitud.
¿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 modificar al cliente de API. El cliente de la API debe procesar los datos que se muestran en la respuesta.
¿Cómo se pasa la URL de la solicitud al servicio de backend?
La extensión x-google-backend
controla la URL que se usa para realizar una solicitud al servicio de backend.
En esta sección, se describen las opciones para configurar la URL del servicio de backend.
Configura la dirección de servicio de backend y la ruta de acceso 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
a fin de especificar la URL del servicio de backend.
Por ejemplo, debes especificar el servicio de backend con este formato:
Backend | x-google-backend |
---|---|
Cloud 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:
- GCP_REGION especifica la región de GCP para el backend implementado.
- PROJECT_ID especifica el ID del proyecto de Google Cloud.
- 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 compatible con la 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
para 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 cuando se agrega la ruta del recurso de la solicitud del cliente a la URLaddress
de la extensiónx-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 del recurso que especifica el cliente de API.CONSTANT_ADDRESS
: La URL del servicio de backend es constante, tal como lo define la URLaddress
de la extensiónx-google-backend
. Si la solicitud del cliente contiene una ruta de acceso al recurso, esta se agrega a la URL del servicio de backend mediante parámetros de consulta.Por lo general, Cloud Functions usa 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 a los recursos de solicitud del cliente de API:
/hello
- URL de solicitud de servicio de backend:
https://PROJECT_ID.appspot.com/hello
- Ruta de acceso de OpenAPI:
- Con parámetros de ruta de acceso de OpenAPI
- Ruta de acceso de OpenAPI:
/hello/{name}
- Ruta de acceso a los recursos de solicitud del cliente de API:
/hello/Dave
- URL de solicitud de servicio de backend:
https://PROJECT_ID.appspot.com/hello/Dave
- Ruta de acceso de OpenAPI:
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 a los recursos de solicitud del cliente de API:
/hello
- URL de solicitud de servicio de backend:
https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
- Ruta de acceso de OpenAPI:
- Con parámetros de ruta de acceso de OpenAPI
- Ruta de acceso de OpenAPI:
/hello/{name}
- Ruta de acceso a los recursos de solicitud del cliente de API:
/hello/Dave
- URL de solicitud de servicio de backend:
https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave
- Ruta de acceso de OpenAPI:
Configura 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 establezcas 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 depath_translation
esAPPEND_PATH_TO_ADDRESS
.Cuando se usa
x-google-backend
en el nivel de operación de la especificación de OpenAPI, el valor predeterminado depath_translation
esCONSTANT_ADDRESS
.