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
gatewayeschemaVersionsã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:
- Se a lista
parametersdo modelo tiver uma entrada em que onamecorresponda e odefaultnão esteja vazio, a CLI vai usar esse valor. Se o conjunto de atributos definir umuid, o nome da entrada do modelo precisará serFEATURE_NAME.UID.PARAMETER_NAME. - Caso contrário, a CLI vai usar o
defaultdo parâmetro de recurso. - 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
contenttem exatamente uma chave, que precisa corresponder aotypeda 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-seFoo: {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
pathsem um parâmetro (JSONPath). O uso dele faz com que a compilação falhe.testsem 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.