API Dati card

Scopri le schede integrate dal catalogo pubblicato di questo ambiente, unito al floor fornito. Aggiornamenti e verifica dello schema avvengono in background; questa rotta non chiama mai il bucket edge. Ogni voce elenca la copia corrente, il livello e i layout consentiti da quel livello, e ogni major servito.

Gli schemi JSON autonomi della major corrente per i params dei posizionamenti e per i documenti card-data, lo schema del feed, il tier, i layout consentiti e un posizionamento di esempio. I params contrassegnati come dynamic provengono dal documento dati quando un posizionamento collega una chiave data.

Un parametro stringa può contenere {screen.name}, {screen.timezone} e {screen.field.NAME}, e un parametro location può essere la stringa {screen.location}; il backend li espande per ogni schermo. Sostituisci i valori dei contenuti di esempio prima di pubblicare. Gli id sconosciuti rispondono con card_not_found (404).

Un UID carta globale, o un segmento di tipo catalogo deprecato. Quest’ultimo aggiunge intestazioni Deprecation e Warning che puntano a /api/card-types.

If-Match confronta opzionalmente la revisione dei metadati della scheda (non la revisione dei dati); l’omissione aggiorna la revisione corrente. Idempotency-Key lega metodo, UID, parametri e If-Match per 24 ore. Un retry riproduce il risultato registrato, incluso 204 dopo la cancellazione; input modificato restituisce idempotency_mismatch. If-Match obsoleto restituisce revision_conflict (412).

Le chiavi sono limitate all’UID della scheda.

If-Match confronta opzionalmente la revisione dei metadati della scheda (non la revisione dei dati); l’omissione aggiorna la revisione corrente. Idempotency-Key lega metodo, UID, parametri e If-Match per 24 ore. Un retry riproduce il risultato registrato, incluso 204 dopo la cancellazione; input modificato restituisce idempotency_mismatch. If-Match obsoleto restituisce revision_conflict (412).

Le chiavi sono limitate all’UID della scheda.

Elenca i webhook in ingresso della scheda, dal più vecchio (al massimo 20). I segreti non vengono mai restituiti qui.

Crea un webhook che scrive il documento di dati di questa scheda: un sistema esterno invia un corpo JSON o di modulo al suo url (POST /api/cards/{id}/kv-webhooks/{webhook_id}/write).

Senza una mappatura l’oggetto inviato è il documento; un modello di mappatura lo costruisce dal corpo e viene controllato al salvataggio. signing true richiede anche un’intestazione ScreenRig-Signature. verify fa autenticare un invio dalla firma propria di un fornitore (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana o qualsiasi mittente HMAC) al posto del segreto, che continua a funzionare accanto; non può essere combinato con signing, e il suo segreto è sigillato e non viene mai restituito, solo un suggerimento. handshake indica un handshake di fornitore a cui risponde l’url (Microsoft Graph, monday.com, Trello o Azure Event Grid; verify slack e asana rispondono al proprio).

La risposta è l’unico posto in cui compaiono il segreto e il segreto di firma (insieme a rotate-secret e all’aggiornamento che attiva la firma): memorizzali subito nel sistema mittente. Una scheda può avere al massimo 20 webhook (kv_webhook_limit_reached). Aggiunge kv_webhook.created.

Un nuovo tentativo identico con la stessa Idempotency-Key restituisce la stessa risposta, segreti compresi, per ventiquattro ore.

Modifica description, mapping (null lo rimuove), enabled, signing, verify (null lo rimuove; senza un segreto conserva quello memorizzato quando il fornitore è lo stesso) e handshake (null lo rimuove). Attivare signing risponde il nuovo signing_secret una sola volta; false lo disattiva. Un webhook disattivato risponde a ogni invio come a un segreto sbagliato. Aggiunge kv_webhook.updated.

Elimina il webhook. Il suo URL smette di funzionare immediatamente; la scheda mantiene il suo documento. Aggiunge kv_webhook.deleted.

Sostituisce il segreto del webhook e restituisce quello nuovo una sola volta; con signing true sostituisce invece il segreto di firma. Il vecchio smette di funzionare immediatamente. Aggiunge kv_webhook.secret_rotated.

Il registro delle consegne del webhook, dal più recente, al massimo 100, conservato per sette giorni.

Ogni invio che ha indicato questo webhook è una riga con la sua ora, l’esito (written, unchanged, refused, invalid o handshake), il motivo (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 breve dettaglio come il percorso dei dati della scheda che ha fallito, lo stato della risposta, la dimensione del corpo e il numero di parti di file che un invio multipart portava (ignorate).

Non viene memorizzato alcun corpo, intestazione o credenziale. Qui un progetto vede perché un invio ha ricevuto il 404 che ogni rifiuto condivide.

L’URL a cui un sistema esterno invia il documento dati di una scheda. Si autentica con il segreto proprio del webhook nell’intestazione Authorization: Bearer <secret>, oppure HTTP Basic con l’ID del webhook come nome utente.

Quando il webhook è stato creato con verify, una firma valida nell’intestazione propria di quel fornitore (vedi WebhookVerifyWrite) autentica l’invio al posto del segreto, che continua a funzionare accanto.

Quando il webhook firma, è richiesto anche ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret>, e t deve distare al massimo cinque minuti dall’orologio del server.

Una scheda o un webhook sconosciuti, un segreto o una firma sbagliati o mancanti, un timestamp scaduto, un webhook disattivato e ogni GET ricevono lo stesso 404 not_found; il progetto vede il motivo nel registro delle consegne.

Un webhook configurato per un handshake di fornitore risponde per primo, prima che venga richiesta qualsiasi credenziale, a una richiesta che è quell’handshake: la sfida url_verification di Slack (firmata, risposta con la sfida), il validationToken di Microsoft Graph (restituito come text/plain), l’X-Hook-Secret di Asana (restituito e conservato sigillato come segreto di firma dei suoi eventi), la challenge di monday.com, il SubscriptionValidationEvent di Azure Event Grid (risposta con il suo validationResponse) e il controllo HEAD di Trello (l’operazione head di questo url).

Un handshake non scrive dati della scheda, non viene mai fatturato e non consuma budget di frequenza, ed è registrato nel registro delle consegne con l’esito handshake.

Il corpo, al massimo 1 MiB, è JSON, application/x-www-form-urlencoded (un nome ripetuto è un array) o multipart/form-data (ogni campo di testo è body.<field>, un nome ripetuto è un array, e le parti di file vengono ignorate e contate nel registro delle consegne). Senza una mappatura l’oggetto è il documento; con una, il modello lo costruisce da body e query.

Il documento viene controllato come dati della scheda (card_data_invalid indica il percorso), e uno uguale al documento attuale non viene scritto (stato unchanged). Un invio accettato è una richiesta API fatturata e aggiunge gli eventi dei dati della scheda. Idempotency-Key (da 8 a 200 caratteri) deduplica i nuovi tentativi di un mittente per ventiquattro ore.

Al massimo 120 invii al minuto per webhook; ciascuno conta anche per le frequenze di scrittura dell’organizzazione e della scheda (PUT /api/card-data/{key}).

Il controllo che Trello fa su un nuovo webhook. Risponde 200 senza corpo per un webhook il cui handshake è trello, e l’unico 404 not_found per ogni altro webhook, indirizzo e richiesta, così un’anteprima di link non apprende nulla. Non scrive nulla, non viene mai fatturato e non consuma budget di frequenza; il controllo a cui si è risposto compare nel registro delle consegne con l’esito handshake.

Ogni GET risponde il 404 e non legge nulla.

Elenca i documenti dati delle schede del progetto, al massimo 200 in ordine crescente di chiave. next_cursor è l’ultima chiave restituita; va passato come after per la pagina successiva, null se non ce ne sono altre. I documenti dati delle schede contengono le proprietà dinamiche delle posizioni delle schede (sezioni menu, elementi ticker, riquadri KPI); la chiave dati della posizione ne indica una.

Restituisce il documento e la sua revisione. L’ETag è la revisione, per If-Match sulla prossima scrittura.

Crea o sostituisce un documento dati scheda. Quando le posizioni delle schede nelle playlist del progetto vincolano la chiave, il documento deve contenere solo le proprietà dinamiche di ogni scheda vincolata e validare contro di esse; altrimenti la scrittura è rifiutata con card_data_invalid nominando la scheda e il percorso della proprietà, e nulla cambia. Una chiave non vincolata ad alcuna posizione accetta qualsiasi oggetto JSON.

Ogni stringa che inizia con media: è un riferimento a contenuti multimediali, media:<id>, che una scheda deve disegnare (una foto); su qualsiasi chiave deve nominare un’immagine pronta e approvata in questo progetto, al massimo 256 media distinti per documento, o la scrittura è rifiutata con card_media_invalid che nomina il percorso proprietà e media_id.

Gli schermi il cui contenuto legge la chiave possono quindi recuperare quei contenuti multimediali da GET /media/{media_id}. Gli schermi che mostrano un posizionamento che legge la chiave ricevono screen.card_data_changed e lo recuperano nuovamente in loco; il registro del progetto registra kv.updated con una risorsa card_data_entry, che non raggiunge mai un lettore.

Limiti, quote, misurazioni, revisioni e idempotenza sono quelli dell’archivio K/V dell’applicazione.

Anche le scritture di agenti e webhook hanno un limite di frequenza, per organizzazione in base al piano (Standard e Plus 60 al minuto, Education e Premium 600, Enterprise 3.000) e 60 al minuto per chiave su ogni piano; una scrittura oltre il limite viene rifiutata con rate_limited e Retry-After e non viene misurata.

Elimina un documento dati carta. Una carta associata alla chiave è nascosta sul vetro finché un documento non viene riscritto.

Legge un documento feed di terze parti condiviso: lo stesso documento che una scheda integrata con gli stessi parametri legge (docs/feeds.md).

I parametri di query vengono normalizzati nella chiave di feed della scheda, indicata dall’intestazione ScreenRig-Feed-Key: weather, airquality e alerts accettano lat e lon (arrotondati a una cella di 0,25 gradi); earthquakes lat, lon, radius_km (da 10 a 20000, 500 per impostazione predefinita), min_magnitude (da 0 a 9, 2,5 per impostazione predefinita) e hours (da 1 a 168, 24 per impostazione predefinita); cyclones basins (separati da virgole at, ep, cp, wp; tutti per impostazione predefinita) e facoltativamente lat, lon e radius_km (le tempeste vicino a quel luogo); tides station (un ID di stazione di previsione delle maree NOAA, come 9414290) oppure lat e lon (la stazione più vicina entro 100 km, altrimenti invalid_request); launches nessun parametro (i prossimi lanci nel mondo); rates base (una valuta di riferimento BCE, EUR per impostazione predefinita); crypto symbols (ID CoinGecko o ticker, separati da virgole, al massimo 20) e currency (usd per impostazione predefinita); headlines url (un URL RSS o Atom http o https); cap (screenrig.cap/v1) gli avvisi CAP che corrispondono a uno schermo: url (ripetibile, fino a 5 URL di avvisi CAP o di indici ATOM/RSS), public (legge anche i feed pubblici che coprono lat e lon; predefinito quando non c’è url), lat e lon, geocode (codici di area NAME:VALUE ripetibili), min_severity, max_severity, min_urgency, min_certainty, event, exclude_event, sender, status (Actual per impostazione predefinita), scope (Public per impostazione predefinita), language (ripetibile, in ordine di preferenza) e area_unknown (hide o show); drugalerts (screenrig.drugalerts/v1) i rapporti di richiamo recenti di un paese: country (us, ca o gb, obbligatorio) e category (drug, il predefinito, o food); respiratory (screenrig.respiratory/v1) l’attività settimanale di influenza, COVID-19 e VRS di un luogo: country (us o gb, obbligatorio) e region (uno stato, territorio o DC degli USA per nome o codice postale, oppure l’Inghilterra o una regione dell’UKHSA; il paese se vuoto); almanac (screenrig.almanac/v1) le ricorrenze, gli eventi di On This Day, il sole e la luna di una data per la scheda today: country (un codice ISO 3166-1 alpha-2, per i suoi giorni festivi), language (un’edizione di On This Day: ar, bs, cs, de, en, es, fr, it, pt, ru, sv, tr, uk o zh; en per impostazione predefinita), facoltativamente lat e lon (arrotondati a una cella di 0,1 gradi, per il sole) e date (un giorno fisso; per impostazione predefinita i giorni intorno a oggi); outdoorsafety (screenrig.outdoorsafety/v1) il caldo per la scheda outdoor-safety, una stima della temperatura di bulbo umido e globo, da lat e lon (la cella di 0,25 gradi del meteo); non segnala fulmini; departures (screenrig.departures/v1) le prossime partenze da una a quattro fermate di un provider di dati aperti: provider (tfl, entur o digitransit) e stops (ID separati da virgole, al massimo 4: ID StopPoint di TfL, ID di luogo di fermata o banchina NSR di Entur, gtfsIds di Digitransit), uniti in un unico tabellone in ordine di partenza e interrogati ogni minuto; bikeshare (screenrig.bikeshare/v1) le stazioni di bike sharing GBFS più vicine a lat e lon (arrotondati a una cella di 0,001 gradi, circa 100 m), ciascuna con la sua distanza da quella cella, da system (un ID di sistema elencato) o, senza di esso, dal sistema elencato più vicino che copre il luogo (invalid_request su system dove nessuno lo copre).

La richiesta non chiama mai il provider. 200 è il documento (schema, fetchedAt, attribution e i campi della famiglia, come definiti dal contratto delle card); il suo ETag è lo sha256 dei byte e If-None-Match risponde 304; Cache-Control max-age dura fino al prossimo fetch programmato. 202 significa nessun documento ancora: la domanda di lettura è registrata e il feed worker recupera la chiave entro circa un minuto (Retry-After).

Una lettura API mantiene una chiave recuperata per 24 ore. Un’organizzazione registra al massimo 50 nuove chiavi al giorno in tutti i suoi progetti (rate_limited oltre). Una famiglia senza origine su questa distribuzione risponde not_found.