卡片数据 API

发现此环境已发布目录中的内置卡片，与供应的底层合并。刷新和架构验证在后台进行；此路由从不调用边缘存储桶。每条目列出其当前副本、所属层级及该层级允许的布局，以及所有提供的主要内容。

当前主版本中用于放置项 params 和卡片数据文档的自包含 JSON Schema，以及 feed schema、层级、允许的布局和一个示例放置项。标记为 dynamic 的 params 在放置项绑定 data 键时取自数据文档。

字符串类型的参数可以包含 {screen.name}、{screen.timezone} 和 {screen.field.NAME}，location 参数也可以是字符串 {screen.location}；后端会为每个屏幕展开它们。发布前请替换示例内容值。未知的 id 会返回 card_not_found（404）。

全局卡片 UID，或已弃用的目录类型段。后者会添加指向 /api/card-types. 的 Deprecation 和 Warning 头。

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：外部系统把 JSON 或表单请求体发送到它的 url（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 的完全相同的重试，会在二十四小时内返回相同的响应，包括密钥。

更改 description、mapping（null 会移除它）、enabled、signing、verify（null 会移除它；不带密钥时，若服务商相同则保留已存储的密钥）和 handshake（null 会移除它）。开启 signing 会返回一次新的 signing_secret；false 将其关闭。已停用的 webhook 对每个请求的响应都像密钥错误一样。追加 kv_webhook.updated。

删除 webhook。其 URL 立即停止工作，卡片保留其文档。追加 kv_webhook.deleted。

替换 webhook 的密钥并仅返回一次新密钥；若 signing 为 true，则改为替换签名密钥。旧密钥立即失效。追加 kv_webhook.secret_rotated。

webhook 的投递日志，最新的在前，最多 100 条，保留七天。

每个指向此 webhook 的请求是一行记录，包含时间、结果（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）、简短的详情（如失败的卡片数据路径）、响应的状态、请求体大小，以及 multipart 请求所带文件部分的数量（被忽略）。

不存储任何请求体、请求头或凭据。项目在这里查看一个请求为什么得到所有拒绝共用的那个 404。

外部系统向其发送卡片数据文档的 URL。使用 webhook 自身的密钥在 Authorization 标头中认证：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 必须在服务器时钟的五分钟以内。

未知的卡片或 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）。被接受的请求计为一次计费的 API 请求，并追加卡片数据事件。Idempotency-Key（8 到 200 个字符）会在二十四小时内对发送方的重试去重。

每个 webhook 每分钟最多 120 个请求；每个请求也计入组织和卡片的写入速率（PUT /api/card-data/{key}）。

Trello 对新 webhook 所做的检查。对握手为 trello 的 webhook，它以 200 响应且没有请求体；对其他所有 webhook、地址和请求，则只有同一个 404 not_found，因此链接预览器什么也了解不到。它不写入任何内容，从不计费，也不消耗速率额度；已响应的检查会以结果 handshake 出现在投递日志中。

每个 GET 都响应 404，且不读取任何内容。

列出项目的卡片数据文档，最多 200 个，按键升序排列。next_cursor 是最后返回的键；作为 after 传回以获取下一页，无更多时为 null。卡片数据文档保存卡片位置的动态属性（菜单部分、跑马灯项目、KPI 瓷砖）；位置的数据键名即为其中之一。

返回文档及其修订版本。ETag 是修订版本，用于下一次写入的 If-Match。

创建或替换卡片数据文档。当项目播放列表中的卡片位置绑定该键时，文档必须仅包含每个绑定卡片的动态属性并通过验证；否则写入被拒，返回 card_data_invalid 并指明卡片及属性路径，且无更改。无绑定位置的键接受任意 JSON 对象。

以 media: 开头的每个字符串都是媒体引用，格式为 media:<id>，供卡片绘制（照片）；在任何键上必须命名该项目中准备好的、已批准的图像，每个文档最多 256 个不同媒体，否则写入时拒绝，错误名为 card_media_invalid，包含属性路径和 media_id。

读取密钥内容的屏幕随后可从 GET /media/{media_id}. 获取这些媒体。显示读取密钥的投放位的屏幕接收 screen.card_data_changed 并在原位重新获取；项目日志记录带有 card_data_entry 资源的 kv.updated，该资源永远不会到达播放器。

限制、配额、计量、修订和幂等性由应用的键值存储管理。

智能体和 webhook 的写入也有频率限制，按套餐对每个组织限制（Standard 和 Plus 每分钟 60 次，Education 和 Premium 600 次，Enterprise 3,000 次），所有套餐中每个键均限制为每分钟 60 次；超出限制的写入会被 rate_limited 和 Retry-After 拒绝，且不计量。

删除卡片数据文档。绑定到该键的卡片在屏幕上隐藏，直到再次写入文档。

读取共享的第三方订阅文档：内置卡片位置使用相同参数读取的文档（docs/feeds.md）。

查询参数会规范化为卡片的 feed 键，由 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（NOAA 潮汐预测站 ID，如 9414290）或 lat 和 lon（100 公里内最近的站点，否则为 invalid_request）；launches 无参数（全球后续发射）；rates 取 base（欧洲央行参考货币，默认 EUR）；crypto 取 symbols（CoinGecko 的 ID 或代码，逗号分隔，最多 20 个）和 currency（默认 usd）；headlines 取 url（http 或 https 的 RSS 或 Atom URL）；cap（screenrig.cap/v1）与某个屏幕匹配的 CAP 警报：url（可重复，最多 5 个 CAP 警报或 ATOM/RSS 索引 URL）、public（同时读取覆盖 lat 和 lon 的公开 feed；没有 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（固定的某一天；默认今天前后几天）；outdoorsafety（screenrig.outdoorsafety/v1）outdoor-safety 卡片所用的高温信息，即由 lat 和 lon（天气的 0.25 度单元格）得出的湿球黑球温度估计值；它不报告雷电；departures（screenrig.departures/v1）某个开放数据提供商一到四个站点的下几班发车：provider（tfl、entur 或 digitransit）和 stops（逗号分隔的 ID，最多 4 个：TfL 的 StopPoint ID、Entur 的 NSR 站点或站台 ID、Digitransit 的 gtfsIds），按发车顺序合并为一个看板，每分钟轮询一次；bikeshare（screenrig.bikeshare/v1）距 lat 和 lon（舍入到 0.001 度的单元格，约 100 米）最近的 GBFS 共享单车站点，每个都带有到该单元格的距离，来自 system（一个已列出的系统 ID），不提供时来自覆盖该地点的最近的已列出系统（没有系统覆盖时，system 为 invalid_request）。

请求从不调用提供者。200 表示文档（架构、fetchedAt、归属及其家族字段，按卡片合同定义）；其 ETag 是字节的 sha256，If-None-Match 返回 304；Cache-Control max-age 直到下一次计划获取。202 表示尚无文档：读取注册需求，feed 工作线程约一分钟内获取密钥（Retry-After）。

API 读取会缓存密钥 24 小时。组织跨其所有项目每天最多注册 50 个新密钥（超过返回 rate_limited）。无源的家族在此部署返回 not_found。