Esta página se aplica a Apigee y Apigee Hybrid.
Consulta la documentación de
Apigee Edge.
En esta página, se describe el formato YAML para las plantillas de funciones de Apigee: los tipos de documentos template, feature y proxy, y todos sus campos. Para obtener una introducción conceptual, consulta
Configura
un proxy con YAML. Para obtener una explicación, consulta
Crea
un proxy de API a partir de una plantilla de YAML.
Convenciones
- Los nombres de los campos usan mayúsculas mediales. Por ejemplo,
schemaVersion,basePath,displayName,faultRules,defaultFaultRule,httpTargetConnection. - El esquema es estricto. Los campos desconocidos causan un error cuando importas el archivo.
- Campos obligatorios. Solo se validan
gatewayyschemaVersioncuando se analiza un archivo. Otros campos marcados como Sí en las siguientes tablas son obligatorios en la práctica para producir un proxy de API que funcione.
Campos comunes de nivel superior
Cada documento template, feature y proxy
comienza con los siguientes campos.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
gateway |
Es la puerta de enlace de destino. Debe ser apigee. |
N/A | Sí |
schemaVersion |
Es la versión del esquema del documento. Debe ser 1.0.0. |
N/A | Sí |
name |
El nombre del documento. En el caso de una plantilla o un proxy, este es el nombre del proxy de API escrito en el paquete. | N/A | Sí |
type |
El tipo de documento: template, feature o
proxy. |
N/A | Sí |
description |
Es una descripción legible por humanos. | N/A | No |
priority |
Es un número entero que controla el orden en el que se aplican los atributos durante la compilación. Los números más bajos se aplican primero. | 100 |
No |
Tipo de documento: plantilla
Una plantilla es el punto de entrada que importas. Compone funciones y define los extremos y las rutas del proxy. Una plantilla no contiene políticas ni recursos, ya que estos provienen de las funciones a las que hace referencia.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
features |
Es una lista de archivos de atributos que se deben componer en el proxy. Cada entrada es una
ruta de acceso a un archivo de atributos, relativa al directorio que contiene la
plantilla (por ejemplo, ./features/spike-arrest.yaml). |
[] |
No |
parameters |
Es una lista de parámetros que establecen valores para
los parámetros de los atributos. El default de una entrada anula el
default del parámetro de función con el mismo
name. Consulta parámetro. |
[] |
No |
endpoints |
Es una lista de extremos que definen rutas de acceso y rutas de acceso base. | [] |
No |
targets |
Es una lista de destinos que definen las conexiones de backend. | [] |
No |
Tipo de documento: atributo
Un atributo es una unidad de configuración reutilizable que se incluye en una plantilla. Un atributo contiene políticas y recursos, y puede aportar flujos, extremos y destinos al proxy compilado. Además de los campos comunes de nivel superior, un objeto tiene los siguientes campos.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
displayName |
Es un nombre visible legible por humanos. | N/A | No |
uid |
Es un identificador único que mantiene separadas las políticas y los recursos de la función
cuando una plantilla incluye la función más de una vez. Si el atributo
establece un uid, la CLI antepone UID- a cada uno de los nombres de sus políticas y recursos,
y actualiza las referencias a ellos. Si
la función no establece un uid, la CLI usa los nombres tal como
están escritos. |
N/A | No |
documentation |
Documentación extendida de la función | N/A | No |
categories |
Es una lista de etiquetas de categoría de formato libre. | [] |
No |
parameters |
Es una lista de parámetros que define el atributo. | [] |
No |
defaultEndpoint |
Un extremo de proxy cuyos flujos y regla de error predeterminada se combinan en cada extremo del proxy compilado. Usa esto para adjuntar las políticas de una función al flujo de solicitud o respuesta. | N/A | No |
defaultTarget |
Un destino de proxy que se usa como una conexión de backend predeterminada. | N/A | No |
endpoints |
Es una lista de extremos de proxy para agregar al proxy. Un extremo con el mismo nombre que uno existente lo reemplaza. | [] |
No |
targets |
Es una lista de destinos de proxy para agregar al proxy. Un destino con el mismo nombre que uno existente lo reemplaza. | [] |
No |
policies |
Una lista de políticas que proporciona la función. Si la
función establece un uid, la CLI antepone a cada nombre de política el prefijo
UID- durante la compilación, por ejemplo,
sa1-SA-SpikeArrest. De lo contrario, la CLI usa los nombres de las políticas tal como
están escritos. |
[] |
No |
resources |
Es una lista de recursos que proporciona la función, como archivos de JavaScript o de propiedades. | [] |
No |
Tipo de documento: proxy
Un proxy es el documento completamente resuelto que produce la CLI cuando compila una plantilla con sus funciones. Por lo general, no creas este tipo directamente; se describe aquí porque es la forma que se convierte en el paquete de proxy de API.
Un proxy tiene los mismos campos que un atributo, excepto que usa
endpoints y targets (no defaultEndpoint
ni defaultTarget) y siempre representa un proxy completo
y que se puede implementar. Su type es proxy.
Objetos anidados
parámetro
Un parámetro proporciona un valor a un atributo. Un atributo declara sus
parámetros, y una plantilla puede establecer sus valores en su propia
lista parameters. Cuando la CLI compila una plantilla, resuelve cada
parámetro de función de la siguiente manera:
- Si la lista
parametersde la plantilla tiene una entrada cuyonamecoincide y cuyodefaultno está vacío, la CLI usa ese valor. Si el atributo establece unuid, el nombre de la entrada de la plantilla debe serFEATURE_NAME.UID.PARAMETER_NAME. - De lo contrario, la CLI usa el
defaultdel parámetro de función. - Si ninguna de las dos opciones establece un valor, el parámetro se resuelve como una cadena vacía. La CLI no informa un error.
No hay ninguna función experimental de línea de comandos para establecer los valores de los parámetros en el momento de la importación. Para cambiar un valor, edita la plantilla.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
name |
Es el nombre del parámetro. Se hace referencia a él en el contenido destacado como {name}. |
N/A | Sí |
displayName |
Un nombre legible por humanos. | N/A | No |
description |
Es una descripción del parámetro. | N/A | No |
default |
En un atributo, es el valor que se usa cuando la plantilla no establece uno. En una
plantilla, el valor del parámetro de función con el mismo nombre. La
CLI ignora un valor vacío. La CLI sustituye el valor resuelto por {name} en las cadenas de la función. |
N/A | No |
examples |
Es una lista de valores de ejemplo. | [] |
No |
maps |
Es un mapa de reemplazos de valores. Si el valor resuelto es una clave en el mapa, se reemplaza por el valor asignado. | N/A | No |
paths |
Es una lista de expresiones JSONPath. No se admite en esta versión; si se usa, se produce un error. | N/A | No |
extremo
Se usa en la lista endpoints de una plantilla.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
name |
Es el nombre del extremo. | N/A | Sí |
basePath |
Es la ruta de acceso base que usan los clientes para llamar al proxy, por ejemplo,
/v1/gemini. |
N/A | No |
routes |
Es una lista de rutas que asignan solicitudes a destinos. | [] |
No |
proxyEndpoint
Se usa en el defaultEndpoint y el endpoints de un atributo,
y en un proxy compilado. Extiende el extremo con el manejo de flujos.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
flows |
Una lista de flujos Los flujos llamados PreFlow
o PostFlow se asignan al flujo de Apigee correspondiente; cualquier
otro nombre se coloca en el contenedor de flujos genérico. |
[] |
No |
postClientFlow |
Un solo flujo que se ejecuta después de que se envía la respuesta al cliente. | N/A | No |
faultRules |
Es una lista de flujos que se usan como reglas de falla. | [] |
No |
defaultFaultRule |
Es una regla de falla que se ejecuta cuando no coincide ninguna otra regla de falla. | N/A | No |
ruta
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
name |
Es el nombre de la ruta. | N/A | Sí |
target |
Es el nombre del extremo de destino al que se debe enrutar. | N/A | No |
condition |
Es una condición que debe ser verdadera para que se aplique esta ruta. | N/A | No |
concentración
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
name |
Es el nombre del flujo. Usa PreFlow o PostFlow para
los flujos de solicitud/respuesta estándar. |
N/A | Sí |
mode |
Request o Response. Determina si los
pasos se ejecutan en la solicitud o en la respuesta. |
Request |
No |
condition |
Es una condición que debe ser verdadera para que se ejecute el flujo. | N/A | No |
steps |
Una lista ordenada de pasos (invocaciones de políticas). | [] |
No |
paso
Un paso ejecuta una política dentro de un flujo.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
name |
Es el nombre de la política que se ejecutará. Dentro de un atributo, usa el nombre local de la política; el compilador lo reescribe con el nombre con espacio de nombres. | N/A | Sí |
condition |
Es una condición que debe ser verdadera para que se ejecute el paso. | N/A | No |
faultRule
Extiende flow con un campo adicional.
El campo mode heredado de flow
no se aplica a una regla de error. Debido a que una regla de falla se ejecuta después de que falla una solicitud, no tiene una fase de solicitud o respuesta; sus pasos siempre se ejecutan directamente. Si configuras mode en una regla de falla, la herramienta registra una
advertencia y omite el campo.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
alwaysEnforce |
Si es true, siempre se aplica la regla de falla predeterminada. |
false |
No |
objetivo
Se usa en la lista targets de una plantilla.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
name |
Es el nombre del destino. Se hace referencia a él con el target de una ruta. |
N/A | Sí |
url |
Es la URL del backend. | N/A | No |
auth |
Es el esquema de autenticación para un backend de Google Cloud, por ejemplo,
GoogleAccessToken o GoogleIDToken. |
N/A | No |
scopes |
Es una lista de permisos de OAuth que se solicitarán. Se aplica cuando se establece auth. |
[] |
No |
aud |
Es el público del token. Se aplica cuando se establece auth. |
N/A | No |
proxyTarget
Se usa en defaultTarget y targets de un atributo, y
en un proxy compilado. Extiende target con el manejo de flujos y
las anulaciones de conexiones sin procesar.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
flows |
Es una lista de flujos que se ejecutan en la solicitud o respuesta de destino. | [] |
No |
faultRules |
Es una lista de flujos que se usan como reglas de falla. | [] |
No |
defaultFaultRule |
Una regla de falla | N/A | No |
httpTargetConnection |
Es una representación sin procesar del elemento HTTPTargetConnection para la configuración avanzada. Si se establece, tiene prioridad sobre
url, auth, scopes y
aud. |
N/A | No |
localTargetConnection |
Es una representación sin procesar de un elemento LocalTargetConnection.
Si se establece, tiene prioridad sobre una conexión HTTP. |
N/A | No |
política
Una política se define en un atributo. Su configuración se escribe en
content con la convención de atributo/texto que se describe en
Convención de contenido de la política.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
name |
Nombre de la política. | N/A | Sí |
type |
Es el tipo de política de Apigee, por ejemplo, VerifyAPIKey,
SpikeArrest o Javascript. Debe coincidir con la clave única de nivel superior en content. |
N/A | Sí |
content |
Es un diccionario de una sola clave, cuya clave es igual a type. El
valor anidado describe el XML de la política con la siguiente convención. |
{} |
Sí |
Convención de contenido de la política
Las políticas de Apigee son XML. En YAML, representas ese XML en
content con estas reglas:
- El diccionario
contenttiene exactamente una clave, que debe coincidir con eltypede la política. - Los atributos de los elementos se encuentran debajo de una clave
metadata. - El texto del elemento se incluye en una clave
_text. Por ejemplo,<Foo bar="baz">qux</Foo>se convierte enFoo: {metadata: {bar: "baz"}, _text: "qux"}. Si un elemento solo tiene texto y no tiene atributos, puedes escribir el texto directamente como el valor. - Los elementos secundarios se anidan bajo su nombre de etiqueta. Las etiquetas repetidas se convierten en una lista.
Por ejemplo, esta política de funciones:
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
se compila en 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
Un recurso es un archivo que una función aporta al paquete, como un archivo JavaScript o un archivo de propiedades.
| Nombre | Descripción | Predeterminado | ¿Es obligatorio? |
|---|---|---|---|
name |
El nombre del archivo, por ejemplo, hello-world.js. Si el atributo
establece un uid, la CLI antepone UID- al nombre del recurso
durante la compilación. De lo contrario, la CLI usa
el nombre tal como está escrito. |
N/A | Sí |
type |
El tipo de recurso, que determina el subdirectorio en el paquete, por ejemplo, jsc (JavaScript) o properties. |
N/A | Sí |
content |
Es el contenido del archivo sin procesar. | N/A | No |
Campos que no se admiten en esta versión
pathsen un parámetro (JSONPath). Si lo usas, la compilación fallará.testsen cualquier documento. El campo se acepta, pero se ignora y no se incluye en el paquete generado.
Límites
El paquete de proxy de API generado no debe superar los 10 MiB sin comprimir ni los 256 archivos.