Karten: CLI-Befehle

Karten

Entdecken Sie Kartentypen, erstellen Sie eine Instanz und aktualisieren Sie deren Live-Daten. Eine Playlist platziert die zurückgegebene Karten-ID.

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 gibt params_schema und data_schema der Karte aus, ihre statischen und dynamischen Eigenschaften, Stufe, Layouts und Feed sowie ein Beispiel zum Kopieren in eine Playlist-Seite. card create liefert die crd_-ID der Instanz, und eine identische Wiederholung nach einer verlorenen Antwort verwendet den gespeicherten Idempotenzschlüssel.

card data put ersetzt das Dokument sofort, ohne die Playlist neu zu veröffentlichen. Die eigene Validierung der Karte lehnt ein Dokument ab, das sie nicht anzeigen kann (card_data_invalid), und ein Ablauf leert die Daten auf jedem Bildschirm, wenn sie nichts erneuert. card delete löscht die Instanz und ihre Daten und antwortet mit resource_conflict (Exit 5), solange eine Playlist sie platziert.

card preview zeichnet die Karte in einem lokalen Chromium oder Chrome und schreibt ein PNG; es wird nichts veröffentlicht. Setzen Sie SCREENRIG_BROWSER auf den Pfad des Browsers, wenn keiner der üblichen installiert ist. data.file ist der geschriebene Pfad, und data.unrendered listet auf, was die Vorschau nicht zeichnen konnte, etwa einen Host-Feed, den Sie nicht geliefert haben. Öffnen Sie das Bild, bevor Sie veröffentlichen. Eingebaute Karten beschreibt Layouts, Eigenschaften und Feeds jeder Karte.

Karten-Webhooks

Ein Karten-Webhook ist eine URL, die das Datendokument einer Karte schreibt, sodass ein externes System wie ein CMS, eine Verkaufsstelle oder ein Skript mit einem einzigen HTTP POST Daten an eine Karte sendet. kv webhook create, list, rotate-secret und delete akzeptieren --card CARD_ID anstelle von --app-id, nie beides; update und deliveries unten funktionieren nur für Karten. Eine Karte hat höchstens 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

Beim Erstellen eines Karten-Webhooks ist kein Schlüssel nötig. --map FILE (oder - für stdin) ist das Mapping, --key-template schreibt Dokumente mit Schlüsseln, --signing schaltet die Signierung ein, und --verify und --handshake akzeptieren die eigenen Zustellungen eines Anbieters (Signaturen und Handshakes der Anbieter). Die Antwort enthält data.secret und, wenn der Webhook signiert, data.signing_secret, jeweils nur einmal angezeigt.

Der Absender authentifiziert sich wie bei einem Anwendungs-Webhook: Authorization: Bearer <secret> mit dem Geheimnis srkw_… oder HTTP Basic mit der Webhook-ID als Benutzername, sodass https://kvw_ID:srkw_…@api.screenrig.ai/… für einen Absender geeignet ist, der nur eine URL annimmt. Der Body, höchstens 1 MiB, ist JSON oder application/x-www-form-urlencoded; ein wiederholter Formularname wird zu einem Array. Ohne Mapping ist das gesendete Objekt das Datendokument der Karte.

Ein Mapping ist eine JSON-Vorlage, die das Dokument aus dem Body aufbaut. Ein String mit Platzhaltern wie {{body.alert.title}} oder {{body.items[0].name}} ist Text, und ein String, der genau ein Platzhalter ist, behält den Typ des Werts. Ein Pfad beginnt mit body oder query (die Abfrageparameter der URL), und ein Pfad, der nichts enthält, ist im Text leer und lässt einen einzelnen Wert weg. $each bildet ein Array ab, mit item und index im Gültigkeitsbereich, $group mit $by gruppiert in der Reihenfolge des ersten Auftretens, $number liest 1,234.50, $3.50, 3,50 € oder 12% (fügen Sie "$decimal": "," für ein Dezimalkomma hinzu), $bool liest true, yes, y, 1 und x, und $text mit $max kürzt Text. Die Vorlage wird beim Speichern geprüft: invalid_request nennt die fehlerhafte Stelle.

{
  "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 schreibt Dokumente mit Schlüsseln anstelle des eigenen Dokuments der Karte. Die Vorlage ist ein Kartendaten-Schlüssel mit {screen.field.NAME}-Platzhaltern, etwa room-{screen.field.room}, und das gemappte Objekt (oder der gesendete Body ohne Mapping) enthält nur ein documents-Array aus {fields, document}-Objekten: Jedes fields-Objekt füllt die Vorlage, und jedes document wird unter dem Schlüssel geschrieben, den es ergibt. Ein Seitenelement, das dieselbe Vorlage als data angibt, zeigt jedem Bildschirm das Dokument seiner eigenen Felder. Jedes Dokument wird geprüft, bevor eines geschrieben wird, und ein wiederholter Schlüssel wird abgelehnt. Ein Speicherfehler kann einen Teil des Stapels geschrieben zurücklassen: Senden Sie denselben Body mit demselben Idempotency-Key erneut. Schlüssel, die eine Zustellung auslässt, behalten ihre Daten, und ein Webhook setzt kein Ablaufdatum. Dokumente mit Schlüsseln zeigt ein Mapping.

Jeder Post wird als Daten der Karte selbst geprüft: card_data_invalid nennt den Pfad, und nichts wird geschrieben. Ein Dokument, das dem aktuellen der Karte entspricht, wird mit unchanged beantwortet und schreibt nichts, sodass kein Bildschirm geweckt wird. Ein akzeptierter Post zählt nicht zum Limit für Agentenanfragen, ein Webhook nimmt höchstens 120 Posts pro Minute an, und ein Idempotency-Key-Header dedupliziert die Wiederholungen eines Absenders 24 Stunden lang.

Eine falsche Adresse, ein falsches oder fehlendes Geheimnis, ein deaktivierter Webhook, eine fehlende oder falsche Signatur und jedes GET werden mit demselben 404 beantwortet, sodass eine Link-Vorschau oder ein Raten nichts verrät. kv webhook deliveries nennt den Grund.

Mit --signing muss jeder Post außerdem ScreenRig-Signature: t=<unix seconds>,v1=<hex> tragen, wobei v1 der HMAC-SHA256 von t, einem Punkt und dem rohen Body unter dem Signaturgeheimnis whsec_… ist und t höchstens fünf Minuten von der Serveruhr abweichen darf. Es ist das Format der eigenen Webhook-Signaturen von screenRIG.

Signaturen und Handshakes der Anbieter

Anbieter signieren ihre Zustellungen auf ihre eigene Weise, und manche können Ihr Secret gar nicht senden. Ein Karten-Webhook kann die Signatur des Anbieters anstelle des Secrets prüfen und den Einrichtungs-Handshake des Anbieters beantworten, sodass GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana, Microsoft Graph, monday.com, Trello und Azure Event Grid direkt an ihn senden, ohne Zwischenstation. Jeder andere Sender, der mit HMAC signiert, funktioniert ebenfalls. Setzen Sie sie mit --verify und --handshake bei kv webhook create und ändern Sie sie mit kv webhook update.

• --verify VENDOR akzeptiert die eigene Signatur eines Anbieters; --verify-secret-file FILE (oder - für stdin, nie als Argument) enthält das Secret, das der Anbieter anzeigt. Für generic_hmac benennt --verify-header NAME den Header, der die Signatur trägt, --verify-encoding ist hex (Standard) oder base64, --verify-timestamp-header NAME benennt einen Header mit der Unix-Zeit, und --verify-tolerance SECONDS gibt an, wie weit sie von der Uhr des Servers abweichen darf (standardmäßig 300). Eine Zustellung mit der gültigen Signatur des Anbieters wird ohne das eigene srkw_-Secret des Webhooks akzeptiert, das daneben weiter funktioniert. Das Secret des Anbieters wird versiegelt gespeichert und nur als set und ein hint seiner letzten vier Zeichen angezeigt. Bei kv webhook update behält --verify ohne --verify-secret-file das gespeicherte Secret, solange der Anbieter derselbe bleibt, und --clear-verify entfernt die Prüfung samt Secret. --verify und --signing schließen sich gegenseitig aus.
• --handshake VENDOR ist microsoft_graph, monday, trello oder azure_event_grid, und --clear-handshake entfernt ihn. Slack und Asana beantworten ihre eigenen Handshakes über --verify.

Der Schlüssel jedes HMAC ist der Text des Secrets, wie ihn der Anbieter zeigt (bei Stripe einschließlich whsec_). Eine Signatur wird am Body genau so geprüft, wie er ankam, in konstanter Zeit, bevor die Zustellung Schreibbudget verbraucht, und sie wird vor ihrem Zeitstempel beurteilt: timestamp_stale bedeutet immer, dass das Secret stimmte. Ein Body kann JSON, ein Formular oder multipart/form-data sein, wobei ein Textfeld body.FIELD ist und Dateien gezählt, nicht gelesen werden.

Ein Handshake wird nur für einen Webhook beantwortet, der für diesen Anbieter eingerichtet ist, bevor irgendwelche Zugangsdaten verlangt werden, auf eine Anfrage, die dieser Handshake ist, und nie von einem deaktivierten Webhook. Er schreibt nichts, wird nie abgerechnet und verbraucht kein Ratenbudget. Microsoft Graph, monday.com, Trello und Azure Event Grid senden keinen Header, den screenRIG prüft, daher werden ihre Zustellungen nur mit dem Secret des Webhooks akzeptiert. Azure Event Grid übergibt es als statischen Zustell-Header, Authorization: Bearer srkw_…, als geheim markiert, und seine Ereignisse kommen als Array an, sodass eine Zuordnung body[0] liest.

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 -

Ein Sender, der mit seinem eigenen HMAC signiert, nennt den Header, die Codierung und, wenn er einen Zeitstempel signiert, den Zeitstempel-Header:

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"

Jeder Fehler ergibt dasselbe 404 wie jede andere Ablehnung. kv webhook deliveries zeigt den Grund, und ein Handshake erscheint mit dem Ergebnis 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