Configurar um proxy com YAML

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

Confira a documentação da Apigee Edge.

É possível definir um proxy de API do Apigee em YAML e implantá-lo com a Google Cloud CLI, como alternativa à criação do pacote de proxy XML tradicional. Você descreve os endpoints, as rotas, as políticas e os destinos de back-end de um proxy em arquivos YAML chamados Modelos de recursos do Apigee, e o Apigee os compila em um pacote de proxy de API padrão para você.

Como o resultado é um pacote comum de proxy de API da Apigee, um proxy criado dessa forma é executado no mesmo ambiente de execução da Apigee, com as mesmas políticas e comportamento de um proxy criado na interface da Apigee ou em um pacote XML.

Por que usar YAML para definir proxies

O formato tradicional de proxy de API do Apigee é um arquivo ZIP de arquivos XML. O YAML oferece uma alternativa que muitos desenvolvedores consideram mais rápida para ler, escrever e revisar, e que funciona bem com ferramentas assistidas por IA e de agentes. Os modelos de recursos da Apigee foram criados para:

  • Desenvolvedores e arquitetos de API que preferem um formato conciso e declarativo e querem manter a configuração do proxy no controle de origem.
  • Profissionais de IA que querem uma maneira padronizada de colocar um gateway do Apigee na frente de um back-end de modelo.
  • Equipes de plataforma e DevOps que querem empacotar partes reutilizáveis da configuração de proxy e aplicá-las de maneira consistente em vários proxies.

Principais conceitos

Os modelos de recursos da Apigee usam três tipos de documentos. Cada um é um arquivo YAML identificado pelo campo type.

Tipo de documento Valor de type Finalidade
Modelo template O ponto de entrada que você implanta. Um modelo compõe um ou mais recursos e define os endpoints e as rotas do proxy.
Recurso feature Uma unidade reutilizável de configuração, como uma verificação de autenticação, um limite de taxa ou um destino de back-end, que você inclui em um modelo. Os recursos contêm as políticas e os recursos.
Proxy proxy O proxy totalmente resolvido que a CLI produz ao compilar um modelo com os recursos dele. Embora normalmente seja uma saída intermediária gerada pela CLI, também é possível importar um arquivo de proxy diretamente para ser traduzido em um pacote de proxy de API.

Você cria modelos e recursos. A Apigee gera o proxy para você durante a compilação.

Como funciona

Ao importar um modelo, a Google Cloud CLI executa as seguintes etapas localmente e faz upload do resultado para o Apigee:

  1. Compilar. A CLI lê seu modelo e os arquivos de recursos referenciados, mescla e produz uma única definição de proxy.
  2. Converter. A CLI converte a definição de proxy em um pacote padrão de proxy de API do Apigee (o ZIP de arquivos XML que o Apigee espera).
  3. Importar. A CLI faz upload do pacote para a Apigee, que cria uma nova revisão do proxy de API.

A importação de um proxy não o ativa. Como uma etapa separada, você implanta a revisão em um ambiente, exatamente como faria com qualquer outro 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 instruções detalhadas, consulte Criar um proxy de API com base em um modelo YAML.

Um exemplo mínimo

O modelo a seguir define um proxy que compõe dois recursos: um que adiciona um destino de back-end e outro que adiciona uma mensagem de resposta:

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 os arquivos de recursos referenciados precisam estar no mesmo diretório do modelo. Para conferir um exemplo completo e executável e os arquivos de recursos que ele usa, consulte Criar um proxy de API com um modelo YAML.

O que você pode fazer

  • Defina endpoints, caminhos de base, rotas, fluxos e destinos de back-end de um proxy em YAML.
  • Empacote políticas e recursos reutilizáveis como recursos e os crie em um modelo.
  • Adicione a autenticação de back-end para destinos do Google Cloud, por exemplo, um token de acesso do Google para um back-end da Vertex AI.
  • Importe um modelo como uma nova revisão de proxy de API com a Google Cloud CLI e implante-o com o comando de implantação padrão.

Limitações

Ao criar modelos e recursos, lembre-se do seguinte:

  • Os recursos são arquivos locais. Um modelo só pode fazer referência a arquivos de recursos que estão no mesmo diretório. Não é possível fazer referência a recursos por URL ou de um catálogo compartilhado.
  • Os valores de parâmetro usam os padrões. Os recursos podem definir parâmetros, mas os valores deles são resolvidos para o padrão definido no recurso. Não há uma flag de linha de comando para substituir os valores de parâmetro no momento da importação.
  • Os parâmetros JSONPath não são compatíveis. Um parâmetro que usa uma expressão paths (JSONPath) causa falha na compilação.
  • Os testes não são aceitos. Uma seção tests é aceita pelo esquema, mas é ignorada e não incluída no pacote gerado.
  • O esquema é estrito. Campos desconhecidos causam um erro. Somente gateway: apigee e schemaVersion: 1.0.0 são aceitos.
  • A solução de problemas usa o XML gerado. A interface e o tempo de execução da Apigee funcionam com o pacote gerado. Não há uma viagem de volta à sua origem YAML na UI.

Próximas etapas