API Sources de données

Liste les préréglages de source : des configurations toutes prêtes et testées de la source de données json (docs/sources.md, Presets). Chacun indique les cartes qu’il alimente, les champs qu’une personne remplit (avec une aide, un motif et un exemple), les secrets dont il a besoin et la façon d’obtenir chacun, la fréquence de son actualisation et la durée pendant laquelle une carte garde ses dernières données, ainsi que les données de qui il lit et selon quelles conditions.

Créez une source à partir d’un préréglage avec POST /api/sources et preset, settings et secrets, et prévisualisez-la avec POST /api/sources/test.

Un préréglage de source, tel que la liste le montre.

Liste les sources de données du projet, les plus récentes d’abord, au plus 200 par page. Une source de données garde à jour les propriétés dynamiques d’une carte à partir d’une adresse externe, selon un calendrier (docs/sources.md). Chaque source affiche son statut : la dernière tentative, le dernier succès, la dernière modification écrite, la prochaine exécution, le nombre d’échecs et la dernière erreur.

Les secrets ne sont jamais renvoyés; chacun apparaît comme défini avec un indice masqué. next_cursor se renvoie comme after pour la page suivante, null s’il n’y en a plus.

Crée une source de données qui écrit les propriétés dynamiques d’une carte à partir d’une adresse externe. kind choisit l’adaptateur (ics lit une adresse iCalendar ou webcal://); config contient les paramètres du type et secrets ses identifiants, stockés chiffrés et affichés seulement sous forme d’indice masqué.

Ou nommez un préréglage (GET /api/source-presets) et donnez ses settings et secrets à la place de kind et config : la source est une source json dont la configuration est construite par le préréglage, renvoyée avec son preset et ses settings, et l’intervalle d’actualisation et la période de péremption prennent par défaut ceux du préréglage. Un préréglage n’alimente que les cartes qu’il liste (source_target_unsupported).

La source s’exécute dans les secondes qui suivent, puis toutes les refresh_seconds. Une exécution en échec n’écrit jamais : la carte garde son dernier bon document et le statut de la source affiche l’erreur. Une source alimente une carte (source_target_taken), la carte doit être de celles que ce type peut alimenter (source_target_unsupported), et une organisation compte au plus 200 sources (source_limit_reached).

Utilisez d’abord POST /api/sources/test pour voir le document que la source écrirait. Ajoute source.created. Une nouvelle tentative identique avec la même Idempotency-Key renvoie la même réponse pendant vingt-quatre heures.

Fait un aperçu d’une source de données sans rien enregistrer ni écrire : récupère l’adresse, met la réponse en forme pour la carte visée et valide le document auprès de la carte, puis renvoie le document, si la carte l’accepte (valid, avec validation_error qui nomme le chemin sinon), ainsi que les avertissements et les décomptes de l’exécution.

Passez source_id pour tester une source enregistrée, les autres membres servant de remplacements (settings remplace ceux d’une source créée à partir d’un préréglage); sinon target et soit kind et config, soit preset, settings et secrets sont requis. Un secret que conserve une source enregistrée est utilisé tel quel, sauf si le remplacement change l’adresse visée (source_secret_required).

Un échec de récupération ou de mise en forme est source_test_failed avec le source_error fixe. Au plus 30 aperçus par minute et par organisation.

Une source de données avec son statut. ETag est la révision, pour If-Match au prochain changement.

Modifie une source de données. config remplace toute la configuration; secrets fusionne (une chaîne définit ou remplace un secret, null le supprime).

Une source créée à partir d’un préréglage prend settings au lieu de config : chaque paramètre nommé remplace sa valeur, null supprime un paramètre facultatif, les autres gardent la leur, et la configuration est reconstruite à partir du préréglage (config sur une telle source donne invalid_request sur config, et settings sur une autre donne invalid_request sur settings). Ses secrets sont nommés comme le préréglage les nomme.

Un secret non envoyé garde sa valeur, sauf si le changement pointe la source vers un endroit que sa portée stockée ne couvre pas (source_secret_required sur secrets.<name> : saisissez-le de nouveau).

Un changement de la cible, de config, des secrets, de refresh_seconds ou de enabled réinitialise le compteur d’échecs et exécute la source dans les secondes qui suivent; un renommage non. enabled à false arrête le calendrier et conserve le dernier document de la carte. If-Match protège la révision. Ajoute source.updated.

Supprime la source de données. La carte garde le dernier document que la source a écrit. If-Match protège la révision. Ajoute source.deleted.

Le mappage des salles d’une source de données qui lit les salles d’un système de réservation (type momentus) : les salles qu’elle offre et qu’aucun écran n’affiche (summary.unmapped_rooms), et les écrans qui lisent un document de salle ou de zone sans valeur qui en désigne un (écrans dont le statut est missing ou unknown, avec une suggestion lorsque la valeur est une salle écrite autrement).

Les salles sont celles de la dernière bonne actualisation de la source; rien n’est récupéré. Un type sans salles répond source_has_no_rooms.

Synchronise la source tout de suite, en ligne (jusqu’à 60 secondes), et la renvoie avec son nouveau statut. Une synchronisation en échec répond 200 avec status.state error et l’erreur; elle n’écrit jamais. Une actualisation repart de zéro : le compteur d’échecs est remis à zéro et l’adresse est lue en entier. source_busy (Retry-After) tant qu’une synchronisation planifiée occupe la source.

Au plus 6 actualisations par minute et par source.