Cartes : commandes CLI

Cartes

Découvrez les types de cartes, créez une instance et mettez à jour ses données en direct. Une liste de lecture place l’identifiant de carte retourné.

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 affiche le params_schema et le data_schema de la carte, ses propriétés statiques et dynamiques, son niveau, ses mises en page et son flux, ainsi qu’un exemple à copier dans une page de liste de lecture. card create renvoie l’identifiant crd_ de l’instance, et une relance identique après une réponse perdue réutilise la clé d’idempotence enregistrée.

card data put remplace le document immédiatement, sans republier la liste de lecture. La validation propre à la carte refuse un document qu’elle ne peut pas afficher (card_data_invalid), et une expiration vide les données sur chaque écran quand rien ne les renouvelle. card delete supprime l’instance et ses données, et répond resource_conflict (sortie 5) tant qu’une liste de lecture la place.

card preview dessine la carte dans un Chromium ou Chrome local et écrit un PNG ; il ne publie rien. Définissez SCREENRIG_BROWSER sur le chemin du navigateur si aucun des navigateurs habituels n’est installé. data.file est le chemin écrit et data.unrendered liste ce que l’aperçu n’a pas pu dessiner, par exemple un flux hôte que vous n’avez pas fourni. Ouvrez l’image avant de publier. Cartes intégrées décrit les mises en page, les propriétés et les flux de chaque carte.

Webhooks de carte

Un webhook de carte est une URL qui écrit le document de données d'une carte, de sorte qu'un système externe comme un CMS, un point de vente ou un script envoie des données à une carte avec un seul POST HTTP. kv webhook create, list, rotate-secret et delete acceptent --card CARD_ID à la place de --app-id, jamais les deux ; update et deliveries ci-dessous ne fonctionnent que sur les cartes. Une carte peut avoir au maximum 20 webhooks.

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 création d’un webhook de carte ne prend aucune clé. --map FILE (ou - pour stdin) est le mappage, --key-template écrit des documents par clé, --signing active la signature, et --verify et --handshake acceptent les envois propres à un fournisseur (Signatures et poignées de main des fournisseurs). La réponse contient data.secret et, si le webhook signe, data.signing_secret, chacun affiché une seule fois.

L'expéditeur s'authentifie comme pour un webhook d'application : Authorization: Bearer <secret> avec le secret srkw_…, ou HTTP Basic avec l'identifiant du webhook comme nom d'utilisateur, de sorte que https://kvw_ID:srkw_…@api.screenrig.ai/… convient à un expéditeur qui n'accepte qu'une URL. Le corps, d'au plus 1 Mio, est du JSON ou application/x-www-form-urlencoded ; un nom de formulaire répété devient un tableau. Sans mappage, l'objet envoyé est le document de données de la carte.

Un mappage est un modèle JSON qui construit le document à partir du corps. Une chaîne contenant des espaces réservés comme {{body.alert.title}} ou {{body.items[0].name}} est du texte, et une chaîne qui est exactement un espace réservé conserve le type de la valeur. Un chemin commence par body ou query (les paramètres de requête de l'URL), et un chemin qui ne contient rien est vide dans le texte et omet une valeur isolée. $each mappe un tableau avec item et index dans la portée, $group avec $by regroupe dans l'ordre de première apparition, $number lit 1,234.50, $3.50, 3,50 € ou 12% (ajoutez "$decimal": "," pour une virgule décimale), $bool lit true, yes, y, 1 et x, et $text avec $max tronque le texte. Le modèle est vérifié à l'enregistrement : invalid_request nomme l'endroit en cause.

{
  "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 écrit des documents par clé à la place du document propre à la carte. Le modèle est une clé de données de carte avec des jetons {screen.field.NAME}, comme room-{screen.field.room}, et l’objet mappé (ou le corps posté, sans mappage) ne contient qu’un tableau documents d’objets {fields, document} : chaque objet fields remplit le modèle et chaque document est écrit sous la clé qu’il produit. Un élément de page qui donne le même modèle comme data montre à chaque écran le document de ses propres champs. Chaque document est vérifié avant qu’aucun ne soit écrit, et une clé répétée est refusée. Un échec de stockage peut laisser une partie du lot écrite : renvoyez le même corps avec le même Idempotency-Key. Les clés qu’un envoi omet gardent leurs données, et un webhook ne fixe aucune expiration. Documents par clé montre un mappage.

Chaque envoi est vérifié comme les données de la carte elle-même : card_data_invalid nomme le chemin et rien n’est écrit. Un document identique à celui en cours de la carte reçoit la réponse unchanged et n’écrit rien, de sorte qu’aucun écran n’est réveillé. Un envoi accepté ne compte pas dans le plafond de requêtes d’agent, un webhook accepte au plus 120 envois par minute, et un en-tête Idempotency-Key déduplique les nouvelles tentatives d’un expéditeur pendant 24 heures.

Une mauvaise adresse, un secret erroné ou absent, un webhook désactivé, une signature absente ou erronée et chaque GET reçoivent la même réponse 404, de sorte qu'un aperçu de lien ou une supposition n'apprend rien. kv webhook deliveries en donne la raison.

Avec --signing, chaque envoi doit aussi porter ScreenRig-Signature: t=<unix seconds>,v1=<hex>, où v1 est le HMAC-SHA256 de t, d'un point et du corps brut sous le secret de signature whsec_…, et t doit être à moins de cinq minutes de l'horloge du serveur. C'est le format des signatures de webhook de screenRIG.

Signatures et poignées de main des fournisseurs

Les fournisseurs signent leurs envois à leur façon, et certains ne peuvent pas envoyer votre secret du tout. Un webhook de carte peut vérifier la signature du fournisseur à la place du secret et répondre à la poignée de main de configuration du fournisseur : GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana, Microsoft Graph, monday.com, Trello et Azure Event Grid y envoient donc directement, sans relais. Tout autre expéditeur qui signe avec HMAC fonctionne aussi. Définissez-les avec --verify et --handshake sur kv webhook create, et modifiez-les avec kv webhook update.

• --verify VENDOR accepte la signature propre à un fournisseur, avec --verify-secret-file FILE (ou - pour stdin, jamais en argument) qui contient le secret que le fournisseur affiche. Pour generic_hmac, --verify-header NAME nomme l’en-tête qui porte la signature, --verify-encoding vaut hex (par défaut) ou base64, --verify-timestamp-header NAME nomme un en-tête qui porte l’heure Unix, et --verify-tolerance SECONDS indique de combien elle peut s’écarter de l’horloge du serveur (300 par défaut). Un envoi qui porte la signature valide du fournisseur est accepté sans le secret srkw_ propre au webhook, qui continue de fonctionner à côté. Le secret du fournisseur est stocké chiffré et affiché seulement sous la forme set et d’un hint de ses quatre derniers caractères. Avec kv webhook update, --verify sans --verify-secret-file conserve le secret stocké tant que le fournisseur reste le même, et --clear-verify supprime la vérification et son secret. --verify et --signing s’excluent mutuellement.
• --handshake VENDOR est microsoft_graph, monday, trello ou azure_event_grid, et --clear-handshake le supprime. Slack et Asana répondent à leurs propres poignées de main par --verify.

La clé de chaque HMAC est le texte du secret tel que le fournisseur l’affiche (celui de Stripe comprend whsec_). Une signature est vérifiée sur le corps exactement tel qu’il est arrivé, en temps constant, avant que l’envoi ne consomme du budget d’écriture, et elle est jugée avant son horodatage : timestamp_stale signifie toujours que le secret était le bon. Un corps peut être du JSON, un formulaire ou multipart/form-data, où un champ de texte est body.FIELD et où les fichiers sont comptés, non lus.

Une poignée de main n’est traitée que pour un webhook configuré pour ce fournisseur, avant qu’aucun identifiant ne soit demandé, pour une requête qui est cette poignée de main, et jamais par un webhook désactivé. Elle n’écrit rien, n’est jamais facturée et ne consomme aucun budget de débit. Microsoft Graph, monday.com, Trello et Azure Event Grid n’envoient aucun en-tête que screenRIG vérifie : leurs envois ne sont donc acceptés qu’avec le secret du webhook. Azure Event Grid le transmet comme un en-tête de livraison statique, Authorization: Bearer srkw_…, marqué secret, et ses événements arrivent sous forme de tableau : un mappage lit donc 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 expéditeur qui signe avec son propre HMAC nomme l’en-tête, l’encodage et, s’il signe un horodatage, l’en-tête d’horodatage :

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"

Chaque échec donne le même 404 que tout autre refus. kv webhook deliveries montre la raison, et une poignée de main apparaît avec le résultat 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