Card: comandi CLI

Schede

Scopri i tipi di scheda, crea un’istanza e aggiorna i suoi dati in tempo reale. Una playlist colloca l’ID della scheda restituito.

screenrig cards list --category ops
screenrig cards show gauge
screenrig card create --type gauge --file gauge-params.json
screenrig card list
screenrig card show crd_01EXAMPLEGAUGE000000000
screenrig card params crd_01EXAMPLEGAUGE000000000 --file gauge-params.json
screenrig card data get crd_01EXAMPLEGAUGE000000000
screenrig card data put crd_01EXAMPLEGAUGE000000000 --file gauge-data.json --ttl 30m --expect-rev 1
screenrig card preview crd_01EXAMPLEGAUGE000000000 --output gauge.png
screenrig card delete crd_01EXAMPLEGAUGE000000000

cards show mostra params_schema e data_schema della scheda, le sue proprietà statiche e dinamiche, livello, layout e feed, e un esempio da copiare in una pagina di playlist. card create restituisce l’id crd_ dell’istanza, e una ripetizione identica dopo una risposta persa riutilizza la chiave di idempotenza salvata.

card data put sostituisce il documento subito, senza ripubblicare la playlist. La validazione della scheda rifiuta un documento che non può mostrare (card_data_invalid), e una scadenza svuota i dati su ogni schermo quando nulla li rinnova. card delete elimina l’istanza e i suoi dati e risponde resource_conflict (uscita 5) finché una playlist la colloca.

card preview disegna la scheda in un Chromium o Chrome locale e scrive un PNG; non pubblica nulla. Imposta SCREENRIG_BROWSER sul percorso del browser se non è installato nessuno di quelli abituali. data.file è il percorso scritto e data.unrendered elenca ciò che l’anteprima non ha potuto disegnare, per esempio un feed host che non hai fornito. Apri l’immagine prima di pubblicare. Schede integrate descrive i layout, le proprietà e i feed di ogni scheda.

Webhook delle schede

Un webhook di scheda è un URL che scrive il documento dati di una scheda, così un sistema esterno come un CMS, un punto vendita o uno script invia dati a una scheda con una singola richiesta HTTP POST. kv webhook create, list, rotate-secret e delete accettano --card CARD_ID al posto di --app-id, mai entrambi; update e deliveries qui sotto funzionano solo con le schede. Una scheda può avere al massimo 20 webhook.

kv webhook create --card CARD_ID [--description TEXT] [--map FILE|-] [--key-template TEMPLATE] [--signing]
                  [--verify VENDOR [--verify-secret-file FILE|-] [--verify-header NAME] [--verify-encoding hex|base64]
                   [--verify-timestamp-header NAME] [--verify-tolerance SECONDS]] [--handshake VENDOR]
kv webhook list --card CARD_ID
kv webhook rotate-secret <webhook_id> --card CARD_ID [--signing]
kv webhook delete <webhook_id> --card CARD_ID

La creazione di un webhook di scheda non richiede una chiave. --map FILE (o - per stdin) è la mappatura, --key-template scrive documenti per chiave, --signing attiva la firma, e --verify e --handshake accettano gli invii propri di un fornitore (Firme e handshake dei fornitori). La risposta contiene data.secret e, se il webhook firma, data.signing_secret, ciascuno mostrato una sola volta.

Il mittente si autentica come per un webhook di applicazione: Authorization: Bearer <secret> con il segreto srkw_…, oppure HTTP Basic con l'ID del webhook come nome utente, quindi https://kvw_ID:srkw_…@api.screenrig.ai/… va bene per un mittente che accetta solo un URL. Il corpo, al massimo 1 MiB, è JSON oppure application/x-www-form-urlencoded; un nome di modulo ripetuto diventa un array. Senza mappatura, l'oggetto inviato è il documento dati della scheda.

Una mappatura è un modello JSON che costruisce il documento dal corpo. Una stringa con segnaposto come {{body.alert.title}} o {{body.items[0].name}} è testo, e una stringa che è esattamente un segnaposto mantiene il tipo del valore. Un percorso inizia con body o query (i parametri di query dell'URL), e un percorso che non contiene nulla è vuoto nel testo e omette un valore isolato. $each mappa un array con item e index nell'ambito, $group con $by raggruppa nell'ordine della prima comparsa, $number legge 1,234.50, $3.50, 3,50 € o 12% (aggiungi "$decimal": "," per la virgola decimale), $bool legge true, yes, y, 1 e x, e $text con $max taglia il testo. Il modello viene controllato al salvataggio: invalid_request indica il punto che ha fallito.

{
  "title": "{{body.alert.title}}",
  "body": "{{body.alert.message}}",
  "items": { "$each": "{{body.items}}", "$limit": 20, "$template": { "text": "{{item.name}}" } }
}

curl https://api.screenrig.ai/api/cards/crd_01EXAMPLEBOARD0000000000/kv-webhooks/kvw_01EXAMPLEWEBHOOK00000/write \
  -H "Authorization: Bearer $CARD_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  --data '{"alert":{"title":"Fire drill","message":"Leave by the east door"},"items":[{"name":"Floor 2"}]}'

--key-template TEMPLATE scrive documenti per chiave al posto del documento proprio della scheda. Il modello è una chiave dati della scheda con token {screen.field.NAME}, come room-{screen.field.room}, e l’oggetto mappato (o il corpo inviato, senza mappatura) contiene solo un array documents di oggetti {fields, document}: ogni oggetto fields riempie il modello e ogni document viene scritto sotto la chiave che produce. Un elemento di pagina che indica lo stesso modello come data mostra a ogni schermo il documento dei suoi campi. Ogni documento viene verificato prima che ne venga scritto qualcuno, e una chiave ripetuta viene rifiutata. Un errore di archiviazione può lasciare scritta una parte del lotto: reinvia lo stesso corpo con lo stesso Idempotency-Key. Le chiavi che un invio omette mantengono i loro dati, e un webhook non imposta alcuna scadenza. Documenti per chiave mostra una mappatura.

Ogni invio viene controllato come dati della scheda stessa: card_data_invalid indica il percorso e non viene scritto nulla. Un documento uguale a quello attuale della scheda riceve la risposta unchanged e non scrive nulla, quindi nessuno schermo viene risvegliato. Un invio accettato non conta nel limite di richieste agente, un webhook accetta al massimo 120 invii al minuto e un’intestazione Idempotency-Key deduplica i nuovi tentativi di un mittente per 24 ore.

Un indirizzo sbagliato, un segreto errato o mancante, un webhook disattivato, una firma mancante o errata e ogni GET ricevono la stessa risposta 404, così un'anteprima di link o un tentativo non rivela nulla. kv webhook deliveries ne spiega il motivo.

Con --signing, ogni invio deve anche includere ScreenRig-Signature: t=<unix seconds>,v1=<hex>, dove v1 è l'HMAC-SHA256 di t, un punto e il corpo grezzo con il segreto di firma whsec_…, e t deve distare al massimo cinque minuti dall'orologio del server. È il formato delle firme dei webhook di screenRIG.

Firme e handshake dei fornitori

I fornitori firmano i loro invii a modo loro, e alcuni non possono inviare affatto il tuo segreto. Un webhook di scheda può verificare la firma del fornitore al posto del segreto e rispondere all’handshake di configurazione del fornitore, così GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana, Microsoft Graph, monday.com, Trello e Azure Event Grid inviano direttamente, senza intermediari. Funziona anche qualsiasi altro mittente che firma con HMAC. Impostali con --verify e --handshake su kv webhook create e modificali con kv webhook update.

• --verify VENDOR accetta la firma propria di un fornitore, con --verify-secret-file FILE (o - per stdin, mai come argomento) che contiene il segreto mostrato dal fornitore. Per generic_hmac, --verify-header NAME indica l’intestazione che porta la firma, --verify-encoding è hex (predefinito) o base64, --verify-timestamp-header NAME indica un’intestazione che porta l’ora Unix, e --verify-tolerance SECONDS è quanto può discostarsi dall’orologio del server (300 per impostazione predefinita). Un invio che porta la firma valida del fornitore viene accettato senza il segreto srkw_ del webhook, che continua a funzionare accanto. Il segreto del fornitore è memorizzato sigillato e mostrato solo come set e un hint dei suoi ultimi quattro caratteri. Con kv webhook update, --verify senza --verify-secret-file mantiene il segreto memorizzato finché il fornitore resta lo stesso, e --clear-verify rimuove la verifica e il suo segreto. --verify e --signing si escludono a vicenda.
• --handshake VENDOR è microsoft_graph, monday, trello o azure_event_grid, e --clear-handshake lo rimuove. Slack e Asana rispondono ai propri handshake tramite --verify.

La chiave di ogni HMAC è il testo del segreto come lo mostra il fornitore (quello di Stripe include whsec_). Una firma viene verificata sul corpo esattamente come è arrivato, in tempo costante, prima che l’invio consumi budget di scrittura, e viene giudicata prima della sua marca temporale: timestamp_stale significa sempre che il segreto era giusto. Un corpo può essere JSON, un modulo o multipart/form-data, dove un campo di testo è body.FIELD e i file vengono contati, non letti.

Un handshake riceve risposta solo per un webhook configurato per quel fornitore, prima che venga richiesta qualsiasi credenziale, a una richiesta che è quell’handshake, e mai da un webhook disattivato. Non scrive nulla, non viene mai fatturato e non consuma budget di frequenza. Microsoft Graph, monday.com, Trello e Azure Event Grid non inviano alcuna intestazione che screenRIG verifichi, quindi le loro consegne sono accettate solo con il segreto del webhook. Azure Event Grid lo porta come intestazione di consegna statica, Authorization: Bearer srkw_…, contrassegnata come segreta, e i suoi eventi arrivano come array, quindi una mappatura legge body[0].

echo '{"title":"{{body.repository.full_name}}","body":"{{body.head_commit.message}}"}' |
  screenrig kv webhook create --card crd_01EXAMPLEBOARD0000000000 --description "Pushes" \
    --verify github --verify-secret-file github.secret --map -

Un mittente che firma con il proprio HMAC indica l’intestazione, la codifica e, se firma una marca temporale, l’intestazione della marca temporale:

echo '{"title":"{{body.sensor}}","body":"{{body.state}}"}' |
  screenrig kv webhook create --card crd_01EXAMPLEBOARD0000000000 --verify generic_hmac --verify-secret-file acme.secret \
    --verify-header X-Acme-Signature --verify-encoding base64 --verify-timestamp-header X-Acme-Time --verify-tolerance 120 \
    --map -

ts=$(date +%s); body='{"sensor":"door","state":"open"}'
sig=$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$SECRET" -binary | openssl base64 -A)
curl "$URL" -H "Content-Type: application/json" -H "X-Acme-Time: $ts" -H "X-Acme-Signature: $sig" -d "$body"

Ogni errore dà lo stesso 404 di qualsiasi altro rifiuto. kv webhook deliveries mostra il motivo, e un handshake compare con l’esito handshake:

kv webhook update <webhook_id> --card CARD_ID [--description TEXT] [--map FILE|-] [--clear-map]
                   [--key-template TEMPLATE] [--clear-key-template] [--enable|--disable] [--signing|--no-signing]
                   [--verify VENDOR [--verify-secret-file FILE|-] [--verify-header NAME] [--verify-encoding hex|base64]
                    [--verify-timestamp-header NAME] [--verify-tolerance SECONDS]] [--clear-verify]
                   [--handshake VENDOR] [--clear-handshake]

screenrig kv webhook update kvw_01EXAMPLEWEBHOOK00000 --card crd_01EXAMPLEBOARD0000000000 --map alert-map.json
screenrig kv webhook update kvw_01EXAMPLEWEBHOOK00000 --card crd_01EXAMPLEBOARD0000000000 --verify stripe --verify-secret-file stripe.secret
screenrig kv webhook update kvw_01EXAMPLEWEBHOOK00000 --card crd_01EXAMPLEBOARD0000000000 --clear-verify

kv webhook deliveries <webhook_id> --card CARD_ID [--limit N]

screenrig kv webhook deliveries kvw_01EXAMPLEWEBHOOK00000 --card crd_01EXAMPLEBOARD0000000000