Criar um proxy de API com um modelo YAML

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Nesta página, mostramos como definir um proxy de API como um modelo de recurso da Apigee em YAML e implantá-lo com a Google Cloud CLI. Primeiro, crie um proxy simples e depois um exemplo mais completo que fique na frente de um modelo do Gemini.

Para mais informações, consulte Configurar um proxy com YAML. Para o esquema completo, consulte Referência de configuração YAML do proxy de API.

Antes de começar

  • Ative a API Vertex AI no seu projeto na nuvem do Google Cloud para que o proxy possa se comunicar com os modelos do Gemini. 
    gcloud services enable aiplatform.googleapis.com
  • Instale e inicialize a Google Cloud CLI.
  • Ter uma organização da Apigee e pelo menos um ambiente. Observe os nomes da organização e do ambiente. Os exemplos usam ORG e ENV como marcadores de posição. O gateway de IA na Parte 2 também exige um ambiente Intermediário ou Completo (não um ambiente Básico). Consulte Tipos de ambiente da Apigee.
  • Verifique se você tem as permissões necessárias:
    • Para importar (criar) um proxy de API: o papel Administrador de API (roles/apigee.apiAdmin) ou um papel equivalente que conceda apigee.proxies.create.
    • Para implantar um proxy de API: Administrador do ambiente (roles/apigee.environmentAdmin) no ambiente de destino e Leitor de API (roles/apigee.apiReaderV2) no nível do projeto.
    • Para criar o produto da API, o desenvolvedor e o app que produzem a chave de API na Parte 2, Etapa 6: Administrador de API (roles/apigee.apiAdmin) e Administrador de desenvolvedor (roles/apigee.developerAdmin). Para conferir a lista completa de papéis, consulte Funções da Apigee.

Parte 1: criar um proxy de API simples

Nesta seção, você vai criar um proxy que encaminha solicitações para o serviço de destino simulado da Apigee e impõe um limite de taxa.

Etapa 1: criar o modelo

Um modelo é o arquivo que você implanta. Ele define o caminho base, as rotas e o destino de back-end do proxy, além de listar os recursos a serem incluídos.

Crie um diretório para seu proxy e um arquivo chamado 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

Este modelo define:

  • Um endpoint com o caminho base /hello. Os clientes chamam o proxy nesse caminho.
  • Uma rota que envia solicitações para o destino chamado default.
  • Um destino que aponta para o URL do back-end.
  • Um recurso, spike-arrest.yaml, que você vai criar em seguida.

Etapa 2: criar o recurso

Um recurso é uma unidade reutilizável de configuração que contém políticas. Um modelo não pode conter políticas diretamente. Por isso, a política de limitação de taxa fica em um recurso.

No mesmo diretório do modelo, crie um arquivo chamado 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}"

O recurso:

  • Define uma política SpikeArrest que limita a taxa de solicitações.
  • Usa defaultEndpoint.flows para adicionar a política ao PreFlow de solicitação, para que ela seja executada em todas as solicitações.
  • Declara um parâmetro, RATE, cujo padrão (30ps) é substituído por {RATE} quando o proxy é compilado.

Etapa 3: importar o proxy

Importe o modelo para criar uma revisão do proxy de API. Execute este comando no diretório que contém seus arquivos:

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

A CLI compila o modelo e o recurso em um pacote de proxy de API, faz o upload e imprime a nova revisão do proxy. A importação cria uma revisão, mas não a implanta.

Etapa 4: implantar o proxy

Implante a revisão em um ambiente:

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

Por padrão, esse comando implanta a revisão mais recente. Para implantar uma revisão específica, transmita o número dela como o primeiro argumento. Por exemplo, gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV. Se um proxy diferente já estiver implantado no mesmo caminho base, adicione --override para substituí-lo sem tempo de inatividade.

Etapa 5: chamar o proxy

Para chamar o proxy implantado pela rede, seu ambiente precisa estar anexado a um grupo de ambiente com um nome do host roteável. Se você acabou de criar sua organização, confirme se ela está configurada antes de chamar o proxy. Consulte Sobre ambientes e grupos de ambientes.

Encontre o nome do host de um grupo de ambientes que contém seu ambiente:

  1. No console Google Cloud , acesse Apigee > Gerenciamento > Ambientes.
  2. Selecione a guia Grupos de ambientes.
  3. Encontre o grupo de ambientes que contém seu ambiente e copie um valor da coluna Nomes de host.

Chame o proxy nesse nome de host usando o caminho base do seu modelo:

curl https://HOSTNAME/hello

Substitua HOSTNAME pelo nome do host que você copiou. Uma resposta bem-sucedida vem do serviço de destino simulado.

Parte 2: criar um gateway de IA para o Gemini

Esta seção cria um proxy mais completo: um gateway de IA que encaminha solicitações para um modelo do Gemini na Vertex AI, aplica um limite de taxa e exige uma chave de API. Ele usa um modelo, três recursos e uma conta de serviço.

Ao contrário do proxy simples da Parte 1, este proxy chama um serviço do Google Cloud (Vertex AI). O recurso gemini-target usa auth: GoogleAccessToken. Por isso, o Apigee anexa um token do Google OAuth a cada solicitação para a Vertex AI. Esse token é emitido para uma conta de serviço que você cria e fornece ao implantar o proxy. Portanto, esta parte adiciona uma etapa para criar essa conta de serviço (Etapa 3).

Etapa 1: criar o modelo

Crie um arquivo chamado 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

Etapa 2: criar os recursos

No mesmo diretório, crie os três arquivos de recursos.

Reutilize o recurso spike-arrest.yaml da Parte 1.

Crie verify-api-key.yaml para exigir uma chave de API no cabeçalho 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

Crie gemini-target.yaml para encaminhar a um modelo do Gemini, autenticado com um token de acesso do 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

Substitua PROJECT_ID pelo ID do projeto do Google Cloud e REGION pela região da Vertex AI que você está usando (como us-central1). Esse recurso usa auth: GoogleAccessToken para que o Apigee anexe um token de acesso do Google a cada solicitação à Vertex AI.

Os modelos não estão disponíveis em todos os locais, e o URL depende do local usado. O URL anterior é a forma regional, que funciona para um modelo veiculado em uma região específica, como gemini-2.5-flash em us-central1. Outros modelos são fornecidos apenas pelo endpoint global, que usa um host e locations/global diferentes:

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

Para saber quais locais um modelo oferece suporte, consulte Locais da IA generativa na Vertex AI.

Etapa 3: criar uma conta de serviço para o proxy

Como o recurso gemini-target usa auth: GoogleAccessToken, o proxy implantado chama a Vertex AI como uma conta de serviço. Crie essa conta de serviço, conceda acesso à Vertex AI e permita que o agente de serviço do Apigee a use. Você fornece essa conta de serviço ao implantar o proxy na Etapa 5. Para mais detalhes, consulte Como usar a autenticação do Google.

  1. Crie uma conta serviço gerenciado pelo usuário no mesmo projeto Google Cloud da sua organização da Apigee. (A conta de serviço padrão do Compute Engine não é aceita.) Para outras maneiras de criar uma, consulte Como criar e gerenciar contas de serviço. 
    gcloud iam service-accounts create SA_NAME \
    --project=PROJECT_ID \
    --display-name="Apigee AI gateway"

    Isso cria a conta de serviço SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

  2. Conceda à conta de serviço acesso ao back-end que ela chama. Para um destino da Vertex AI, conceda o papel de Usuário da 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"

    Se a política do IAM do projeto já tiver vinculações de papéis condicionais, adicione --condition=None a esse comando.

  3. Permita que o agente de serviço do Apigee crie tokens para a conta de serviço concedendo a ele o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) na conta de serviço: 
    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, execute gcloud projects describe PROJECT_ID --format='value(projectNumber)'.

Etapa 4: importar o proxy

Importe o modelo para criar uma revisão do proxy de API:

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

Anote o número da revisão na resposta ao comando. Você vai precisar dele na etapa 5. Para imprimir apenas o número da revisão, adicione --format="value(revision)" ao comando de importação.

Etapa 5: implante o proxy com a conta de serviço

A implantação do gateway de IA difere do proxy simples na Parte 1 de duas maneiras:

  • Informe a conta de serviço que você criou na Etapa 3. Se você fizer a implantação sem um, ela vai falhar com um erro MISSING_SERVICE_ACCOUNT.
  • É necessário implantar em um ambiente intermediário ou abrangente. Esse proxy usa uma política extensível, que um ambiente Base não suporta. A implantação em um deles falha com o erro Não é possível implantar um proxy extensível em um ambiente de base. Consulte Tipos de ambiente da Apigee.

Interface da Apigee:implante o proxy e, quando solicitado a informar uma conta de serviço, insira SA_NAME@PROJECT_ID.iam.gserviceaccount.com. Para ver as etapas, consulte Como implantar um proxy de API.

API Deployment:chame a API deployments, transmitindo a conta de serviço como o parâmetro de consulta serviceAccount. Substitua REVISION pelo número da revisão da Etapa 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"

A solicitação de implantação retorna imediatamente, mas a implantação é assíncrona. Pesquise o status de implantação da revisão, que informa PROGRESSING até que ele seja 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"

Quando o proxy é compilado, os recursos spike-arrest e verify-api-key adicionam as políticas deles ao pré-fluxo de solicitação (primeiro a limitação de taxa e depois a verificação da chave de API), e o recurso gemini-target adiciona o back-end da Vertex AI. Depois que a implantação for concluída, o proxy fará a autenticação na Vertex AI como sua conta de serviço.

Etapa 6: gerar uma chave de API

O recurso verify-api-key rejeita qualquer solicitação que não tenha uma chave de API válida. Portanto, você precisa de uma chave antes de chamar o proxy. Uma chave de API é uma credencial de um app de desenvolvedor associada a um produto de API que contém esse proxy. Conclua as tarefas a seguir, que são descritas em Visão geral da publicação:

  1. Crie um produto de API que inclua o proxy ai-gateway e o ambiente em que ele foi implantado.
  2. Registrar um desenvolvedor de apps.
  3. Registre um app de desenvolvedor associado a esse produto de API.

O registro do app gera a chave. Para recuperá-lo, consulte Como ver uma chave de API e um secret.

Etapa 7: chamar o proxy

Encontre o nome do host do grupo de ambientes, conforme descrito na Parte 1, Etapa 5, e chame o proxy no caminho base /v1/gemini. Transmita a chave de API no cabeçalho x-api-key e envie um corpo de solicitação generateContent do 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."}]}]}'

Substitua HOSTNAME pelo nome do host do grupo de ambiente e API_KEY pela chave da Etapa 6. Uma resposta bem-sucedida é a saída JSON do modelo. Omitir a chave retorna uma falha de autorização da política VerifyAPIKey, o que confirma que o recurso verify-api-key está em vigor. Para outras maneiras de transmitir uma chave, consulte Enviar uma solicitação com uma chave de API válida.

Próximas etapas