Referencia de la configuración en YAML del proxy de API

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 gateway y schemaVersion cuando 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:

  1. Si la lista parameters de la plantilla tiene una entrada cuyo name coincide y cuyo default no está vacío, la CLI usa ese valor. Si el atributo establece un uid, el nombre de la entrada de la plantilla debe ser FEATURE_NAME.UID.PARAMETER_NAME.
  2. De lo contrario, la CLI usa el default del parámetro de función.
  3. 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 content tiene exactamente una clave, que debe coincidir con el type de 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 en Foo: {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

  • paths en un parámetro (JSONPath). Si lo usas, la compilación fallará.
  • tests en 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.

Próximos pasos