Crea un proxy de API a partir de una plantilla YAML

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

Consulta la documentación deApigee Edge.

En esta página, se muestra cómo definir un proxy de API como una plantilla de funciones de Apigee en YAML y cómo implementarlo con la Google Cloud CLI. Primero, compilas un proxy simple y, luego, compilas un ejemplo más completo que se encuentra frente a un modelo de Gemini.

Para obtener información general, consulta Configura un proxy con YAML. Para obtener el esquema completo, consulta la referencia de configuración de YAML del proxy de API .

Antes de comenzar

  • Habilita la API de Vertex AI en tu proyecto de Google Cloud para que el proxy pueda comunicarse con los modelos de Gemini. 
    gcloud services enable aiplatform.googleapis.com
  • Instala y, luego, inicializa el Google Cloud CLI.
  • Para acceder a los comandos que se usan en este instructivo, instala el componente beta de gcloud: 
    gcloud components install beta
  • Ten una organización de Apigee y al menos un entorno. Toma nota de los nombres de la organización y el entorno. En los ejemplos, se usan ORG y ENV como marcadores de posición. La puerta de enlace de IA en la Parte 2 también requiere un entorno intermedio o integral (no un entorno base). Consulta Tipos de entorno de Apigee.
  • Asegúrate de tener los permisos necesarios:
    • Para importar (crear) un proxy de API: el rol de administrador de API (roles/apigee.apiAdmin) o un rol equivalente que otorgue apigee.proxies.create.
    • Para implementar un proxy de API: administrador de entorno (roles/apigee.environmentAdmin) en el entorno de destino, y lector de API (roles/apigee.apiReaderV2) a nivel del proyecto.
    • Para crear el producto de API, el desarrollador y la app que producen la clave de API en la Parte 2, Paso 6: administrador de API (roles/apigee.apiAdmin) y administrador de desarrolladores (roles/apigee.developerAdmin). Para obtener la lista completa de roles, consulta Roles de Apigee.

Parte 1: Crea un proxy de API simple

En esta sección, crearás un proxy que reenvía solicitudes al servicio de destino simulado de Apigee y aplica un límite de frecuencia.

Paso 1: Crea la plantilla

Una plantilla es el archivo que implementas. Define la ruta base, las rutas y el destino de backend de tu proxy, y enumera las funciones que se incluirán.

Crea un directorio para tu proxy y, luego, crea un archivo llamado hello-proxy.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: hello-proxy
type: template
description: A simple proxy to the Apigee mock target, protected by a rate limit.
features:
- spike-arrest.yaml
endpoints:
- name: default
  basePath: /hello
  routes:
  - name: default
    target: default
targets:
- name: default
  url: https://mocktarget.apigee.net

Esta plantilla define lo siguiente:

  • Un extremo con la ruta base /hello. Los clientes llaman al proxy en esta ruta.
  • Una ruta que envía solicitudes al destino llamado default.
  • Un destino que apunta a la URL de backend.
  • Una función, spike-arrest.yaml, que crearás a continuación.

Paso 2: Crea la función

Una función es una unidad de configuración reutilizable que contiene políticas. Una plantilla no puede contener políticas directamente, por lo que la política de limitación de frecuencia reside en una función.

En el mismo directorio que la plantilla, crea un archivo llamado spike-arrest.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: spike-arrest
displayName: Spike Arrest
type: feature
description: Protects the backend by smoothing traffic spikes.
categories:
- traffic
parameters:
- name: RATE
  displayName: RATE
  description: Maximum request rate, for example 30ps (per second) or 100pm (per minute).
  default: 30ps
  examples:
  - 30ps
  - 100pm
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: SA-SpikeArrest
policies:
- name: SA-SpikeArrest
  type: SpikeArrest
  content:
    SpikeArrest:
      metadata:
        name: SA-SpikeArrest
        enabled: "true"
        continueOnError: "false"
      DisplayName: SA-SpikeArrest
      Rate: "{RATE}"

Esta función:

  • Define una política de SpikeArrest que limita la tasa de solicitudes.
  • Usa defaultEndpoint.flows para agregar la política al PreFlow de solicitud, de modo que se ejecute en cada solicitud.
  • Declara un parámetro, RATE, cuyo valor predeterminado (30ps) se sustituye por {RATE} cuando se compila el proxy.

Paso 3: Importa el proxy

Importa la plantilla para crear una revisión del proxy de API. Ejecuta este comando desde el directorio que contiene tus archivos:

gcloud beta apigee apis import hello-proxy \
    --from-template=hello-proxy.yaml \
    --organization=ORG

La CLI compila la plantilla y su función en un paquete de proxy de API, lo sube y muestra la nueva revisión del proxy. La importación crea una revisión, pero no la implementa.

Paso 4: Implementa el proxy

Implementa la revisión en un entorno:

gcloud apigee apis deploy \
    --api=hello-proxy \
    --environment=ENV \
    --organization=ORG

De forma predeterminada, este comando implementa la revisión más reciente. Para implementar una revisión específica, pasa su número como el primer argumento, por ejemplo gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV. Si ya se implementó un proxy diferente en la misma ruta base, agrega --override para reemplazarlo sin tiempo de inactividad.

Paso 5: Llama al proxy

Para llamar al proxy implementado a través de la red, tu entorno debe estar conectado a un grupo de entornos que tenga un nombre de host enrutable. Si acabas de crear tu organización, confirma que esté configurada antes de llamar al proxy. Consulta Acerca de los entornos y los grupos de entornos.

Busca el nombre de host de un grupo de entornos que contenga tu entorno:

  1. En la Google Cloud consola de, ve a Apigee > Administración > Entornos.
  2. Selecciona la pestaña Grupos de entornos.
  3. Busca el grupo de entornos que contiene tu entorno y copia un valor de su Nombres de host columna.

Llama al proxy en ese nombre de host con la ruta base de tu plantilla:

curl https://HOSTNAME/hello

Reemplaza HOSTNAME por el nombre de host que copiaste. Una respuesta correcta proviene del servicio de destino simulado.

Parte 2: Compila una puerta de enlace de IA para Gemini

En esta sección, se compila un proxy más completo: una puerta de enlace de IA que reenvía solicitudes a un modelo de Gemini en Vertex AI, aplica un límite de frecuencia y requiere una clave de API. Usa una plantilla, tres funciones y una cuenta de servicio.

A diferencia del proxy simple de la Parte 1, este proxy llama a un servicio de Google Cloud (Vertex AI). La función gemini-target usa auth: GoogleAccessToken, por lo que Apigee adjunta un token de OAuth de Google a cada solicitud a Vertex AI. Ese token se emite para una cuenta de servicio que creas y, luego, proporcionas cuando implementas el proxy, por lo que esta parte agrega un paso para crear esa cuenta de servicio (Paso 3).

Paso 1: Crea la plantilla

Crea un archivo llamado ai-gateway.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: ai-gateway
type: template
description: AI gateway that fronts a Gemini model with throttling and API key enforcement.
features:
- spike-arrest.yaml
- verify-api-key.yaml
- gemini-target.yaml
endpoints:
- name: gemini
  basePath: /v1/gemini
  routes:
  - name: default
    target: gemini

Paso 2: Crea las funciones

En el mismo directorio, crea los tres archivos de funciones.

Reutiliza la función spike-arrest.yaml de la Parte 1.

Crea verify-api-key.yaml para requerir una clave de API en el encabezado x-api-key:

gateway: apigee
schemaVersion: 1.0.0
name: verify-api-key
displayName: Verify API Key
type: feature
description: Requires a valid API key in the x-api-key request header.
categories:
- security
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: VA-VerifyAPIKey
policies:
- name: VA-VerifyAPIKey
  type: VerifyAPIKey
  content:
    VerifyAPIKey:
      metadata:
        name: VA-VerifyAPIKey
        enabled: "true"
        continueOnError: "false"
      DisplayName: VA-VerifyAPIKey
      APIKey:
        metadata:
          ref: request.header.x-api-key

Crea gemini-target.yaml para enrutar a un modelo de Gemini, autenticado con un token de acceso de Google:

gateway: apigee
schemaVersion: 1.0.0
name: gemini-target
displayName: Gemini Target
type: feature
description: Routes requests to a Gemini model on Vertex AI, authenticated with a Google access token.
categories:
- llm
targets:
- name: gemini
  url: https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent
  auth: GoogleAccessToken
  scopes:
  - https://www.googleapis.com/auth/cloud-platform

Reemplaza PROJECT_ID por el ID de tu proyecto de Google Cloud y REGION por la región de Vertex AI que usas (como us-central1). Esta función usa auth: GoogleAccessToken para que Apigee adjunte un token de acceso de Google a cada solicitud a Vertex AI.

Los modelos no están disponibles en todas las ubicaciones, y la URL depende de la ubicación que uses. La URL anterior es la forma regional, que funciona para un modelo que se entrega desde una región específica, como gemini-2.5-flash en us-central1. Otros modelos solo se entregan desde el extremo global, que usa un host diferente y locations/global:

  url: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL:generateContent

Para encontrar las ubicaciones que admite un modelo, consulta IA generativa en ubicaciones de Vertex AI.

Paso 3: Crea una cuenta de servicio para el proxy

Debido a que la función gemini-target usa auth: GoogleAccessToken, el proxy implementado llama a Vertex AI como una cuenta de servicio. Crea esa cuenta de servicio, otórgale acceso a Vertex AI y permite que el agente de servicio de Apigee la use. Proporcionas esta cuenta de servicio cuando implementas el proxy en el Paso 5. Para obtener más detalles, consulta Usa la autenticación de Google.

  1. Crea una cuenta de servicio administrada por el usuario en el mismo Google Cloud proyecto que tu organización de Apigee. (No se acepta la cuenta de servicio predeterminada de Compute Engine ). Para obtener otras formas de crear una, consulta Crea y administra cuentas de servicio. 
    gcloud iam service-accounts create SA_NAME \
    --project=PROJECT_ID \
    --display-name="Apigee AI gateway"

    Esto crea la cuenta de servicio SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

  2. Otorga a la cuenta de servicio acceso al backend al que llama. Para un destino de Vertex AI, otorga el rol de usuario de Vertex AI (roles/aiplatform.user): 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

    Si la política de IAM de tu proyecto ya contiene vinculaciones de roles condicionales, agrega --condition=None a este comando.

  3. Permite que el agente de servicio de Apigee genere tokens para la cuenta de servicio otorgándole el rol de creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) en la cuenta de servicio: 
    gcloud iam service-accounts add-iam-policy-binding \
    SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --project=PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

    Para encontrar PROJECT_NUMBER, ejecuta gcloud projects describe PROJECT_ID --format='value(projectNumber)'.

Paso 4: Importa el proxy

Importa la plantilla para crear una revisión del proxy de API:

gcloud beta apigee apis import ai-gateway \
    --from-template=ai-gateway.yaml \
    --organization=ORG

Toma nota del número de revisión en el resultado del comando. Lo necesitarás en el Paso 5. Para imprimir solo el número de revisión, agrega --format="value(revision)" al comando de importación.

Paso 5: Implementa el proxy con la cuenta de servicio

La implementación de la puerta de enlace de IA difiere del proxy simple en la Parte 1 de dos maneras:

  • Debes proporcionar la cuenta de servicio que creaste en el Paso 3. Si implementas sin una, la implementación falla y muestra un MISSING_SERVICE_ACCOUNT error.
  • Debes implementar en un entorno intermedio o integral. Este proxy usa una política extensible, que un entorno base no admite. La implementación en uno falla con el error Extensible proxy can not be deployed to a base environment. Consulta Tipos de entorno de Apigee.

IU de Apigee: Implementa el proxy y, cuando se te solicite una cuenta de servicio, ingresa SA_NAME@PROJECT_ID.iam.gserviceaccount.com. Para obtener los pasos, consulta Implementa un proxy de API.

API de implementación: llama a la API de implementaciones y pasa la cuenta de servicio como el parámetro de consulta serviceAccount. Reemplaza REVISION por el número de revisión de Paso 4:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com"

La solicitud de implementación se muestra de inmediato. La implementación es asíncrona. Consulta el estado de implementación de la revisión, que informa PROGRESSING hasta que se convierte en READY:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments"

Cuando se compila el proxy, las funciones spike-arrest y verify-api-key agregan sus políticas al PreFlow de solicitud (primero, la límite de frecuencia y, luego, la verificación de la clave de API), y la función gemini-target agrega el backend de Vertex AI. Una vez que se completa la implementación, el proxy se autentica en Vertex AI como tu cuenta de servicio.

Paso 6: Obtén una clave de API

La función verify-api-key rechaza cualquier solicitud que no contenga una clave de API válida, por lo que necesitas una clave antes de poder llamar al proxy. Una clave de API es una credencial de una app de desarrollador que está asociada con un producto de API que contiene este proxy. Completa las siguientes tareas, que se describen en Descripción general de la publicación:

  1. Crea un producto de API que incluya el proxy ai-gateway y el entorno en el que lo implementaste.
  2. Registra a un desarrollador de apps.
  3. Registra una app de desarrollador asociada con ese producto de API.

El registro de la app genera la clave. Para recuperarla, consulta Visualiza una clave de API y un secreto.

Paso 7: Llama al proxy

Busca el nombre de host de tu grupo de entornos como se describe en la Parte 1, Paso 5, y, luego, llama al proxy en la ruta base /v1/gemini. Pasa la clave de API en el encabezado x-api-key, y envía un cuerpo de solicitud generateContent de Gemini:

curl -X POST https://HOSTNAME/v1/gemini \
    -H "x-api-key: API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"contents":[{"role":"user","parts":[{"text":"Say hello in one sentence."}]}]}'

Reemplaza HOSTNAME por el nombre de host de tu grupo de entornos y API_KEY por la clave de Paso 6. Una respuesta correcta es el resultado JSON del modelo. Si omites la clave, se muestra una falla de autorización de la política VerifyAPIKey, lo que confirma que la función verify-api-key está en efecto. Para obtener otras formas de pasar una clave, consulta Envía una solicitud con una clave de API válida.

Próximos pasos