Kartendaten-API

Entdecken Sie integrierte Karten aus dem veröffentlichten Katalog dieser Umgebung, zusammengeführt mit dem bereitgestellten Floor. Aktualisierungen und Schemaüberprüfungen erfolgen im Hintergrund; diese Route ruft niemals den Edge-Bucket auf. Jeder Eintrag listet seine aktuelle Kopie, seine Stufe und die Layouts, die diese Stufe erlaubt, sowie jede ausgelieferte Hauptversion auf.

Die in sich geschlossenen JSON-Schemas der aktuellen Hauptversion für Platzierungsparameter und Karten-Datendokumente, das Feed-Schema, die Stufe, die zulässigen Layouts und eine Beispielplatzierung. Als dynamic markierte Parameter stammen aus dem Datendokument, wenn eine Platzierung einen data-Schlüssel bindet.

Ein String-Parameter kann {screen.name}, {screen.timezone} und {screen.field.NAME} enthalten, und ein Parameter location darf der String {screen.location} sein; das Backend setzt sie für jeden Bildschirm ein. Ersetzen Sie die Beispielwerte für Inhalte vor dem Veröffentlichen. Unbekannte IDs werden mit card_not_found (404) beantwortet.

Eine globale Karten-UID oder ein veralteter Katalogtyp-Segment. Letzteres fügt Deprecation- und Warning-Header hinzu, die auf /api/card-types. verweisen.

If-Match vergleicht optional die Metadaten-Revision der Karte (nicht deren Datenrevision); Weglassen aktualisiert die aktuelle Revision. Idempotency-Key bindet Methode, UID, Parameter und If-Match für 24 Stunden. Ein Wiederholen spielt das aufgezeichnete Ergebnis ab, einschließlich 204 nach Löschung; geänderte Eingabe gibt idempotency_mismatch zurück. Veraltetes If-Match gibt revision_conflict (412) zurück.

Schlüssel sind auf die Karten-UID beschränkt.

If-Match vergleicht optional die Metadaten-Revision der Karte (nicht deren Datenrevision); Weglassen aktualisiert die aktuelle Revision. Idempotency-Key bindet Methode, UID, Parameter und If-Match für 24 Stunden. Ein Wiederholen spielt das aufgezeichnete Ergebnis ab, einschließlich 204 nach Löschung; geänderte Eingabe gibt idempotency_mismatch zurück. Veraltetes If-Match gibt revision_conflict (412) zurück.

Schlüssel sind auf die Karten-UID beschränkt.

Listet die eingehenden Webhooks der Karte auf, älteste zuerst (höchstens 20). Geheimnisse werden hier nie zurückgegeben.

Legt einen Webhook an, der das Datendokument dieser Karte schreibt: Ein externes System sendet einen JSON- oder Formular-Body an seine url (POST /api/cards/{id}/kv-webhooks/{webhook_id}/write).

Ohne Zuordnung ist das gesendete Objekt das Dokument; eine Zuordnungsvorlage baut es aus dem Body auf und wird beim Speichern geprüft. signing true verlangt außerdem einen ScreenRig-Signature-Header. verify lässt die eigene Signatur eines Anbieters (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana oder ein beliebiger HMAC-Sender) eine Zustellung anstelle des Secrets authentifizieren, das daneben weiter funktioniert; es lässt sich nicht mit signing kombinieren, und sein Secret wird versiegelt und nie zurückgegeben, nur ein Hinweis darauf. handshake nennt einen Anbieter-Handshake, den die url beantwortet (Microsoft Graph, monday.com, Trello oder Azure Event Grid; verify slack und asana beantworten ihren eigenen).

Die Antwort ist die einzige Stelle, an der das Geheimnis und das Signaturgeheimnis erscheinen (zusammen mit rotate-secret und dem Update, das die Signierung einschaltet): Speichern Sie sie sofort im sendenden System. Eine Karte hat höchstens 20 Webhooks (kv_webhook_limit_reached). Fügt kv_webhook.created hinzu.

Ein exakter Wiederholungsaufruf mit demselben Idempotency-Key liefert vierundzwanzig Stunden lang dieselbe Antwort, einschließlich der Geheimnisse.

Ändert description, mapping (null entfernt es), enabled, signing, verify (null entfernt es; ohne Secret behält es das gespeicherte, wenn der Anbieter derselbe ist) und handshake (null entfernt es). Das Einschalten von signing antwortet einmal mit dem neuen signing_secret; false schaltet es aus. Ein deaktivierter Webhook beantwortet jede Zustellung wie ein falsches Secret. Hängt kv_webhook.updated an.

Löscht den Webhook. Seine URL funktioniert sofort nicht mehr; die Karte behält ihr Dokument. Fügt kv_webhook.deleted hinzu.

Ersetzt das Geheimnis des Webhooks und gibt das neue einmalig zurück; mit signing true ersetzt es stattdessen das Signaturgeheimnis. Das alte funktioniert sofort nicht mehr. Fügt kv_webhook.secret_rotated hinzu.

Das Zustellprotokoll des Webhooks, neueste zuerst, höchstens 100, sieben Tage aufbewahrt.

Jede Zustellung, die diesen Webhook nannte, ist eine Zeile mit ihrer Zeit, dem Ergebnis (written, unchanged, refused, invalid oder handshake), dem Grund (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), einem kurzen Detail wie dem fehlgeschlagenen Kartendatenpfad, dem Status der Antwort, der Body-Größe und der Anzahl der Dateiteile, die eine Multipart-Zustellung trug (ignoriert).

Weder Body noch Header noch Zugangsdaten werden gespeichert. Hier sieht ein Projekt, warum eine Zustellung das 404 erhielt, das alle Ablehnungen teilen.

Die URL, an die ein externes System das Datendokument einer Karte sendet. Sie authentifiziert sich mit dem eigenen Geheimnis des Webhooks im Authorization-Header: Bearer <secret>, oder HTTP Basic mit der Webhook-ID als Benutzername.

Wurde der Webhook mit verify angelegt, authentifiziert eine gültige Signatur im eigenen Header dieses Anbieters (siehe WebhookVerifyWrite) die Zustellung anstelle des Secrets, das daneben weiter funktioniert.

Signiert der Webhook, ist außerdem ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret> erforderlich, und t darf höchstens fünf Minuten von der Serveruhr abweichen.

Eine unbekannte Karte oder ein unbekannter Webhook, ein falsches oder fehlendes Secret oder eine falsche oder fehlende Signatur, ein veralteter Zeitstempel, ein deaktivierter Webhook und jedes GET erhalten dasselbe 404 not_found; das Projekt sieht den Grund im Zustellprotokoll.

Ein Webhook, der für einen Anbieter-Handshake eingerichtet ist, beantwortet ihn zuerst, bevor irgendwelche Zugangsdaten verlangt werden, auf eine Anfrage, die dieser Handshake ist: die url_verification-Challenge von Slack (signiert, mit der Challenge beantwortet), das validationToken von Microsoft Graph (als text/plain zurückgegeben), das X-Hook-Secret von Asana (zurückgegeben und versiegelt als Signing-Secret seiner Ereignisse behalten), die challenge von monday.com, das SubscriptionValidationEvent von Azure Event Grid (mit seinem validationResponse beantwortet) und die HEAD-Prüfung von Trello (die head-Operation dieser url).

Ein Handshake schreibt keine Kartendaten, wird nie abgerechnet und verbraucht kein Ratenbudget und wird im Zustellprotokoll mit dem Ergebnis handshake festgehalten.

Der Body, höchstens 1 MiB, ist JSON, application/x-www-form-urlencoded (ein wiederholter Name ist ein Array) oder multipart/form-data (jedes Textfeld ist body.<field>, ein wiederholter Name ist ein Array, und Dateiteile werden ignoriert und im Zustellprotokoll gezählt). Ohne Zuordnung ist das Objekt das Dokument; mit einer baut die Vorlage es aus body und query auf.

Das Dokument wird als Daten der Karte geprüft (card_data_invalid nennt den Pfad), und ein Dokument, das dem aktuellen gleicht, wird nicht geschrieben (Status unchanged). Eine akzeptierte Zustellung ist eine abgerechnete API-Anfrage und hängt die Kartendaten-Ereignisse an. Idempotency-Key (8 bis 200 Zeichen) dedupliziert die Wiederholungsversuche eines Senders vierundzwanzig Stunden lang.

Höchstens 120 Zustellungen pro Minute und Webhook; jede zählt außerdem zu den Schreibraten der Organisation und der Karte (PUT /api/card-data/{key}).

Die Prüfung, die Trello bei einem neuen Webhook vornimmt. Sie antwortet mit 200 ohne Body für einen Webhook, dessen Handshake trello ist, und mit dem einen 404 not_found für jeden anderen Webhook, jede andere Adresse und Anfrage, sodass eine Link-Vorschau nichts erfährt. Sie schreibt nichts, wird nie abgerechnet und verbraucht kein Ratenbudget; die beantwortete Prüfung steht im Zustellprotokoll mit dem Ergebnis handshake.

Jedes GET antwortet mit dem 404 und liest nichts.

Listet die Kartendatendokumente des Projekts auf, maximal 200 in aufsteigender Schlüsselreihenfolge. next_cursor ist der zuletzt zurückgegebene Schlüssel; geben Sie ihn als after für die nächste Seite zurück, null, wenn keine weiteren vorhanden sind. Kartendatendokumente enthalten die dynamischen Eigenschaften von Kartenplatzierungen (Menüabschnitte, Ticker-Elemente, KPI-Kacheln); der Daten-Schlüssel der Platzierung benennt einen davon.

Gibt das Dokument und seine Revision zurück. ETag ist die Revision, für If-Match beim nächsten Schreiben.

Erstellt oder ersetzt ein Kartendaten-Dokument. Wenn Kartenplatzierungen in den Playlists des Projekts den Schlüssel binden, muss das Dokument nur die dynamischen Eigenschaften jeder gebundenen Karte enthalten und gegen diese validieren; andernfalls wird das Schreiben mit card_data_invalid abgelehnt, wobei die Karte und der Eigenschaftspfad genannt werden, und es ändert sich nichts. Ein Schlüssel ohne gebundene Platzierung akzeptiert jedes JSON-Objekt.

Jede Zeichenkette, die mit media: beginnt, ist eine Medienreferenz, media:<id>, die eine Karte zeichnen soll (ein Foto); bei jedem Schlüssel muss sie ein bereites, genehmigtes Bild in diesem Projekt benennen, höchstens 256 verschiedene Medien pro Dokument, sonst wird das Schreiben mit card_media_invalid abgelehnt, das den Eigenschaftspfad und media_id angibt.

Bildschirme, deren Inhalt den Schlüssel liest, können diese Medien dann von GET /media/{media_id}. abrufen. Bildschirme, die eine Platzierung zeigen, die den Schlüssel liest, erhalten screen.card_data_changed und rufen ihn an Ort und Stelle erneut ab; das Projektprotokoll zeichnet kv.updated mit einer card_data_entry-Ressource auf, die niemals einen Player erreicht.

Limits, Kontingente, Messung, Revisionen und Idempotenz werden vom Anwendungs-K/V-Speicher verwaltet.

Agenten- und Webhook-Schreibvorgänge sind zudem ratenbegrenzt, pro Organisation je nach Plan (Standard und Plus 60 pro Minute, Education und Premium 600, Enterprise 3.000) und auf jedem Plan mit 60 pro Minute je Schlüssel; ein Schreibvorgang über dem Limit wird mit rate_limited und Retry-After abgelehnt und nicht gemessen.

Löscht ein Kartendaten-Dokument. Eine an den Schlüssel gebundene Karte wird auf dem Bildschirm verborgen, bis erneut ein Dokument geschrieben wird.

Liest ein geteiltes Drittanbieter-Feed-Dokument: dasselbe Dokument, das eine eingebaute Kartenplatzierung mit denselben Parametern liest (docs/feeds.md).

Abfrageparameter werden zum Feed-Schlüssel der Karte normalisiert, benannt durch den Header ScreenRig-Feed-Key: weather, airquality und alerts nehmen lat und lon (auf eine 0,25-Grad-Zelle gerundet); earthquakes lat, lon, radius_km (10 bis 20000, standardmäßig 500), min_magnitude (0 bis 9, standardmäßig 2,5) und hours (1 bis 168, standardmäßig 24); cyclones basins (kommagetrennt at, ep, cp, wp; standardmäßig alle) und optional lat, lon und radius_km (die Stürme in der Nähe dieses Ortes); tides station (eine NOAA-Gezeitenvorhersage-Stations-ID wie 9414290) oder lat und lon (die nächste Station im Umkreis von 100 km, sonst invalid_request); launches keine Parameter (die nächsten Starts weltweit); rates base (eine EZB-Referenzwährung, standardmäßig EUR); crypto symbols (CoinGecko-IDs oder Ticker, kommagetrennt, höchstens 20) und currency (standardmäßig usd); headlines url (eine http- oder https-RSS- oder Atom-URL); cap (screenrig.cap/v1) die zu einem Bildschirm passenden CAP-Warnungen: url (wiederholbar, bis zu 5 CAP-Warnungs- oder ATOM/RSS-Index-URLs), public (liest auch die öffentlichen Feeds, die lat und lon abdecken; Standard, wenn keine url), lat und lon, geocode (wiederholbare NAME:VALUE-Gebietscodes), min_severity, max_severity, min_urgency, min_certainty, event, exclude_event, sender, status (standardmäßig Actual), scope (standardmäßig Public), language (wiederholbar, in Reihenfolge der Präferenz) und area_unknown (hide oder show); drugalerts (screenrig.drugalerts/v1) die jüngsten Rückrufberichte eines Landes: country (us, ca oder gb, erforderlich) und category (drug, die Vorgabe, oder food); respiratory (screenrig.respiratory/v1) die wöchentliche Grippe-, COVID-19- und RSV-Aktivität eines Ortes: country (us oder gb, erforderlich) und region (ein US-Bundesstaat, ein Territorium oder DC nach Name oder Postleitzahl, oder England oder eine UKHSA-Region; das Land, wenn leer); almanac (screenrig.almanac/v1) die Gedenktage, On-This-Day-Ereignisse, Sonne und Mond eines Datums für die today-Karte: country (ein ISO-3166-1-Alpha-2-Code, für seine Feiertage), language (eine On-This-Day-Ausgabe: ar, bs, cs, de, en, es, fr, it, pt, ru, sv, tr, uk oder zh; standardmäßig en), optional lat und lon (auf eine 0,1-Grad-Zelle gerundet, für die Sonne) und date (ein fester Tag; standardmäßig die Tage um heute); outdoorsafety (screenrig.outdoorsafety/v1) die Hitze für die outdoor-safety-Karte, eine Schätzung der Feucht-Kugel-Globe-Temperatur, aus lat und lon (die 0,25-Grad-Zelle des Wetters); sie meldet keine Blitze; departures (screenrig.departures/v1) die nächsten Abfahrten an einer bis vier Haltestellen eines Open-Data-Anbieters: provider (tfl, entur oder digitransit) und stops (kommagetrennte IDs, höchstens 4: TfL-StopPoint-IDs, Entur-NSR-Haltestellen- oder -Quay-IDs, Digitransit-gtfsIds), zu einer Tafel in Abfahrtsreihenfolge zusammengeführt und jede Minute abgefragt; bikeshare (screenrig.bikeshare/v1) die GBFS-Bike-Sharing-Stationen, die lat und lon am nächsten liegen (auf eine 0,001-Grad-Zelle gerundet, etwa 100 m), jede mit ihrem Abstand zu dieser Zelle, aus system (eine gelistete System-ID) oder, ohne sie, dem nächsten gelisteten System, das den Ort abdeckt (invalid_request bei system, wo keines ihn abdeckt).

Die Anfrage ruft den Anbieter nie auf. 200 ist das Dokument (Schema, fetchedAt, Attribution und die Felder der Familie, wie der Kartenvertrag sie definiert); sein ETag ist der sha256 der Bytes und If-None-Match antwortet mit 304; Cache-Control max-age läuft bis zum nächsten geplanten Abruf. 202 bedeutet noch kein Dokument: die registrierte Nachfrage wurde gelesen, und der Feed-Worker holt den Schlüssel innerhalb von etwa einer Minute (Retry-After).

Ein API-Lesevorgang hält einen Schlüssel 24 Stunden lang vor. Eine Organisation registriert höchstens 50 neue Schlüssel pro Tag über alle ihre Projekte (danach rate_limited). Eine Familie ohne Quelle auf dieser Bereitstellung antwortet mit not_found.