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 Cómo configurar un proxy con YAML. Para obtener una guía, consulta Crea un proxy de API a partir de una plantilla en YAML.

Convenciones

  • Los nombres de los campos usan camelCase. Por ejemplo, schemaVersion, basePath, displayName, faultRules, defaultFaultRule, httpTargetConnection.
  • El esquema es estricto. Los campos desconocidos provocan 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

Todos los documentos template, feature y proxy comienzan 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 Es 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 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 las funciones 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 atributos y define los extremos y las rutas del proxy. Una plantilla no contiene políticas ni recursos, sino que estos provienen de las funciones a las que hace referencia.

Nombre Descripción Predeterminado ¿Es obligatorio?
features Es una lista de nombres de archivos de funciones que se incluirán en el proxy. Cada nombre debe resolverse en un archivo del mismo directorio que la plantilla. [] No
parameters Es una lista de valores de parámetros que proporcionan valores predeterminados para las funciones. [] No
endpoints Es una lista de endpoints que definen rutas y rutas base. [] No
targets Es una lista de destinos que definen las conexiones de backend. [] No

Tipo de documento: atributo

Un componente es una unidad de configuración reutilizable que se incluye en una plantilla. Una función contiene políticas y recursos, y puede aportar flujos, extremos y destinos al proxy compilado. Además de los campos comunes de nivel superior, una función 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 se usa para asignar un espacio de nombres a las políticas y los recursos de la función. Si no se establece, se usa name. N/A No
documentation Se amplió la documentación de la función. N/A No
categories Es una lista de etiquetas de categorías de formato libre. [] No
parameters Es una lista de parámetros que define la función. [] No
defaultEndpoint Un extremo de proxy cuyos flujos y regla de errores predeterminada se combinan en cada extremo del proxy compilado. Úsala 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 conexión de backend predeterminada. N/A No
endpoints Es una lista de extremos de proxy que se agregarán al proxy. Un extremo con el mismo nombre que uno existente lo reemplaza. [] No
targets Es una lista de destinos de proxy que se agregarán al proxy. Se reemplaza un destino existente por uno con el mismo nombre. [] No
policies Es una lista de las políticas que proporciona la función. Los nombres de las políticas se anteponen automáticamente con el uid (o name) de la función durante la compilación. [] No
resources Es una lista de recursos que proporciona la función, como archivos 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 adopta el paquete del proxy de API.

Un proxy tiene los mismos campos que una función, excepto que usa endpoints y targets (no defaultEndpoint ni defaultTarget) y siempre representa un proxy completo y apto para la implementación. Su type es proxy.

Objetos anidados

parámetro

Un parámetro proporciona un valor a una función. El valor de un parámetro se resuelve en su default.

Nombre Descripción Predeterminado ¿Es obligatorio?
name Es el nombre del parámetro. Se hace referencia en el contenido de la función como {name}. N/A Sí
displayName Es un nombre legible. N/A No
description Es una descripción del parámetro. N/A No
default Es el valor predeterminado. Se sustituye por {name} en las cadenas del atributo. 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 lo usas, se generará 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 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 las propiedades defaultEndpoint y endpoints de una función, y en un proxy compilado. Extiende endpoint con el control de flujo.

Nombre Descripción Predeterminado ¿Es obligatorio?
flows Es 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éricos. [] 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 fallas. [] No
defaultFaultRule 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 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 y 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 Condición que debe ser verdadera para que se ejecute el flujo. N/A No
steps Es 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 Nombre de la política que se ejecutará. Dentro de una función, usa el nombre local de la política. El compilador lo reescribe como el nombre con espacio de nombres. N/A Sí
condition Condición que debe ser verdadera para que se ejecute el paso. N/A No

faultRule

Extiende el flujo con un campo adicional.

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 en 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 el defaultTarget y el targets de una función, y en un proxy compilado. Extiende target con el control de flujo y las anulaciones de conexión 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 fallas. [] 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 configura, tiene prioridad sobre url, auth, scopes y aud. N/A No
localTargetConnection Es una representación sin procesar de un elemento LocalTargetConnection. Si se configura, tiene prioridad sobre una conexión HTTP. N/A No

política

Una política se define en una función. Su configuración se escribe en content con la convención de atributo/texto que se describe en Convención de contenido de políticas.

Nombre Descripción Predeterminado ¿Es obligatorio?
name Nombre de la política. N/A Sí
type Tipo de política de Apigee, por ejemplo, VerifyAPIKey, SpikeArrest o Javascript. Debe coincidir con la única clave de nivel superior en content. N/A Sí
content Es un diccionario de una sola clave cuya única clave es igual a type. El valor anidado describe el XML de la política según 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 elementos se incluyen en 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 atributos, puedes escribir el texto directamente como el valor.
  • Los elementos secundarios se anidan bajo el nombre de su 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 al que contribuye una función del 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. Los nombres de los recursos tienen el prefijo uid (o name) de la función durante la compilación. N/A Sí
type Tipo de recurso que determina el subdirectorio en el paquete, por ejemplo, jsc (JavaScript) o properties. N/A Sí
content Es el contenido sin procesar del archivo. N/A No

Campos que no se admiten en esta versión

  • paths en un parámetro (JSONPath). Si lo usas, se producirá un error de compilación.
  • 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