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.

Nesta página, descrevemos o formato YAML para os modelos de recursos da Apigee: os tipos de documento template, feature e proxy e todos os campos deles. Para uma introdução conceitual, consulte Como configurar um proxy com YAML. Para um tutorial, consulte Criar um proxy de API com base em um modelo YAML.

Convenções

  • Os nomes dos campos usam camelCase. Por exemplo, schemaVersion, basePath, displayName, faultRules, defaultFaultRule, httpTargetConnection.
  • O esquema é rígido. 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 em funcionamento.

Campos comuns de nível superior

Cada documento template, feature e proxy começa com os campos a seguir.

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 por humanos. 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 ou recursos. Eles vêm dos recursos que ele referencia.

Nome Descrição Padrão Obrigatório?
features Uma lista de arquivos de recursos para compor o proxy. Cada entrada é um caminho para um arquivo de recurso, relativo ao diretório que contém o modelo (por exemplo, ./features/spike-arrest.yaml). [] Não
parameters Uma lista de parâmetros que definem valores para os parâmetros dos recursos. O default de uma entrada substitui o default do parâmetro de recurso com o mesmo name. Consulte o parâmetro. [] Não
endpoints Uma lista de endpoints que definem caminhos e rotas de base. [] Não
targets Uma lista de destinos que definem conexões de back-end. [] Não

Tipo de documento: recurso

Um recurso é uma unidade de configuração reutilizável 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 campos a seguir.

Nome Descrição Padrão Obrigatório?
displayName Um nome de exibição legível por humanos. N/A Não
uid Um identificador exclusivo que mantém as políticas e os recursos do recurso separados quando um modelo inclui o recurso mais de uma vez. Se o recurso definir um uid, a CLI vai prefixar cada um dos nomes de política e recurso com UID- e atualizar as referências a eles. Se o recurso não definir um uid, a CLI vai usar os nomes como escritos. N/A Não
documentation Documentação estendida do recurso. N/A Não
categories Uma lista de rótulos de categoria de formato livre. [] Não
parameters Uma lista de parâmetros que o recurso define. [] Não
defaultEndpoint Um endpoint de proxy com fluxos e regra de falha padrão mesclados em cada endpoint 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 atual o substitui. [] Não
targets Uma lista de destinos de proxy a serem adicionados ao proxy. Um destino com o mesmo nome de um destino atual o substitui. [] Não
policies Uma lista de políticas fornecidas pelo recurso. Se o conjunto de atributos definir um uid, a CLI vai prefixar cada nome de política com UID- durante a compilação, por exemplo, sa1-SA-SpikeArrest. Caso contrário, a CLI vai usar os nomes das políticas como escritos. [] Não
resources Uma lista de recursos fornecidos pelo recurso, como arquivos JavaScript ou de propriedades. [] Não

Tipo de documento: procuração

Um proxy é o documento totalmente resolvido que a CLI produz quando compila um modelo com os recursos dele. Normalmente, você não cria esse tipo diretamente. Ele é descrito aqui porque é o formato 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 para um recurso. Um recurso declara os parâmetros, e um modelo pode definir os valores deles na própria lista parameters. Quando a CLI compila um modelo, ela resolve cada parâmetro de recurso da seguinte maneira:

  1. Se a lista parameters do modelo tiver uma entrada em que o name corresponda e o default não esteja vazio, a CLI vai usar esse valor. Se o conjunto de atributos definir um uid, o nome da entrada do modelo precisará ser FEATURE_NAME.UID.PARAMETER_NAME.
  2. Caso contrário, a CLI vai usar o default do parâmetro de recurso.
  3. Se nenhum deles definir um valor, o parâmetro será resolvido como uma string vazia. A CLI não informa um erro.

Não há uma flag de linha de comando para definir valores de parâmetro no momento da importação. Para mudar um valor, edite o modelo.

Nome Descrição Padrão Obrigatório?
name O nome do parâmetro. Referenciado no conteúdo em destaque como {name}. N/A Sim
displayName Um nome legível por humanos. N/A Não
description Uma descrição do parâmetro. N/A Não
default Em um recurso, o valor usado quando o modelo não define um. Em um modelo, o valor do parâmetro de recurso com o mesmo nome. A CLI ignora um valor vazio. A CLI substitui o valor resolvido por {name} nas strings do recurso. N/A Não
examples Uma lista de exemplos de valores. [] Não
maps Um mapa de substituições de valor. 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 em defaultEndpoint e 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. Os 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 o qual 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 de solicitação/resposta padrão. 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 que a etapa seja executada. N/A Não

faultRule

Estende o fluxo com um campo adicional.

O campo mode herdado de flow não se aplica a uma regra de falha. Como uma regra de falha é executada após uma falha na solicitação, ela não tem uma fase de solicitação ou resposta. As etapas dela são sempre executadas diretamente. Se você definir mode em uma regra de falha, a ferramenta vai registrar um aviso e ignorar o campo.

Nome Descrição Padrão Obrigatório?
alwaysEnforce Se for true, a regra de falha padrão será sempre 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 de 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. Aplica-se quando auth está definido. [] Não
aud O público-alvo do token. Aplica-se quando auth está definido. N/A Não

proxyTarget

Usado em defaultTarget e targets de um recurso e em um proxy compilado. Estende o destino 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 definida, ela 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 uma 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. No 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 em uma chave _text. Por exemplo, <Foo bar="baz">qux</Foo> torna-se 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. As 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. Se o recurso definir um uid, a CLI vai prefixar o nome do recurso com UID- durante a compilação. Caso contrário, a CLI vai usar o nome como está escrito. 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 que não são compatíveis com esta versão

  • paths em um parâmetro (JSONPath). O uso dele faz com que a compilação falhe.
  • 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