Referência de configuração YAML do proxy de API

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

Confira a documentação da Apigee Edge.

Esta página descreve o formato YAML para modelos de recursos da Apigee: os tipos de documentos template, feature e proxy e todos os campos deles. Para uma introdução conceitual, consulte Configurar um proxy com YAML. Para um tutorial, consulte Criar um proxy de API com um modelo YAML.

Convenções

  • Os nomes de campo usam camelCase. Por exemplo, schemaVersion, basePath, displayName, faultRules, defaultFaultRule, httpTargetConnection.
  • O esquema é restrito. Campos desconhecidos causam um erro ao importar o arquivo.
  • Campos obrigatórios. Somente gateway e schemaVersion são validados quando um arquivo é analisado. Outros campos marcados como Sim nas tabelas a seguir são necessários na prática para produzir um proxy de API funcional.

Campos comuns de nível superior

Todos os documentos template, feature e proxy começam com os seguintes campos.

Nome Descrição Padrão Obrigatório?
gateway O gateway de destino. Precisa ser apigee. N/A Sim
schemaVersion A versão do esquema do documento. Precisa ser 1.0.0. N/A Sim
name O nome do documento. Para um modelo ou proxy, esse é o nome do proxy de API gravado no pacote. N/A Sim
type O tipo de documento: template, feature ou proxy. N/A Sim
description Uma descrição legível. N/A Não
priority Um número inteiro que controla a ordem em que os recursos são aplicados durante a compilação. Os números menores são aplicados primeiro. 100 Não

Tipo de documento: modelo

Um modelo é o ponto de entrada que você importa. Ele compõe recursos e define os endpoints e as rotas do proxy. Um modelo não contém políticas nem recursos. Eles vêm dos recursos que ele referencia.

Nome Descrição Padrão Obrigatório?
features Uma lista de nomes de arquivos de recursos para compor no proxy. Cada nome precisa ser resolvido para um arquivo no mesmo diretório do modelo. [] Não
parameters Uma lista de valores de parâmetro que fornecem padrões para os recursos. [] Não
endpoints Uma lista de endpoints que definem caminhos e rotas básicos. [] Não
targets Uma lista de destinos que definem conexões de back-end. [] Não

Tipo de documento: recurso

Um recurso é uma unidade reutilizável de configuração que você inclui em um modelo. Um recurso contém políticas e recursos e pode contribuir com fluxos, endpoints e destinos para o proxy compilado. Além dos campos comuns de nível superior, um recurso tem os seguintes campos.

Nome Descrição Padrão Obrigatório?
displayName Um nome de exibição legível. N/A Não
uid Um identificador exclusivo usado para criar namespaces das políticas e dos recursos do recurso. Se não for definido, name será usado. N/A Não
documentation Documentação estendida para o recurso. N/A Não
categories Uma lista de rótulos de categoria de formato livre. [] Não
parameters Uma lista de parâmetros definidos pelo recurso. [] Não
defaultEndpoint Um endpoint de proxy cujos fluxos e regra de falha padrão são mesclados em todos os endpoints do proxy compilado. Use isso para anexar as políticas de um recurso ao fluxo de solicitação ou resposta. N/A Não
defaultTarget Um destino de proxy usado como uma conexão de back-end padrão. N/A Não
endpoints Uma lista de endpoints de proxy a serem adicionados ao proxy. Um endpoint com o mesmo nome de um endpoint existente o substitui. [] Não
targets Uma lista de destinos de proxy a serem adicionados ao proxy. Um grupo com o mesmo nome de um grupo atual o substitui. [] Não
policies Uma lista de políticas fornecidas pelo recurso. Os nomes das políticas são prefixados automaticamente com o uid (ou name) do recurso durante a compilação. [] Não
resources Uma lista de recursos que o recurso oferece, como arquivos JavaScript ou de propriedades. [] Não

Tipo de documento: procuração

Um proxy é o documento totalmente resolvido que a CLI produz ao compilar um modelo com seus recursos. Normalmente, você não cria esse tipo diretamente. Ele é descrito aqui porque é a forma que se torna o pacote de proxy de API.

Um proxy tem os mesmos campos que um recurso, exceto que ele usa endpoints e targets (não defaultEndpoint ou defaultTarget) e sempre representa um proxy completo e implantável. O type é proxy.

Objetos aninhados

parâmetro

Um parâmetro fornece um valor a um recurso. O valor de um parâmetro é resolvido como o default dele.

Nome Descrição Padrão Obrigatório?
name O nome do parâmetro. Referenciado no conteúdo do recurso como {name}. N/A Sim
displayName Um nome legível. N/A Não
description Uma descrição do parâmetro. N/A Não
default O valor padrão. Substituído por {name} nas strings do recurso. N/A Não
examples Uma lista de valores de exemplo. [] Não
maps Um mapa de substituições de valores. Se o valor resolvido for uma chave no mapa, ele será substituído pelo valor mapeado. N/A Não
paths Uma lista de expressões JSONPath. Não compatível com esta versão: o uso causa um erro. N/A Não

endpoint

Usado na lista endpoints de um modelo.

Nome Descrição Padrão Obrigatório?
name O nome do endpoint. N/A Sim
basePath O caminho base que os clientes usam para chamar o proxy, por exemplo, /v1/gemini. N/A Não
routes Uma lista de rotas que mapeiam solicitações para destinos. [] Não

proxyEndpoint

Usado no defaultEndpoint e no endpoints de um recurso e em um proxy compilado. Estende o endpoint com o processamento de fluxo.

Nome Descrição Padrão Obrigatório?
flows Uma lista de fluxos. Fluxos chamados PreFlow ou PostFlow são mapeados para o fluxo correspondente da Apigee. Qualquer outro nome é colocado no contêiner de fluxos genéricos. [] Não
postClientFlow Um único fluxo que é executado depois que a resposta é enviada ao cliente. N/A Não
faultRules Uma lista de fluxos usados como regras de falha. [] Não
defaultFaultRule Uma regra de falha que é executada quando nenhuma outra regra de falha corresponde. N/A Não

route

Nome Descrição Padrão Obrigatório?
name O nome da rota. N/A Sim
target O nome do endpoint de destino para onde rotear. N/A Não
condition Uma condição que precisa ser verdadeira para que essa rota seja aplicada. N/A Não

Fluxo

Nome Descrição Padrão Obrigatório?
name O nome do fluxo. Use PreFlow ou PostFlow para os fluxos padrão de solicitação/resposta. N/A Sim
mode Request ou Response. Determina se as etapas são executadas na solicitação ou na resposta. Request Não
condition Uma condição que precisa ser verdadeira para que o fluxo seja executado. N/A Não
steps Uma lista ordenada de etapas (invocações de política). [] Não

etapa

Uma etapa executa uma política em um fluxo.

Nome Descrição Padrão Obrigatório?
name O nome da política a ser executada. Em um recurso, use o nome local da política. O compilador o reescreve para o nome com namespace. N/A Sim
condition Uma condição que precisa ser verdadeira para a etapa ser executada. N/A Não

faultRule

Estende flow com um campo adicional.

Nome Descrição Padrão Obrigatório?
alwaysEnforce Se true, a regra de falha padrão sempre será aplicada. false Não

destino

Usado na lista targets de um modelo.

Nome Descrição Padrão Obrigatório?
name O nome do destino. Referenciado pelo target de uma rota. N/A Sim
url O URL do back-end. N/A Não
auth O esquema de autenticação de um back-end do Google Cloud, por exemplo, GoogleAccessToken ou GoogleIDToken. N/A Não
scopes Uma lista de escopos do OAuth a serem solicitados. Aplicável quando auth está definido. [] Não
aud O público-alvo do token. Aplicável quando auth está definido. N/A Não

proxyTarget

Usado em defaultTarget e targets de um recurso e em um proxy compilado. Estende target com processamento de fluxo e substituições de conexão bruta.

Nome Descrição Padrão Obrigatório?
flows Uma lista de fluxos que são executados na solicitação ou resposta de destino. [] Não
faultRules Uma lista de fluxos usados como regras de falha. [] Não
defaultFaultRule Uma regra de falha. N/A Não
httpTargetConnection Uma representação bruta do elemento HTTPTargetConnection para configuração avançada. Se definido, ele terá precedência sobre url, auth, scopes e aud. N/A Não
localTargetConnection Uma representação bruta de um elemento LocalTargetConnection. Se definido, ele terá precedência sobre uma conexão HTTP. N/A Não

política

Uma política é definida em um recurso. A configuração é escrita em content usando a convenção de atributo/texto descrita em Convenção de conteúdo da política.

Nome Descrição Padrão Obrigatório?
name O nome da política. N/A Sim
type O tipo de política da Apigee, por exemplo, VerifyAPIKey, SpikeArrest ou Javascript. Precisa corresponder à única chave de nível superior em content. N/A Sim
content Um dicionário de chave única em que a chave é igual a type. O valor aninhado descreve o XML da política usando a convenção abaixo. {} Sim

Convenção de conteúdo da política

As políticas da Apigee são XML. Em YAML, você representa esse XML em content com estas regras:

  • O dicionário content tem exatamente uma chave, que precisa corresponder ao type da política.
  • Os atributos de elemento ficam em uma chave metadata.
  • O texto do elemento fica abaixo de uma chave _text. Por exemplo, <Foo bar="baz">qux</Foo> passa a ser Foo: {metadata: {bar: "baz"}, _text: "qux"}. Se um elemento tiver apenas texto e nenhum atributo, você poderá escrever o texto diretamente como o valor.
  • Os elementos filhos são aninhados no nome da tag. Tags repetidas se tornam uma lista.

Por exemplo, esta política de recursos:

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

é compilado para este XML de política:

<VerifyAPIKey continueOnError="false" enabled="true" name="verify-api-key-VA-VerifyAPIKey">
  <APIKey ref="request.header.x-api-key"></APIKey>
  <DisplayName>VA-VerifyAPIKey</DisplayName>
</VerifyAPIKey>

recurso

Um recurso é um arquivo que um recurso contribui para o pacote, como um arquivo JavaScript ou de propriedades.

Nome Descrição Padrão Obrigatório?
name O nome do arquivo, por exemplo, hello-world.js. Os nomes de recursos são prefixados com o uid (ou name) do recurso durante a compilação. N/A Sim
type O tipo de recurso, que determina o subdiretório no pacote, por exemplo, jsc (JavaScript) ou properties. N/A Sim
content O conteúdo do arquivo bruto. N/A Não

Campos sem suporte nesta versão

  • paths em um parâmetro (JSONPath). Usá-lo causa falha na compilação.
  • tests em qualquer documento. O campo é aceito, mas ignorado e não incluído no pacote gerado.

Limites

O pacote de proxy de API gerado não pode exceder 10 MiB descompactados ou 256 arquivos.

Próximas etapas