API Données de la carte

Découvrez les cartes intégrées du catalogue publié de cet environnement, fusionné avec le catalogue fournisseur. Les actualisations et vérifications du schéma se font en arrière-plan; cette route n’appelle jamais le seau edge. Chaque entrée liste sa copie actuelle, son niveau et les mises en page autorisées par ce niveau, ainsi que chaque majeur servi.

Les schémas JSON autonomes de la version majeure actuelle pour les params de placement et les documents de données de carte, le schéma de flux, le niveau, les dispositions autorisées et un exemple de placement. Les params marqués dynamic proviennent du document de données lorsqu'un placement lie une clé de données.

Un paramètre de type chaîne peut contenir {screen.name}, {screen.timezone} et {screen.field.NAME}, et un paramètre location peut être la chaîne {screen.location}; le backend les remplace pour chaque écran. Remplacez les valeurs d'exemple du contenu avant de publier. Les identifiants inconnus renvoient card_not_found (404).

Un UID de carte global, ou un segment de type catalogue obsolète. Ce dernier ajoute des en-têtes Deprecation et Warning pointant vers /api/card-types.

If-Match compare optionnellement la révision des métadonnées de la carte (pas sa révision de données) ; omission met à jour la révision courante. Idempotency-Key lie la méthode, l’UID, les paramètres et If-Match pendant 24 heures. Une tentative rejoue le résultat enregistré, y compris 204 après suppression ; une entrée modifiée retourne idempotency_mismatch. If-Match périmé retourne revision_conflict (412).

Les clés sont limitées à l’UID de la carte.

If-Match compare optionnellement la révision des métadonnées de la carte (pas sa révision de données) ; omission met à jour la révision courante. Idempotency-Key lie la méthode, l’UID, les paramètres et If-Match pendant 24 heures. Une tentative rejoue le résultat enregistré, y compris 204 après suppression ; une entrée modifiée retourne idempotency_mismatch. If-Match périmé retourne revision_conflict (412).

Les clés sont limitées à l’UID de la carte.

Liste les webhooks entrants de la carte, les plus anciens d’abord (20 au maximum). Les secrets ne sont jamais renvoyés ici.

Crée un webhook qui écrit le document de données de cette carte : un système extérieur envoie un corps JSON ou de formulaire à son url (POST /api/cards/{id}/kv-webhooks/{webhook_id}/write).

Sans mappage, l’objet envoyé est le document ; un modèle de mappage le construit à partir du corps et est vérifié à l’enregistrement. signing true exige aussi un en-tête ScreenRig-Signature. verify fait authentifier un envoi par la signature propre d’un fournisseur (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana ou tout expéditeur HMAC) à la place du secret, qui continue de fonctionner à côté ; il ne peut pas être combiné avec signing, et son secret est scellé et jamais renvoyé, seulement un indice. handshake nomme une poignée de main de fournisseur à laquelle l’url répond (Microsoft Graph, monday.com, Trello ou Azure Event Grid ; verify slack et asana répondent à la leur).

La réponse est le seul endroit où apparaissent le secret et le secret de signature (avec rotate-secret et la mise à jour qui active la signature) : enregistrez-les immédiatement dans le système expéditeur. Une carte peut avoir au maximum 20 webhooks (kv_webhook_limit_reached). Ajoute kv_webhook.created.

Une nouvelle tentative exacte avec la même Idempotency-Key renvoie la même réponse, secrets compris, pendant vingt-quatre heures.

Modifie description, mapping (null le supprime), enabled, signing, verify (null le supprime ; sans secret, il garde celui qui est stocké quand le fournisseur est le même) et handshake (null le supprime). Activer signing répond le nouveau signing_secret une seule fois ; false le désactive. Un webhook désactivé répond à chaque envoi comme à un mauvais secret. Ajoute kv_webhook.updated.

Supprime le webhook. Son URL cesse de fonctionner immédiatement ; la carte conserve son document. Ajoute kv_webhook.deleted.

Remplace le secret du webhook et renvoie le nouveau une seule fois ; avec signing true, il remplace plutôt le secret de signature. L’ancien cesse de fonctionner immédiatement. Ajoute kv_webhook.secret_rotated.

Le journal de livraison du webhook, du plus récent au plus ancien, au plus 100 entrées, conservé sept jours.

Chaque envoi qui a nommé ce webhook est une ligne avec son heure, son résultat (written, unchanged, refused, invalid ou handshake), sa raison (credentials, signature, signature_missing, signature_invalid, timestamp_missing, timestamp_stale, secret_pending, handshake_invalid, disabled, body, mapping, card_data_invalid, rate_limited, payment_required, internal), un court détail comme le chemin des données de carte en échec, le statut de la réponse, la taille du corps et le nombre de parties de fichier qu’un envoi multipart portait (ignorées).

Aucun corps, en-tête ni identifiant n’est stocké. C’est là qu’un projet voit pourquoi un envoi a reçu le 404 que partagent tous les refus.

L’URL à laquelle un système externe envoie le document de données d’une carte. Elle s’authentifie avec le secret propre au webhook dans l’en-tête Authorization : Bearer <secret>, ou HTTP Basic avec l’identifiant du webhook comme nom d’utilisateur.

Quand le webhook a été créé avec verify, une signature valide dans l’en-tête propre à ce fournisseur (voir WebhookVerifyWrite) authentifie l’envoi à la place du secret, qui continue de fonctionner à côté.

Quand le webhook signe, ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret> est aussi exigé, et t doit être à moins de cinq minutes de l’horloge du serveur.

Une carte ou un webhook inconnu, un secret ou une signature faux ou absent, un horodatage périmé, un webhook désactivé et chaque GET reçoivent le même 404 not_found ; le projet voit la raison dans le journal de livraison.

Un webhook configuré pour une poignée de main de fournisseur y répond en premier, avant qu’aucun identifiant ne soit demandé, à une requête qui est cette poignée de main : le défi url_verification de Slack (signé, auquel on répond par le défi), le validationToken de Microsoft Graph (renvoyé comme text/plain), le X-Hook-Secret d’Asana (renvoyé, et gardé chiffré comme secret de signature de ses événements), le challenge de monday.com, le SubscriptionValidationEvent d’Azure Event Grid (auquel on répond par son validationResponse) et la vérification HEAD de Trello (l’opération head de cette url).

Une poignée de main n’écrit aucune donnée de carte, n’est jamais facturée et ne consomme aucun budget de débit, et elle est consignée dans le journal de livraison avec le résultat handshake.

Le corps, d’au plus 1 MiB, est du JSON, du application/x-www-form-urlencoded (un nom répété donne un tableau) ou du multipart/form-data (chaque champ de texte est body.<field>, un nom répété donne un tableau, et les parties de fichier sont ignorées et comptées dans le journal de livraison). Sans mappage, l’objet est le document ; avec un mappage, le modèle le construit à partir de body et de query.

Le document est vérifié comme données de la carte (card_data_invalid nomme le chemin), et un document égal au document actuel n’est pas écrit (statut unchanged). Un envoi accepté est une requête d’API facturée et ajoute les événements de données de carte. Idempotency-Key (de 8 à 200 caractères) déduplique les relances d’un expéditeur pendant vingt-quatre heures.

Au plus 120 envois par minute par webhook ; chacun compte aussi dans les débits d’écriture de l’organisation et de la carte (PUT /api/card-data/{key}).

La vérification que Trello fait d’un nouveau webhook. Elle répond 200 sans corps pour un webhook dont la poignée de main est trello, et le seul 404 not_found pour tout autre webhook, adresse et requête : un aperçu de lien n’apprend donc rien. Elle n’écrit rien, n’est jamais facturée et ne consomme aucun budget de débit ; la vérification traitée figure dans le journal de livraison avec le résultat handshake.

Chaque GET répond le 404 et ne lit rien.

Liste les documents de données de carte du projet, au maximum 200 par ordre croissant de clé. next_cursor est la dernière clé retournée ; renvoyez-la comme after pour la page suivante, null s’il n’y en a plus. Les documents de données de carte contiennent les propriétés dynamiques des emplacements de carte (sections de menu, éléments de ticker, tuiles KPI) ; la clé de données de l’emplacement en nomme un.

Retourne le document et sa révision. L’ETag est la révision, pour If-Match à la prochaine écriture.

Crée ou remplace un document de données de carte. Lorsque les placements de cartes dans les listes de lecture du projet lient la clé, le document doit contenir uniquement les propriétés dynamiques de chaque carte liée et valider contre elles ; sinon l’écriture est refusée avec card_data_invalid nommant la carte et le chemin de la propriété, et rien ne change. Une clé sans placement lié accepte tout objet JSON.

Chaque chaîne qui commence par media: est une référence média, media:<id>, pour qu’une carte l’affiche (une photo) ; sur toute clé elle doit nommer une image prête, approuvée dans ce projet, au plus 256 médias distincts par document, sinon l’écriture est refusée avec card_media_invalid nommant le chemin de propriété et media_id.

Les écrans dont le contenu lit la clé peuvent ensuite récupérer ces médias via GET /media/{media_id}. Les écrans affichant un emplacement qui lit la clé reçoivent screen.card_data_changed et le récupèrent à nouveau sur place ; le journal du projet enregistre kv.updated avec une ressource card_data_entry, qui n’atteint jamais un Player.

Les limites, quotas, mesures, révisions et idempotence sont ceux du magasin K/V de l’application.

Les écritures des agents et des webhooks sont aussi limitées en fréquence, par organisation selon le forfait (Standard et Plus 60 par minute, Education et Premium 600, Enterprise 3 000) et à 60 par minute par clé sur tous les forfaits ; une écriture au-delà d’une limite est refusée avec rate_limited et Retry-After, et n’est pas mesurée.

Supprime un document de données de carte. Une carte liée à la clé est cachée à l’écran jusqu’à ce qu’un document soit réécrit.

Lit un document de flux tiers partagé : le même document qu’une carte intégrée avec les mêmes paramètres lit (docs/feeds.md).

Les paramètres de requête sont normalisés en la clé de flux de la carte, nommée par l’en-tête ScreenRig-Feed-Key : weather, airquality et alerts prennent lat et lon (arrondis à une cellule de 0,25 degré) ; earthquakes lat, lon, radius_km (10 à 20000, 500 par défaut), min_magnitude (0 à 9, 2,5 par défaut) et hours (1 à 168, 24 par défaut) ; cyclones basins (séparés par des virgules at, ep, cp, wp ; tous par défaut) et facultativement lat, lon et radius_km (les tempêtes près de ce lieu) ; tides station (un ID de station de prévision des marées de NOAA, comme 9414290) ou lat et lon (la station la plus proche dans un rayon de 100 km, sinon invalid_request) ; launches aucun paramètre (les prochains lancements dans le monde) ; rates base (une devise de référence de la BCE, EUR par défaut) ; crypto symbols (ID CoinGecko ou symboles, séparés par des virgules, 20 au plus) et currency (usd par défaut) ; headlines url (une URL RSS ou Atom http ou https) ; cap (screenrig.cap/v1) les alertes CAP correspondant à un écran : url (répétable, jusqu’à 5 URL d’alertes CAP ou d’index ATOM/RSS), public (lit aussi les flux publics couvrant lat et lon ; par défaut sans url), lat et lon, geocode (codes de zone NAME:VALUE répétables), min_severity, max_severity, min_urgency, min_certainty, event, exclude_event, sender, status (Actual par défaut), scope (Public par défaut), language (répétable, par ordre de préférence) et area_unknown (hide ou show) ; drugalerts (screenrig.drugalerts/v1) les rapports de rappel récents d’un pays : country (us, ca ou gb, requis) et category (drug, par défaut, ou food) ; respiratory (screenrig.respiratory/v1) l’activité hebdomadaire de la grippe, de la COVID-19 et du VRS d’un lieu : country (us ou gb, requis) et region (un État, un territoire ou DC des États-Unis par nom ou code postal, ou l’Angleterre ou une région de l’UKHSA ; le pays si vide) ; almanac (screenrig.almanac/v1) les fêtes et jours commémoratifs, les événements On This Day, le soleil et la lune d’une date pour la carte today : country (un code ISO 3166-1 alpha-2, pour ses jours fériés), language (une édition On This Day : ar, bs, cs, de, en, es, fr, it, pt, ru, sv, tr, uk ou zh ; en par défaut), facultativement lat et lon (arrondis à une cellule de 0,1 degré, pour le soleil) et date (un jour fixe ; par défaut les jours autour d’aujourd’hui) ; outdoorsafety (screenrig.outdoorsafety/v1) la chaleur pour la carte outdoor-safety, une estimation de la température au thermomètre-globe mouillé, à partir de lat et lon (la cellule de 0,25 degré de la météo) ; il ne rapporte aucune foudre ; departures (screenrig.departures/v1) les prochains départs de un à quatre arrêts d’un fournisseur de données ouvertes : provider (tfl, entur ou digitransit) et stops (ID séparés par des virgules, 4 au plus : ID StopPoint de TfL, ID de lieu d’arrêt ou de quai NSR d’Entur, gtfsIds de Digitransit), fusionnés en un tableau dans l’ordre de départ et interrogés chaque minute ; bikeshare (screenrig.bikeshare/v1) les stations de vélos en libre-service GBFS les plus proches de lat et lon (arrondis à une cellule de 0,001 degré, environ 100 m), chacune avec sa distance à cette cellule, à partir de system (un ID de système listé) ou, sans lui, du système listé le plus proche qui couvre le lieu (invalid_request à system quand aucun ne le couvre).

La requête n’appelle jamais le fournisseur. 200 est le document (schéma, fetchedAt, attribution et les champs de la famille, comme le contrat des cartes les définit) ; son ETag est le sha256 des octets et If-None-Match répond 304 ; Cache-Control max-age court jusqu’à la prochaine récupération programmée. 202 signifie pas encore de document : la demande enregistrée en lecture, et le travailleur de flux récupère la clé en environ une minute (Retry-After).

Une lecture d’API conserve une clé récupérée pendant 24 heures. Une organisation enregistre au maximum 50 nouvelles clés par jour, tous projets confondus (rate_limited passé). Une famille sans source sur ce déploiement répond not_found.