カード CLI コマンド

カード

カードの種類を調べ、インスタンスを作成し、そのライブデータを更新します。プレイリストには返されたカード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 はカードの params_schema と data_schema、静的・動的プロパティ、ティア、レイアウト、フィード、およびプレイリストのページにコピーできる例を表示します。card create はインスタンスの crd_ ID を返し、応答が失われたあとに同じコマンドを再実行すると、保存済みの冪等キーが再利用されます。

card data put はプレイリストを再公開せずに、ドキュメントを即座に置き換えます。カード自身の検証は、表示できないドキュメントを拒否します（card_data_invalid）。有効期限を設定すると、何も更新しない場合にすべてのスクリーンでデータが空になります。card delete はインスタンスとそのデータを削除し、プレイリストが配置している間は resource_conflict（exit 5）を返します。

card preview はローカルの Chromium または Chrome でカードを描画して PNG を書き出します。何も公開しません。通常のブラウザーがどれもインストールされていない場合は、SCREENRIG_BROWSER にブラウザーのパスを設定してください。data.file は書き出したパス、data.unrendered はプレビューで描画できなかったもの（たとえば指定しなかったホストフィード）の一覧です。公開する前に画像を開いて確認してください。組み込みカードでは、各カードのレイアウト、プロパティ、フィードを説明しています。

カードWebhook

カードWebhookは、1枚のカードのデータドキュメントを書き込むURLです。CMS、POS、スクリプトなどの外部システムが、HTTP POST 1回でカードにデータを送れます。kv webhook create、list、rotate-secret、delete は --app-id の代わりに --card CARD_ID を受け付け、両方は指定できません。以下の update と deliveries はカード専用です。カードは最大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

カードWebhookの作成にキーは不要です。--map FILE（stdin の場合は -）がマッピングで、--key-template でキー別ドキュメントを書き込み、--signing で署名を有効にし、--verify と --handshake でベンダー独自の送信を受け付けます（ベンダーの署名とハンドシェイク）。レスポンスには data.secret と、署名する場合は data.signing_secret が含まれ、それぞれ一度だけ表示されます。

送信側の認証はアプリケーションWebhookと同じです。srkw_… シークレットを使った Authorization: Bearer <secret>、またはWebhook IDをユーザー名にしたHTTP Basicで認証するため、URLしか受け付けない送信側には https://kvw_ID:srkw_…@api.screenrig.ai/… が使えます。ボディは最大1 MiBのJSONまたは application/x-www-form-urlencoded で、繰り返されたフォーム名は配列になります。マッピングがない場合、送信されたオブジェクトがカードのデータドキュメントになります。

マッピングは、リクエストボディからドキュメントを組み立てるJSONテンプレートです。{{body.alert.title}} や {{body.items[0].name}} のようなプレースホルダーを含む文字列はテキストになり、プレースホルダー1つだけの文字列は値の型を保ちます。パスは body または query（URLのクエリパラメーター）で始まり、何も保持しないパスはテキスト内では空になり、単独の値は省略されます。$each は item と index を使える状態で配列をマッピングし、$group は $by で最初に現れた順にグループ化し、$number は 1,234.50、$3.50、3,50 €、12% を読み取り（小数点がカンマの場合は "$decimal": "," を追加）、$bool は true、yes、y、1、x を読み取り、$text は $max と併用してテキストを切り詰めます。テンプレートは保存時に検証され、invalid_request が失敗した箇所を示します。

{
  "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 は、カード自身のドキュメントの代わりに、キー別のドキュメントを書き込みます。テンプレートは {screen.field.NAME} トークンを含むカードデータキー（たとえば room-{screen.field.room}）で、マッピング後のオブジェクト（マッピングがない場合は送信された本文）は {fields, document} オブジェクトの documents 配列だけを持ちます。各 fields オブジェクトがテンプレートを埋め、各 document は生成されたキーのもとに書き込まれます。同じテンプレートを data に指定したページ項目は、各スクリーンに自分のフィールドに対応するドキュメントを表示します。すべてのドキュメントは、どれかが書き込まれる前に検証され、重複したキーは拒否されます。ストレージの障害でバッチの一部だけが書き込まれることがあります。その場合は同じ本文と同じ Idempotency-Key で再送してください。送信で省略したキーはデータを保ち、Webhook は有効期限を設定しません。キー別ドキュメントにマッピングの例があります。

投稿は、カード自身のデータとして検査されます。card_data_invalid がパスを示し、何も書き込まれません。カードの現在のものと同じドキュメントには unchanged と答え、何も書き込まないので、スクリーンは起こされません。受け付けた投稿はエージェントリクエストの上限に数えられません。Webhookは1分あたり最大120件の投稿を受け付け、Idempotency-Key ヘッダーは送信側の再試行を24時間重複排除します。

誤ったアドレス、誤ったまたは欠けたシークレット、無効化されたWebhook、欠けたまたは誤った署名、そしてすべての GET には同じ 404 が返るため、リンクのプレビューや当てずっぽうでは何もわかりません。理由は kv webhook deliveries でわかります。

--signing を指定すると、すべての送信に ScreenRig-Signature: t=<unix seconds>,v1=<hex> も必要です。v1 は、署名シークレット whsec_… による t、ドット、生のボディの HMAC-SHA256 で、t はサーバーの時計から5分以内でなければなりません。これは screenRIG 自身のWebhook署名と同じ形式です。

ベンダーの署名とハンドシェイク

ベンダーは独自の方法で送信に署名し、中にはシークレットをそもそも送れないものもあります。カード Webhook は、シークレットの代わりにベンダーの署名を検証し、ベンダーのセットアップのハンドシェイクに応答できるため、GitHub、Stripe、Shopify、Slack、Linear、Vercel、Asana、Microsoft Graph、monday.com、Trello、Azure Event Grid は、中継なしで直接送信できます。HMAC で署名するその他の送信元も使えます。kv webhook create で --verify と --handshake を設定し、kv webhook update で変更します。

• --verify VENDOR はベンダー独自の署名を受け付けます。--verify-secret-file FILE（stdin の場合は -、引数では渡せません）にベンダーが示すシークレットを入れます。generic_hmac では、--verify-header NAME が署名を運ぶヘッダーを指定し、--verify-encoding は hex（既定）または base64、--verify-timestamp-header NAME は Unix 時刻を運ぶヘッダーを指定し、--verify-tolerance SECONDS はサーバーの時計からどこまでずれてよいかを表します（既定は 300）。ベンダーの有効な署名を持つ送信は、Webhook 自身の srkw_ シークレットなしで受け付けられ、そのシークレットも並行して使えます。ベンダーのシークレットは封印して保存され、set とその末尾 4 文字の hint だけが表示されます。kv webhook update では、--verify-secret-file なしの --verify はベンダーが同じである限り保存済みのシークレットを保ち、--clear-verify は検証とそのシークレットを削除します。--verify と --signing は同時に使えません。
• --handshake VENDOR は microsoft_graph、monday、trello、azure_event_grid のいずれかで、--clear-handshake で削除されます。Slack と Asana は、--verify を通じて自分たちのハンドシェイクに応答します。

すべての HMAC のキーは、ベンダーが表示するとおりのシークレットのテキストです (Stripe のものには whsec_ が含まれます)。署名は、受信したままの本文に対して、一定時間で、送信が書き込み予算を消費する前に検証され、タイムスタンプより先に判定されます。そのため timestamp_stale は常にシークレットが正しかったことを意味します。本文は JSON、フォーム、multipart/form-data のいずれかで、テキストフィールドは body.FIELD になり、ファイルは数えるだけで読み取りません。

ハンドシェイクに応答するのは、そのベンダー用に設定された Webhook だけで、認証情報が求められる前に、そのハンドシェイクであるリクエストに対してのみ行い、無効な Webhook は応答しません。何も書き込まず、課金されず、レート予算も消費しません。Microsoft Graph、monday.com、Trello、Azure Event Grid は screenRIG が検証するヘッダーを送らないため、その配信は Webhook のシークレットがある場合にのみ受け付けられます。Azure Event Grid は、シークレットとして指定した静的な配信ヘッダー Authorization: Bearer srkw_… でそれを渡し、イベントは配列で届くため、マッピングは 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 -

独自の HMAC で署名する送信元は、ヘッダー、エンコード、そしてタイムスタンプに署名する場合はタイムスタンプのヘッダーを指定します:

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"

失敗はすべて、他の拒否と同じ 404 になります。kv webhook deliveries で理由を確認でき、ハンドシェイクは結果 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