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 de Apigee Edge.

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

Para obtener información general, consulta Configura un proxy con YAML. Para ver 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 la Google Cloud CLI.
  • Tener una organización de Apigee y al menos un entorno Ten en cuenta 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 de la Parte 2 también requiere un entorno Intermedio o Integral (no un entorno Básico); consulta Tipos de entorno de Apigee.
  • Asegúrate de tener los permisos necesarios:
    • Para importar (crear) un proxy de API, se requiere 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 de acceso 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.
  • Un atributo, 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 límite de frecuencia se encuentra 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 tiene las siguientes características:

  • Define una política SpikeArrest que limita la tasa de solicitudes.
  • Usa defaultEndpoint.flows para agregar la política al PreFlow de la 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 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, luego, imprime 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 adjunto 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 consola de Google Cloud , 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 columna Nombres de host.

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

curl https://HOSTNAME/hello

Reemplaza HOSTNAME por el nombre de host que copiaste. El servicio de destino simulado envía una respuesta correcta.

Parte 2: Crea 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. Utiliza 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 el atributo 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 un 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 publican desde el extremo global, que usa un host y un locations/global diferentes:

  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

Dado 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. Proporcionarás esta cuenta de servicio cuando implementes 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 proyecto Google Cloud que tu organización de Apigee. (No se acepta la cuenta de servicio predeterminada de Compute Engine). Para conocer 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 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, ya que 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 de la Parte 1 de dos maneras:

  • Debes proporcionar la cuenta de servicio que creaste en el paso 3. Si realizas la implementación sin uno, esta fallará con un error MISSING_SERVICE_ACCOUNT.
  • Debes realizar la implementación en un entorno intermedio o integral. Este proxy usa una política extensible, que no es compatible con un entorno de Base. Si se implementa en uno, se produce el error Extensible proxy can not be deployed to a base environment. Consulta los 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 conocer los pasos, consulta Implementa un proxy de API.

API de Deployment: Llama a la API de Deployments y pasa la cuenta de servicio como el parámetro de consulta serviceAccount. Reemplaza REVISION por el número de revisión del 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 devuelve de inmediato, ya que 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 incluya 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 para desarrolladores que está asociada con un producto de API que contiene este proxy. Completa las siguientes tareas, que se describen en la 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 que esté asociada con ese producto de API.

El registro de la app genera la clave. Para recuperarla, consulta Cómo ver 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 de acceso base /v1/gemini. Pasa la clave de API en el encabezado x-api-key y envía un cuerpo de solicitud de 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 del paso 6. Una respuesta exitosa es el resultado JSON del modelo. Si se omite la clave, la política de VerifyAPIKey devuelve un error de autorización, lo que confirma que la función de verify-api-key está en vigencia. Para conocer otras formas de pasar una clave, consulta Envía una solicitud con una clave de API válida.

Próximos pasos