Configura un proxy con YAML

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Puedes definir un proxy de API de Apigee en YAML y, luego, implementarlo con Google Cloud CLI como alternativa a la creación del paquete tradicional de proxy en XML. En los archivos YAML llamados Plantillas de funciones de Apigee, se describen los extremos, las rutas, las políticas y los destinos de backend de un proxy, y Apigee los compila en un paquete de proxy de API estándar para ti.

Dado que el resultado es un paquete de proxy de API de Apigee común, un proxy que crees de esta manera se ejecutará en el mismo entorno de ejecución de Apigee, con las mismas políticas y el mismo comportamiento que un proxy que crees en la IU de Apigee o desde un paquete XML.

Por qué usar YAML para definir proxies

El formato tradicional del proxy de API de Apigee es un archivo ZIP de archivos XML. YAML ofrece una alternativa que muchos desarrolladores consideran más rápida de leer, escribir y revisar, y que funciona bien con herramientas asistidas por IA y basadas en agentes. Las plantillas de funciones de Apigee están diseñadas para lo siguiente:

  • Desarrolladores y arquitectos de APIs que prefieren un formato conciso y declarativo, y desean mantener la configuración del proxy en el control de origen.
  • Profesionales de la IA que desean una forma estandarizada de colocar una puerta de enlace de Apigee frente a un backend de modelo
  • Equipos de DevOps y de plataforma que desean empaquetar fragmentos reutilizables de configuración de proxy y aplicarlos de manera coherente en muchos proxies.

Conceptos clave

Las plantillas de funciones de Apigee usan tres tipos de documentos. Cada uno es un archivo YAML identificado por su campo type.

Tipo de documento Valor type Objetivo
Plantilla template Es el punto de entrada que implementas. Una plantilla compone una o más funciones y define los extremos y las rutas del proxy.
Función feature Es una unidad de configuración reutilizable, como una verificación de autenticación, un límite de frecuencia o un destino de backend, que se incluye en una plantilla. Las funciones contienen las políticas y los recursos.
Proxy proxy Es el proxy completamente resuelto que produce la CLI cuando compila una plantilla con sus funciones. Si bien suele ser un resultado intermedio que genera la CLI, también puedes importar un archivo de proxy directamente para que se traduzca en un paquete de proxy de API.

Creas plantillas y funciones. Apigee genera el proxy por ti durante la compilación.

Cómo funciona

Cuando importas una plantilla, Google Cloud CLI realiza los siguientes pasos de forma local y, luego, sube el resultado a Apigee:

  1. Compila. La CLI lee tu plantilla y los archivos de funciones a los que hace referencia, los combina y genera una sola definición de proxy.
  2. Convertir La CLI convierte la definición del proxy en un paquete estándar de proxy de API de Apigee (el archivo ZIP de archivos XML que espera Apigee).
  3. Importar: La CLI sube el paquete a Apigee, que crea una nueva revisión del proxy de API.

Importar un proxy no lo activa. Como paso independiente, implementa la revisión en un entorno, exactamente igual que lo harías con cualquier otro proxy de API:

YAML template + feature files
  |  gcloud apigee apis import --from-template
  v
API proxy revision   (created, not yet serving traffic)
  |  gcloud apigee apis deploy
  v
Deployed proxy       (serving traffic in an environment)

Para obtener instrucciones paso a paso, consulta Crea un proxy de API a partir de una plantilla de YAML.

Un ejemplo mínimo

La siguiente plantilla define un proxy que compone dos atributos: uno que agrega un destino de backend y otro que agrega un mensaje de respuesta:

gateway: apigee
schemaVersion: 1.0.0
name: HelloWorld-v1
type: template
description: API proxy for HelloWorld-v1
features:
- proxy-apigeemock.yaml
- response-helloworld.yaml

Todos los archivos de funciones a los que se hace referencia deben estar en el mismo directorio que la plantilla. Para ver un ejemplo completo y ejecutable, y los archivos de funciones que usa, consulta Crea un proxy de API a partir de una plantilla YAML.

Qué puedes hacer

  • Define los extremos, las rutas base, las rutas, los flujos y los destinos de backend de un proxy en YAML.
  • Empaqueta políticas y recursos reutilizables como funciones y compónlos en una plantilla.
  • Agrega autenticación de backend para los destinos de Google Cloud (por ejemplo, un token de acceso de Google para un backend de Vertex AI).
  • Importa una plantilla como una nueva revisión del proxy de API con Google Cloud CLI y, luego, impleméntala con el comando de implementación estándar.

Limitaciones

Ten en cuenta lo siguiente cuando crees plantillas y funciones:

  • Las funciones son archivos locales. Una plantilla solo puede hacer referencia a archivos de funciones que se encuentren en el mismo directorio. No se admite la referencia a funciones por URL ni desde un catálogo compartido.
  • Los valores de los parámetros usan sus valores predeterminados. Las funciones pueden definir parámetros, pero los valores de los parámetros se resuelven en el valor predeterminado definido en la función. No hay ninguna marca de línea de comandos para anular los valores de los parámetros en el momento de la importación.
  • No se admiten los parámetros de JSONPath. Un parámetro que usa una expresión paths (JSONPath) hace que falle la compilación.
  • No se admiten las pruebas. El esquema acepta una sección tests, pero se ignora y no se incluye en el paquete generado.
  • El esquema es estricto. Los campos desconocidos provocan un error. Solo se admiten gateway: apigee y schemaVersion: 1.0.0.
  • La solución de problemas usa el XML generado. La IU y el tiempo de ejecución de Apigee funcionan con el paquete generado. No hay un viaje de ida y vuelta a tu fuente YAML en la IU.

Próximos pasos