Programar franjas fuera de servicio

Programar franjas fuera de servicio

Resumen

Una franja fuera de servicio deja un método sin responder datos durante una ventana programada, por ejemplo mientras el origen hace su mantenimiento nocturno, y en su lugar devuelve un mensaje que usted define. Se configura por método con una expresión cron, una duración en segundos y, si quiere, un alcance por grupos y usuarios y una plantilla de excepciones. En esta guía define una franja, elige qué recibe el consumidor y lo verifica llamando al método dentro y fuera de la franja.

Antes de comenzar

  • Necesita un rol que pueda editar métodos y publicar versiones de la API.
  • La frecuencia se escribe como expresión cron de cinco campos (minuto, hora, día del mes, mes, día de la semana), con números, *, rangos y pasos. No acepta comas ni nombres de mes o de día. El formulario enlaza una herramienta para armarla.
  • La franja empieza cada vez que el cron coincide y dura los segundos que usted indique. Un mantenimiento diario de 3:00 a 5:00 es 0 3 * * * con duración 7200.

Definir una franja en el método

Abrir las franjas del método

En el editor del método, el bloque Fuera de servicio indica que el método no tiene franjas. Haga clic en Sobreescribir y después en Configurar franjas horarias: el modal lista las franjas que ya existen en otros métodos de la cuenta, para reutilizarlas, y el botón Nueva Franja Horaria crea una.

Completar la franja

  • Nombre, obligatorio, y Descripción. La descripción es el mensaje que recibe quien llama al método durante la franja.
  • Todos o Grupos / Usuarios: con la segunda opción solo los elegidos quedan sin servicio y el resto sigue consumiendo el método.
  • Frecuencia: la expresión cron. Debajo del campo se muestra en palabras.
  • Duración (segundos): cuánto dura cada ventana.
  • Plantilla de excepciones, opcional: una plantilla Jinja que se evalúa en cada llamada durante la franja. Si devuelve exactamente true, esa llamada pasa; cualquier otro resultado la bloquea. Tiene disponibles result.user, result.parameters, result.oos, result.timestamp y result.path. Por ejemplo, {{ 'true' if result.user.email == 'monitoreo@midominio.com' else 'false' }} deja pasar al usuario de monitoreo.
Formulario Nueva Franja Horaria con nombre, descripción, alcance, frecuencia, duración y plantilla de excepciones

Haga clic en Crear: la franja aparece en la tabla del modal, ya seleccionada. Con Listo el método queda con las franjas marcadas, que se ven en el bloque con su frecuencia y duración.

Bloque Fuera de servicio del método con la franja Mantenimiento, cada minuto, 30 segundos

Elegir qué recibe el consumidor

Sin más configuración, durante la franja el método responde 200 con este cuerpo, donde description es la descripción de la franja:

{"status": 200, "description": "Mantenimiento programado: el método vuelve en unos minutos.", "type": "OOS"}

Para responder con otro código y su propio formato, en Plantillas de error busque ERROR FUERA DE SERVICIO: elija el Código de respuesta, por ejemplo 503, y asígnele una Plantilla para cada formato del método. La plantilla tiene result.error_message con la descripción de la franja, result.timestamp, result.path, result.method y request.traceid, que también viaja en la cabecera X-TraceId.

{
  "error": "{{ result.error_message }}",
  "estado": "fuera de servicio",
  "reintentar": "en unos minutos"
}
Sección ERROR FUERA DE SERVICIO de las plantillas de error con la plantilla y el código 503

Guardar y publicar

Guarde el método con Listo y publique la versión. La programación se activa al guardar: la próxima coincidencia del cron abre la ventana.

Editar o quitar franjas

De vuelta en Configurar franjas horarias, cada fila tiene los íconos Editar y Eliminar; hacer clic en la fila la marca o la desmarca para este método. Los cambios recién se aplican al guardar el método. Usar valores por defecto quita todas las franjas del método.

Resultado esperado

Dentro de la ventana, cada llamada al método recibe el código y la plantilla que definió, o el cuerpo por defecto con la descripción, sin consultar el origen. Terminada la duración, el método vuelve a responder datos solo. Una llamada que coincide con la plantilla de excepciones pasa como si no hubiera franja.

Errores frecuentes

  • La expresión cron no es válida: tiene que tener cinco campos y usar solo números, *, rangos con - y pasos con /. Reemplace las comas por varias franjas.
  • Responde 200 aunque eligió 503: hasta la versión 7.5.1 el código de ERROR FUERA DE SERVICIO solo se aplica cuando el formato pedido tiene una plantilla asignada. Asígnele una plantilla a cada formato.
  • Responde 503 con error OOS y sin su plantilla: la franja tiene plantilla de excepciones y no devolvió true para esa llamada. Ese caso usa una respuesta fija.
  • La franja no corta el método: el método se guardó pero la versión no se publicó, o el cron todavía no coincidió. La hora se evalúa en la zona horaria del servidor.
  • El botón del formulario dice Crear Límite: es el mismo formulario que usan los límites; crea la franja.

Artículos relacionados