Criar um proxy de API com um modelo YAML

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

Confira Apigee Edge documentação.

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, você cria um proxy simples e, em seguida, um exemplo mais completo que representa um modelo do Gemini.

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

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.
  • Para acessar os comandos usados neste tutorial, instale o componente gcloud beta: 
    gcloud components install beta
  • Tenha uma organização da Apigee e pelo menos um ambiente. Anote os nomes da organização e do ambiente. Os exemplos usam ORG e ENV como marcadores. 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 de ambiente (roles/apigee.environmentAdmin) no ambiente de destino e Leitor de API (roles/apigee.apiReaderV2) no nível do projeto.
    • Para criar o produto de API, o desenvolvedor e o app que produzem a chave de API em 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 Papéis da Apigee.

Parte 1: criar um proxy de API simples

Nesta seção, você cria um proxy que encaminha solicitações para o serviço de destino simulado da Apigee e aplica 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 e lista os recursos a serem incluídos.

Crie um diretório para o proxy e, em seguida, crie 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

Esse 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 de back-end.
  • Um recurso, spike-arrest.yaml, que você cria em seguida.

Etapa 2: criar o recurso

Um recurso é uma unidade de configuração reutilizável que contém políticas. Um modelo não pode conter políticas diretamente, então 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ção.
  • 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 de proxy de API. Execute este comando no diretório que contém seus arquivos:

gcloud beta 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 de 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 ambientes que tenha um nome de 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 Google Cloud console, 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 modelo:

curl https://HOSTNAME/hello

Substitua HOSTNAME pelo nome do host copiado. 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 na Parte 1, esse proxy chama um serviço do Google Cloud (Vertex AI). O recurso gemini-target usa auth: GoogleAccessToken, então a Apigee anexa um token OAuth do Google 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, essa 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 de 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 rotear para 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 na nuvem 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 a Apigee anexe um token de acesso do Google a cada solicitação para a Vertex AI.

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

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

Para encontrar os locais compatíveis com um modelo, consulte IA generativa em locais da 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 da 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 Google Cloud projeto 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 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á contiver vinculações de papéis condicionais, adicione --condition=None a esse comando.

  3. Permita que o agente de serviço da Apigee crie tokens para a conta de serviço concedendo a ela o papel 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 de proxy de API:

gcloud beta 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: implantar o proxy com a conta de serviço

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

  • É necessário fornecer a conta de serviço criada na Etapa 3. Se você implantar sem uma, a implantação vai falhar com um MISSING_SERVICE_ACCOUNT erro.
  • É necessário implantar em um ambiente intermediário ou completo. Esse proxy usa uma política extensível, que um ambiente básico não oferece suporte. A implantação em um deles falha com o erro O proxy extensível não pode ser implantado em um ambiente básico. Consulte Apigee tipos de ambiente.

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

API de implantação: chame a API de implantações, 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 é retornada imediatamente. A implantação é assíncrona. Pesquise o status de implantação da revisão, que informa PROGRESSING até que se torne 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 ao PreFlow de solicitação (limitação de taxa primeiro e, em seguida, 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 será autenticado 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 associado 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 você o implantou.
  2. Registre 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á-la, 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 em 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 do Gemini generateContent:

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 ambientes e API_KEY pela chave da Etapa 6. Uma resposta bem-sucedida é a saída JSON do modelo. A omissão da chave retorna uma falha de autorização da política VerifyAPIKey, que confirma que o recurso verify-api-key está em vigor. Para outras maneiras de transmitir uma chave, consulte Como enviar uma solicitação com uma chave de API válida.

Próximas etapas