API de Fuentes de datos

Lista las opciones predefinidas de fuente: configuraciones listas para usar y probadas de la fuente de datos json (docs/sources.md, Presets). Cada una indica qué tarjetas rellena, los campos que rellena una persona (con ayuda, un patrón y un ejemplo), los secretos que necesita y cómo obtener cada uno, con qué frecuencia se actualiza y cuánto tiempo conserva una tarjeta sus últimos datos, y los datos de quién lee y bajo qué condiciones.

Cree una fuente a partir de una con POST /api/sources y preset, settings y secrets, y obtenga una vista previa con POST /api/sources/test.

Una opción predefinida de fuente, tal como la muestra la lista.

Lista las fuentes de datos del proyecto, las más recientes primero, hasta 200 por página. Una fuente de datos mantiene al día las propiedades dinámicas de una tarjeta desde una dirección externa según una programación (docs/sources.md). Cada fuente muestra su estado: el último intento, el último éxito, el último cambio escrito, la próxima ejecución, el recuento de fallos y el último error.

Los secretos nunca se devuelven; cada uno aparece como definido con una pista enmascarada. next_cursor se pasa como after para la página siguiente, null cuando no hay más.

Crea una fuente de datos que escribe las propiedades dinámicas de una tarjeta desde una dirección externa. kind elige el adaptador (ics lee una dirección iCalendar o webcal://); config contiene los ajustes del tipo y secrets sus credenciales, que se almacenan cifradas y se muestran solo como una pista enmascarada.

O nombre una opción predefinida (GET /api/source-presets) y dé sus settings y secrets en lugar de kind y config: la fuente es una fuente json cuya configuración construye la opción predefinida, devuelta con su preset y settings, y el intervalo de actualización y el periodo de caducidad toman por defecto los de la opción predefinida. Una opción predefinida solo rellena las tarjetas que lista (source_target_unsupported).

La fuente se ejecuta en unos segundos y después cada refresh_seconds. Una ejecución fallida nunca escribe: la tarjeta conserva su último documento válido y el estado de la fuente muestra el error. Una fuente rellena una tarjeta (source_target_taken), la tarjeta debe ser una que el tipo pueda rellenar (source_target_unsupported) y una organización tiene como máximo 200 fuentes (source_limit_reached).

Use primero POST /api/sources/test para ver el documento que escribiría la fuente. Añade source.created. Un reintento idéntico con la misma Idempotency-Key devuelve esta misma respuesta durante veinticuatro horas.

Hace una vista previa de una fuente de datos sin guardar ni escribir nada: obtiene la dirección, adapta la respuesta a la tarjeta de destino y valida el documento con la tarjeta; después devuelve el documento, si la tarjeta lo acepta (valid, con validation_error que nombra la ruta si no) y las advertencias y los recuentos de la ejecución.

Pase source_id para probar una fuente guardada con los demás miembros como sustituciones (settings sustituye a los de una fuente creada a partir de una opción predefinida); de lo contrario, target y o bien kind y config, o bien preset, settings y secrets son obligatorios. Un secreto que conserva una fuente guardada se usa tal como está almacenado, salvo que la sustitución cambie a dónde apunta (source_secret_required).

Un fallo de obtención o de conformado es source_test_failed con el source_error fijo. Como máximo 30 vistas previas por minuto por organización.

Una fuente de datos con su estado. ETag es la revisión, para If-Match en el siguiente cambio.

Cambia una fuente de datos. config sustituye toda la configuración; secrets se fusiona (una cadena define o reemplaza uno, null lo elimina).

Una fuente creada a partir de una opción predefinida toma settings en lugar de config: cada ajuste nombrado sustituye su valor, null elimina uno opcional, los demás conservan el suyo, y la configuración se vuelve a construir a partir de la opción predefinida (config en una fuente así es invalid_request en config, y settings en otra es invalid_request en settings). Sus secretos se nombran como los nombra la opción predefinida.

Un secreto no enviado conserva su valor, salvo que el cambio apunte la fuente a un sitio que su ámbito almacenado no cubre (source_secret_required en secrets.<name>: introdúzcalo de nuevo).

Un cambio en el destino, config, los secretos, refresh_seconds o enabled restablece el recuento de fallos y ejecuta la fuente en unos segundos; un cambio de nombre no. enabled en false detiene la programación y conserva el último documento de la tarjeta. If-Match protege la revisión. Añade source.updated.

Elimina la fuente de datos. La tarjeta conserva el último documento que escribió la fuente. If-Match protege la revisión. Añade source.deleted.

La asignación de salas de una fuente de datos que lee las salas de un sistema de reservas (tipo momentus): qué salas ofrece que ninguna pantalla muestra (summary.unmapped_rooms), y qué pantallas leen un documento de sala o de área sin un valor que nombre una (pantallas con estado missing o unknown, con una sugerencia cuando el valor es una sala escrita de otra manera).

Las salas son las de la última actualización correcta de la fuente; no se consulta nada. Un tipo sin salas responde source_has_no_rooms.

Sincroniza la fuente al instante, en línea (hasta 60 segundos), y la devuelve con su nuevo estado. Una sincronización fallida responde 200 con status.state error y el error; nunca escribe. Una actualización reinicia la fuente: el recuento de fallos vuelve a cero y la dirección se lee completa. source_busy (Retry-After) mientras una sincronización programada tiene la fuente.

Como máximo 6 actualizaciones por minuto y fuente.