カードデータ API

この環境の公開カタログから組み込みカードを検出し、ベンダーのフロアと統合します。更新とスキーマ検証はバックグラウンドで行われ、このルートはエッジバケットを呼び出しません。各エントリには現在のコピー、階層、その階層が許可するレイアウト、提供されるすべてのメジャーが一覧表示されます。

現行メジャーバージョンの、配置の params とカードデータドキュメント向けの自己完結型 JSON スキーマ、フィードスキーマ、ティア、使用できるレイアウト、配置の例です。dynamic と記されたパラメーターは、配置が data キーを指定している場合、データドキュメントから取得されます。

文字列のパラメーターには {screen.name}、{screen.timezone}、{screen.field.NAME} を含めることができ、location パラメーターには文字列 {screen.location} を指定できます。バックエンドがスクリーンごとにこれらを展開します。公開する前に、例として入っているコンテンツの値を置き換えてください。不明な ID には card_not_found（404）が返されます。

グローバルカードUID、または非推奨のカタログタイプセグメント。後者は/api/card-types.を指す非推奨および警告ヘッダーを追加します。

If-Matchはカードメタデータリビジョン（データリビジョンではない）をオプションで比較します。省略すると現在のリビジョンを更新。Idempotency-Keyはメソッド、UID、パラメータ、If-Matchに24時間結びつきます。再試行は記録された結果を再生し、削除後の204も含みます。入力変更はidempotency_mismatch。古いIf-Matchはrevision_conflict（412）を返します。

キーはカードUIDにスコープされます。

If-Matchはカードメタデータリビジョン（データリビジョンではない）をオプションで比較します。省略すると現在のリビジョンを更新。Idempotency-Keyはメソッド、UID、パラメータ、If-Matchに24時間結びつきます。再試行は記録された結果を再生し、削除後の204も含みます。入力変更はidempotency_mismatch。古いIf-Matchはrevision_conflict（412）を返します。

キーはカードUIDにスコープされます。

カードの受信Webhookを古い順に一覧表示します（最大20件）。シークレットはここでは返されません。

このカードのデータドキュメントを書き込む Webhook を作成します。外部のシステムが、その url に JSON またはフォームの本文を送信します (POST /api/cards/{id}/kv-webhooks/{webhook_id}/write)。

マッピングがなければ、送信されたオブジェクトがそのままドキュメントになります。マッピングテンプレートは本文からドキュメントを組み立て、保存時に検証されます。signing true は ScreenRig-Signature ヘッダーも必須にします。verify は、ベンダー自身の署名 (GitHub、Stripe、Shopify、Slack、Linear、Vercel、Asana、または任意の HMAC 送信元) を、シークレットの代わりに送信の認証に使います。シークレットも並行して使えます。signing とは併用できず、そのシークレットは封印して保存され、返されることはなく、ヒントだけが返されます。handshake は、url が応答するベンダーのハンドシェイクを指定します (Microsoft Graph、monday.com、Trello、Azure Event Grid。verify slack と asana は自分のハンドシェイクに応答します)。

シークレットと署名シークレットが現れるのは、このレスポンス（および rotate-secret と署名を有効にする更新）だけです。すぐに送信側のシステムに保存してください。カードには最大20個のWebhookを作成できます（kv_webhook_limit_reached）。kv_webhook.created を追加します。

同じ Idempotency-Key での完全に同じ再試行には、シークレットを含む同じレスポンスが24時間返されます。

description、mapping (null で削除)、enabled、signing、verify (null で削除。シークレットなしの場合、ベンダーが同じなら保存済みのものを保持します)、handshake (null で削除) を変更します。signing をオンにすると、新しい signing_secret が 1 回だけ返され、false でオフになります。無効な Webhook は、すべての送信に、間違ったシークレットと同じ応答をします。kv_webhook.updated を追記します。

Webhookを削除します。URLは即座に無効になりますが、カードはドキュメントを保持します。kv_webhook.deleted を追加します。

Webhookのシークレットを置き換え、新しいものを一度だけ返します。signing true の場合は、代わりに署名シークレットを置き換えます。古いものは即座に使えなくなります。kv_webhook.secret_rotated を追加します。

Webhook の配信ログです。新しい順に最大 100 件、7 日間保持されます。

この Webhook を指定した各送信が 1 行になり、時刻、結果 (written、unchanged、refused、invalid、handshake)、理由 (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)、失敗したカードデータのパスなどの短い詳細、応答のステータス、本文のサイズ、マルチパートの送信に含まれていたファイルパートの数 (無視されます) が記録されます。

本文、ヘッダー、認証情報は保存されません。すべての拒否が共有する 404 を送信が受け取った理由を、プロジェクトはここで確認できます。

外部システムがカードのデータドキュメントを送信するURLです。Authorization ヘッダーにWebhook自身のシークレットを指定して認証します（Bearer <secret>、またはWebhook IDをユーザー名にしたHTTP Basic）。

Webhook を verify 付きで作成した場合、そのベンダー自身のヘッダー (WebhookVerifyWrite を参照) に有効な署名があれば、シークレットの代わりに送信が認証されます。シークレットも並行して使えます。

Webhookが署名する場合は、ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret> も必要で、t はサーバーの時計から5分以内でなければなりません。

不明なカードや Webhook、間違っているか欠けているシークレットや署名、古いタイムスタンプ、無効な Webhook、そしてすべての GET は、同じ 404 not_found で応答します。プロジェクトは理由を配信ログで確認できます。

ベンダーのハンドシェイク用に設定された Webhook は、認証情報が求められる前に、そのハンドシェイクであるリクエストに最初に応答します。Slack の url_verification チャレンジ (署名付き。チャレンジで応答)、Microsoft Graph の validationToken (text/plain でそのまま返す)、Asana の X-Hook-Secret (そのまま返し、イベントの署名シークレットとして封印して保持)、monday.com の challenge、Azure Event Grid の SubscriptionValidationEvent (その validationResponse で応答)、Trello の HEAD チェック (この url の head 操作) です。

ハンドシェイクはカードデータを書き込まず、課金されず、レート予算も消費せず、結果 handshake で配信ログに記録されます。

本文は最大 1 MiB で、JSON、application/x-www-form-urlencoded (繰り返された名前は配列)、または multipart/form-data (各テキストフィールドは body.<field>、繰り返された名前は配列で、ファイルパートは無視され、配信ログに数えられます) です。マッピングがなければオブジェクトがそのままドキュメントになり、あれば、テンプレートが body と query からドキュメントを組み立てます。

ドキュメントはカードのデータとして検証され (card_data_invalid がパスを示します)、現在のドキュメントと同じものは書き込まれません (ステータス unchanged)。受け付けられた送信は課金される 1 回の API リクエストで、カードデータのイベントを追記します。Idempotency-Key (8 〜 200 文字) は、送信元の再試行を 24 時間重複排除します。

Webhook ごとに 1 分あたり最大 120 件の送信です。それぞれ、組織とカードの書き込みレート (PUT /api/card-data/{key}) にも数えられます。

Trello が新しい Webhook に対して行うチェックです。ハンドシェイクが trello の Webhook には本文なしの 200 で応答し、それ以外のあらゆる Webhook、アドレス、リクエストには 1 つの 404 not_found で応答するため、リンクプレビューは何も知ることができません。何も書き込まず、課金されず、レート予算も消費しません。応答したチェックは、結果 handshake で配信ログに記録されます。

すべての GET は 404 で応答し、何も読み取りません。

プロジェクトのカードデータドキュメントを最大200件、キーの昇順で一覧表示します。next_cursorは最後に返されたキーで、次のページのafterとして渡します。これ以上ない場合はnullです。カードデータドキュメントはカード配置（メニューセクション、ティッカー項目、KPIタイル）の動的プロパティを保持し、配置のデータキー名が1つあります。

ドキュメントとそのリビジョンを返します。ETagはリビジョンで、次の書き込みのIf-Match用です。

カードデータドキュメントを作成または置換します。プロジェクトのプレイリストのカード配置がキーにバインドされている場合、ドキュメントは各バインドされたカードの動的プロパティのみを保持し、それらに対して検証されなければなりません。そうでなければcard_data_invalidでカードとプロパティパスを指定して書き込みが拒否され、変更はありません。配置がバインドされていないキーは任意のJSONオブジェクトを受け入れます。

media: で始まるすべての文字列はメディア参照（media:<id>）であり、カードが描画する写真用です。任意のキーで、このプロジェクトの準備済み承認済み画像を指し、ドキュメントごとに最大256個の異なるメディアが許されます。そうでない場合、書き込みは拒否され、card_media_invalid がプロパティパスと media_id を示します。

キーを読み取るコンテンツを持つスクリーンは、そのメディアをGET /media/{media_id}.から取得できます。キーを読み取るプレースメントを表示するスクリーンはscreen.card_data_changedを受け取り、その場で再取得します。プロジェクトログはkv.updatedをcard_data_entryリソースと共に記録し、これは決してプレーヤーに届きません。

制限、クォータ、計測、リビジョン、冪等性はアプリケーションのK/Vストアによります。

エージェントと Webhook の書き込みにはレート制限もあり、組織ごとにプランで異なり（Standard と Plus は毎分60回、Education と Premium は600回、Enterprise は3,000回）、すべてのプランでキーごとに毎分60回までです。上限を超えた書き込みは rate_limited と Retry-After で拒否され、計測されません。

カードデータドキュメントを削除します。キーに紐づくカードは、ドキュメントが再度書き込まれるまでガラス上で非表示になります。

共有されたサードパーティフィードドキュメントを読み取ります：同じパラメータの組み込みカード配置が読むドキュメント（docs/feeds.md）と同じです。

クエリパラメーターは、ScreenRig-Feed-Key ヘッダーで示されるカードのフィードキーに正規化されます。weather、airquality、alerts は lat と lon (0.25 度のセルに丸めます)。earthquakes は lat、lon、radius_km (10 〜 20000、デフォルトは 500)、min_magnitude (0 〜 9、デフォルトは 2.5)、hours (1 〜 168、デフォルトは 24)。cyclones は basins (カンマ区切りの at、ep、cp、wp。デフォルトはすべて) と、任意で lat、lon、radius_km (その場所の近くの嵐)。tides は station (9414290 のような NOAA の潮汐予測観測所 ID) または lat と lon (100 km 以内で最も近い観測所。なければ invalid_request)。launches はパラメーターなし (世界の次の打ち上げ)。rates は base (ECB の基準通貨、デフォルトは EUR)。crypto は symbols (CoinGecko の ID またはティッカー、カンマ区切り、最大 20) と currency (デフォルトは usd)。headlines は url (http または https の RSS または Atom の URL)。cap (screenrig.cap/v1) はスクリーンに合う CAP アラートで、url (繰り返し指定可。CAP アラートまたは ATOM/RSS インデックスの URL を最大 5 件)、public (lat と lon をカバーする公開フィードも読み取ります。url がない場合のデフォルト)、lat と lon、geocode (繰り返し指定可の NAME:VALUE エリアコード)、min_severity、max_severity、min_urgency、min_certainty、event、exclude_event、sender、status (デフォルトは Actual)、scope (デフォルトは Public)、language (繰り返し指定可。優先順)、area_unknown (hide または show)。drugalerts (screenrig.drugalerts/v1) はある国の最近のリコール報告で、country (us、ca、gb。必須) と category (デフォルトの drug、または food)。respiratory (screenrig.respiratory/v1) はある場所の週ごとのインフルエンザ、COVID-19、RSV の活動で、country (us または gb。必須) と region (米国の州、準州、DC を名前または郵便番号で、あるいはイングランドまたは UKHSA の地域。空なら国全体)。almanac (screenrig.almanac/v1) は today カード向けの、ある日付の記念日、On This Day の出来事、太陽と月で、country (ISO 3166-1 alpha-2 コード。その国の祝日用)、language (On This Day の版: ar、bs、cs、de、en、es、fr、it、pt、ru、sv、tr、uk、zh。デフォルトは en)、任意で lat と lon (太陽用。0.1 度のセルに丸めます)、date (特定の 1 日。デフォルトは今日の前後の日)。outdoorsafety (screenrig.outdoorsafety/v1) は outdoor-safety カード向けの暑さで、lat と lon (天気の 0.25 度のセル) から求めた湿球黒球温度の推定値です。雷は報告しません。departures (screenrig.departures/v1) は 1 つのオープンデータプロバイダーの 1 〜 4 か所の停留所の次の発車で、provider (tfl、entur、digitransit) と stops (カンマ区切りの ID、最大 4 件: TfL の StopPoint ID、Entur の NSR の停留所または乗り場の ID、Digitransit の gtfsIds) を受け付け、発車順の 1 つのボードにまとめて 1 分ごとに取得します。bikeshare (screenrig.bikeshare/v1) は lat と lon (0.001 度のセル、約 100 m に丸めます) に最も近い GBFS のバイクシェアの拠点を、それぞれのセルからの距離とともに返し、system (一覧にあるシステム ID) か、指定しなければその場所をカバーする最も近い一覧のシステムから取得します (どれもカバーしない場合は system で invalid_request)。

リクエストはプロバイダーを呼び出しません。200 はドキュメント（スキーマ、fetchedAt、attribution とファミリーのフィールド、カード契約定義に準拠）で、その ETag はバイトの sha256 で If-None-Match は 304 を返します。Cache-Control max-age は次の予定取得まで有効です。202 はまだドキュメントなし：登録された読み取り要求で、フィードワーカーが約1分以内にキーを取得します（Retry-After）。

API読み取りは24時間有効なキーを保持します。組織は、すべてのプロジェクトを合わせて1日に最大50の新しいキーを登録します（rate_limitedを超えると）。このデプロイメントにソースがないファミリーはnot_foundを返します。