Halten Sie Karten aktuell aus einer externen Adresse

So funktioniert eine Datenquelle

• Eine Datenquelle, eine Karte. Eine Datenquelle benennt die Karte, die sie füllt. Eine Karte hat höchstens eine Datenquelle, eine Organisation bis zu 200 über alle ihre Projekte.
• Sie läuft nach Zeitplan. Eine Kalenderquelle synchronisiert alle 5 Minuten, und jede Datenquelle lässt sich zwischen 1 Minute und 24 Stunden einstellen. Eine Datenquelle läuft wenige Sekunden nach dem Anlegen oder Ändern, und source refresh synchronisiert sie sofort.
• Eine fehlgeschlagene Synchronisierung ändert die Karte nie. Die Karte behält ihr letztes gutes Dokument, und der Status der Datenquelle sagt, was schiefging. Fehlschläge werden von selbst wiederholt, mit jeweils längerer Wartezeit.
• Nur Änderungen werden geschrieben. Findet eine Synchronisierung, was die Karte schon enthält, wird nichts geschrieben, und die Bildschirme werden nicht geweckt.
• Synchronisierungen sind kostenlos. Dokumente zählen wie jeder andere Schreibvorgang zum Speicher für Kartendaten.
• Zugangsdaten werden verschlüsselt gespeichert. Eine Adresse, die Zugriff gewährt, wird verschlüsselt abgelegt, nur mit Schema und Host zurückgegeben und erscheint nie in einem Protokoll, einem Fehler oder im Ereignisprotokoll des Projekts.
• Sie behält die letzten guten Daten für einen Zeitraum Ihrer Wahl. Kann eine Quelle nicht aktualisieren, behält ihre Card die letzten guten Daten für den Ablaufzeitraum der Quelle (--stale-after, 1 Minute bis 7 Tage; eine Buchungsquelle eines Veranstaltungsorts behält sie 30 Minuten), danach laufen die Daten auf jedem Bildschirm ab, auch auf Offline-Bildschirmen, und davon abhängige Seiten fallen auf die folgenden Seiten zurück. Ohne Zeitraum bleiben die letzten guten Daten, bis die Quelle wieder aktualisiert. Siehe Wenn eine Quelle nicht aktualisieren kann.

Mit einer Voreinstellung beginnen

Eine Voreinstellung ist eine fertige Quelle für einen Dienst, den man häufig auf einem Bildschirm zeigt. Wählen Sie eine aus, füllen Sie ein paar Felder aus, fügen Sie die Zugangsdaten hinzu, die der Dienst ausstellt, und screenRIG baut die Quelle auf und ordnet die Antwort der Karte zu. Voreinstellungen sind json-Quellen, die jeder Tarif enthält.

Das Dashboard, Ihr Agent und die API listen die Voreinstellungen auf, mit der Hilfezeile und dem Beispiel jedes Felds und den Schritten, um jede Zugangsberechtigung zu erhalten: GET /api/source-presets liefert alle und GET /api/source-presets/NAME eine einzelne (die Gruppe „Datenquellen“ der API-Referenz). Legen Sie eine Quelle aus einer Voreinstellung an mit preset, settings und secrets anstelle von kind und config. Halten Sie die Zugangsdaten in der Anfragedatei, nicht in der Befehlszeile, und ersetzen Sie BOT_TOKEN durch das Token:

{
  "name": "Announcements",
  "preset": "slack-channel",
  "target": {"card_id": "crd_CARD"},
  "settings": {"channel": "C0123456789", "channel_label": "#announcements"},
  "secrets": {"token": "BOT_TOKEN"}
}

curl -sS https://api.screenrig.ai/api/sources/test \
  -H "Authorization: Bearer $SCREENRIG_TOKEN" -H "Content-Type: application/json" -d @source.json

POST /api/sources/test gibt das Dokument aus, das die Karte zeigen würde, ob die Karte es akzeptiert und was dabei aufgefallen ist, und schreibt nichts. POST /api/sources speichert dieselbe Datei, und PATCH /api/sources/ID mit neuen settings baut die Quelle aus der Voreinstellung neu auf.

• Ihr Konto, Ihre Bedingungen. Eine Voreinstellung liest Ihr eigenes Konto mit Zugangsdaten, die Sie erstellen, nach den Bedingungen des Dienstes, und die Karte zeigt, was diese Bedingungen verlangen: Google-Bewertungen erscheinen mit dem Google-Zeichen und dem Namen jedes Rezensenten.
• Zeitplan und Ablauf. Jede Voreinstellung legt ihr eigenes Intervall und ihren eigenen Ablaufzeitraum fest, etwa eine Minute und 15 Minuten für Slack oder 6 Stunden und 24 Stunden für Google-Bewertungen. Eine Quelle darf ein anderes Intervall wählen, nie ein kürzeres als das Minimum ihrer Voreinstellung. Schlägt eine Synchronisierung fehl, behält die Karte ihre letzten Daten, bis der Ablaufzeitraum vergangen ist, und wird dann leer.
• Abrechnung beim Dienst. Jede Aktualisierung der Google-Bewertungen ist eine Place-Details-Anfrage in Ihrem Google-Cloud-Projekt, und jede Aktualisierung der Google-Fahrzeiten ist ein Routenelement pro Ziel: Vier Ziele alle 15 Minuten ergeben rund 11 500 Elemente im Monat.
• Slack braucht eine interne App. Verteilen Sie sie nicht: Slack begrenzt eine App, die außerhalb seines Marketplace verteilt wird, auf eine Anfrage pro Minute. Die App liest nur die Kanäle, zu denen sie hinzugefügt wurde, und die Karte zeigt die eigenen Nachrichten der Personen, keine Beitritte, Bot-Beiträge oder Kanalhinweise.

Datenquelle anlegen

Legen Sie zuerst die Karte an, sehen Sie dann die Vorschau an und speichern Sie anschließend.

screenrig card create --type events --file events.json
screenrig source test --kind ics --card crd_CARD \
  --set 'calendars=[{"key":"lobby"}]' --set time_zone=America/Vancouver \
  --secret calendar_url.lobby=@lobby.url
screenrig source create --kind ics --card crd_CARD --name "Lobby calendar" \
  --set 'calendars=[{"key":"lobby"}]' --set time_zone=America/Vancouver \
  --secret calendar_url.lobby=@lobby.url
screenrig source show src_SOURCE

source test ruft die Adresse ab, bereitet sie für die Karte auf und prüft das Ergebnis gegen die Karte, ohne etwas zu speichern oder zu schreiben. Es zeigt das Dokument, ob die Karte es akzeptiert, und was unterwegs aufgefallen ist. Geben Sie die Adresse in einer Datei (@FILE) oder über die Standardeingabe (-) an, damit sie nicht im Verlauf Ihrer Shell landet.

--settings nimmt die gesamte Konfiguration der Datenquelle als JSON, @FILE oder -. Die CLI-Option --config benennt ihre Anmeldedatei und hat mit Datenquellen nichts zu tun.

Wenn eine Quelle nicht aktualisieren kann

Eine Quelle schreibt jedes Dokument mit einer Frist: ihrem Ablaufzeitraum nach dem Schreiben, erneuert, solange die Quelle weiter aktualisiert. Solange die Quelle läuft, wandert die Frist weiter. Fällt sie aus, zeigt die Card die letzten guten Daten bis zur Frist, danach laufen die Daten auf jedem Bildschirm ab, auch auf Offline-Bildschirmen.

• Legen Sie den Zeitraum fest mit --stale-after 30m bei source create oder source update, von 1 Minute bis 7 Tage und mindestens das Doppelte des Aktualisierungsintervalls. --stale-after none behält die letzten guten Daten bis zur nächsten Aktualisierung. Eine Buchungsquelle eines Veranstaltungsorts (momentus) behält sie 30 Minuten, sofern Sie nichts anderes angeben; die anderen Arten behalten sie bis zur nächsten Aktualisierung.
• Auf eigene Inhalte zurückfallen. Eine Seite, deren Bedingung visibility.data das Dokument nennt (bei einem Raum momentus-room-{screen.field.room}), erscheint, solange die Daten da sind, und weicht der nächsten Seite, wenn sie ablaufen. Lassen Sie danach eine gewöhnliche Seite mit Ihrem eigenen Branding als Ersatz folgen.
• Nachlesen. source show zeigt stale_after, data_expires_at und, sobald die Daten abgelaufen sind, während die Quelle weiter ausfällt, stale: true. Die Seite Datenquellen im Dashboard zeigt dasselbe: Eine fehlerhafte Quelle ist Fehlerhaft, eine mit abgelaufenen Daten Veraltet.
• Benachrichtigt werden. Eine Benachrichtigung auf die Bedingungen source_failed (eine Aktualisierung ist fehlgeschlagen) und source_stale (die Daten sind abgelaufen) sendet E-Mails oder postet in Slack, Teams, PagerDuty oder Telegram, wie bei einem Bildschirm: screenrig notifications create --email owner --conditions source_failed,source_stale --hold 5. Eine Meldung nennt die Quelle und verlinkt ihre Seite, endet, wenn eine Aktualisierung gelingt, und --tag passt nie auf eine Quelle.

Status und Fehler

Jede Datenquelle zeigt ihren Status: wann sie zuletzt lief, zuletzt erfolgreich war und die Karte zuletzt änderte, wann sie wieder läuft, wie viele Synchronisierungen in Folge fehlgeschlagen sind und den letzten Fehler.

ok beurteilt nicht, ob die Daten der Quelle richtig oder aktuell sind oder ob ein Bildschirm die Karte zeigt.

Beim Anlegen oder Ändern einer Datenquelle kann source_target_taken (die Karte hat schon eine Datenquelle), source_target_unsupported (die Art kann diese Karte nicht füllen; die Antwort nennt die möglichen Karten), source_secret_required (ein Geheimnis fehlt oder wurde für eine andere Adresse eingegeben und muss erneut eingegeben werden), source_limit_reached und source_busy (eine Synchronisierung läuft; nach dem Intervall erneut versuchen) zurückkommen. source test antwortet mit source_test_failed und dem Grund, wenn die Adresse nicht gelesen werden kann.

Kalender

Eine Kalenderquelle liest iCalendar-Adressen (ICS): die geheime Adresse, die Google Kalender, Outlook, iCloud und Nextcloud für einen Kalender angeben, sowie jeden webcal://-Link. Sie füllt eine Karte events mit einer Terminübersicht aller Kalender oder eine Karte study-rooms mit einem Raum pro Kalender.

Jeder Kalender hat ein Geheimnis, calendar_url.KEY, das seine Adresse enthält.

• Wiederkehrende Termine (tägliche, wöchentliche, monatliche und jährliche Regeln, Ausnahmen, verschobene und abgesagte Termine) und Zeitzonen werden auf dem Server aufgelöst. So behält ein Termin seine Uhrzeit über die Zeitumstellung hinweg, und eine Karte wiederholt nie die Regeln des Kalenders. Die Windows-Zeitzonennamen von Outlook werden erkannt.
• Private Termine (CLASS:PRIVATE oder CONFIDENTIAL) zeigen nur ihre Zeiten, mit dem privaten Titel und ohne Organisator oder Ort. Die Regel gilt für als privat markierte Termine und beurteilt nicht, was andere Termine verraten.
• Freie Zeit (als transparent oder frei markierte Termine) bleibt in einer Terminübersicht erhalten und entfällt in einer Raumtafel, in der nur belegte Zeit zählt. Abgesagte Termine werden verworfen, vorläufige zählen als belegt.
• Ganztägige Termine erscheinen als Datum; ein Termin ohne Ende zeigt kein Ende.
• Warnungen. Nennt ein Feed keine Zeitzone, verwendet eine, die screenRIG nicht zuordnen kann, oder enthält mehr als 500 Wiederholungen eines Termins oder mehr als 5.000 Termine, gelingt die Synchronisierung, und der Status zeigt eine Warnung.
• Mehrere Kalender werden gemeinsam synchronisiert: Schlägt einer fehl, schlägt die ganze Synchronisierung fehl, und der Fehler nennt den Kalender, sodass eine Tafel nie einen unvollständigen Satz zeigt.

Termine nach Stichwort behalten oder ausblenden

Quellen vom Typ ics, microsoft365, google_calendar und momentus haben zwei optionale Einstellungen, include und exclude, jeweils eine Liste von 1 bis 20 Stichwörtern mit 1 bis 100 Zeichen. Ein Termin bleibt erhalten, wenn sein Titel mindestens ein include-Stichwort enthält (wenn include gesetzt ist) und keines der exclude-Stichwörter. Ein Stichwort passt innerhalb eines Titels ohne Rücksicht auf Groß- und Kleinschreibung oder Akzente, sodass café und CAFE einander entsprechen.

• Nur der Titel. Ort, Organisator und Beschreibung werden nie verglichen. Ein Termin ohne Titel wird als Untitled event verglichen.
• Private Termine werden anhand ihres eigenen Titels verglichen und zeigen weiterhin den privaten Titel. Der private Titel selbst wird nie verglichen, sodass exclude: ["private"] nichts entfernt.
• Alles, was die Quelle schreibt, liest die gefilterten Kalender: die Karte und jedes Raumdokument mit Schlüssel. Ein Filter entfernt nur Termine, nie einen Kalender oder einen Raum, und freie Termine zählen wie die übrigen.
• Der Status zählt, was ausgelassen wurde, als filtered, auch 0. Enthält das Fenster Termine und lassen die Stichwörter keinen übrig, ist die Synchronisierung erfolgreich, mit einer Warnung, die Stichwörter zu prüfen, und die Karte zeigt eine leere Liste. source test zeigt dasselbe.

screenrig source create --kind ics --card crd_EVENTS --name "Public events" \
  --set 'calendars=[{"key":"main"}]' --set 'include=["open house","tour"]' --set 'exclude=["cancelled"]' \
  --secret calendar_url.main=@calendar.url

Tabellenblätter, CSV und JSON

Eine sheets-, csv- oder json-Datenquelle liest eine Tabelle oder ein JSON-Dokument und baut daraus mit einer Zuordnung die Daten einer Karte auf, sodass sie jede Karte füllt: eine Speisekarte aus einer Preisliste, eine Kennzahlentafel aus einem Kennzahlenblatt, eine Tabelle aus einem Tabellenblatt mit Ergebnissen. Die Zuordnung ist eine JSON-Vorlage in den Einstellungen der Datenquelle. Die eigenen Regeln der Karte entscheiden, ob das Ergebnis der Zuordnung akzeptiert wird, und source test gibt das Dokument aus und sagt, ob die Karte es akzeptiert; Sie bearbeiten die Zuordnung also, bis sie es tut. Diese Datenquellen synchronisieren alle 5 Minuten, frühestens jede Minute.

screenrig source test --kind sheets --card crd_MENU --settings @menu-sheet.json
screenrig source create --kind sheets --card crd_MENU --name "Cafe menu" --settings @menu-sheet.json
screenrig source create --kind json --card crd_KPI --name "Daily numbers" \
  --settings @kpi-api.json --secret token=@api.token

Ein Google-Tabellenblatt freigeben

Eine sheets-Datenquelle liest das Tabellenblatt über den CSV-Export von Google. Sie braucht keine Anmeldung und keinen Zugriff auf Ihr Google-Konto, und das Tabellenblatt muss für jeden lesbar sein, der den Link hat.

1. Wählen Sie in Google Sheets Freigeben, stellen Sie Allgemeiner Zugriff auf Jeder, der den Link hat und die Rolle auf Betrachter. Zum Veröffentlichen wählen Sie stattdessen Datei, Teilen, Im Web veröffentlichen.
2. Kopieren Sie den Link aus der Adressleiste des Browsers in url. Ein Link zu einem Tab behält diesen Tab. Um einen anderen Tab über seinen Namen zu lesen, setzen Sie sheet; ein veröffentlichter Link nimmt kein sheet.
3. Sehen Sie die Vorschau mit source test an. Die Kopfzeile des Tabellenblatts wird zu den Spaltenschlüsseln, die die Zuordnung liest.

Ein Tabellenblatt, das nicht freigegeben ist, antwortet mit einer Anmeldeseite, einem 401 oder einem 403. Der Status ist dann not_shared, und die Meldung nennt die Einstellung, die zu ändern ist: Freigeben, Allgemeiner Zugriff, Jeder, der den Link hat, Betrachter, oder Datei, Teilen, Im Web veröffentlichen. Bitten Sie den Eigentümer des Tabellenblatts, es freizugeben. not_shared beurteilt nur diese drei Antworten. Es vergleicht die Spalten nicht mit Ihrer Zuordnung.

Adressen mit Token

Eine CSV-Datei oder ein JSON-Dokument an einer öffentlichen Adresse braucht kein Token. Für eine geschützte setzen Sie auth auf bearer (screenRIG sendet Authorization: Bearer TOKEN) oder auf header mit header_name (es sendet HEADER_NAME: TOKEN) und übergeben das Token als Geheimnis token:

screenrig source create --kind csv --card crd_TABLE --name "Standings" \
  --settings @standings.json --secret token=@api.token

Das Token wird verschlüsselt gespeichert und nur als Hinweis zurückgegeben: seine letzten vier Zeichen, wenn es 12 oder mehr hat, sonst …. Es wird nur an den eigenen Ursprung der Adresse gesendet: Schema, Host und Port. Einer Weiterleitung zu einer anderen Website wird mit dem Token nicht gefolgt, und die Datenquelle auf einen anderen Ursprung zu richten, ohne das Token erneut einzugeben, wird mit source_secret_required abgelehnt. Wird nur der Pfad oder die Abfrage geändert, bleibt das Token erhalten. Für basic, OAuth 2 und Token-Anfragen sowie für eine Anfrage mit Body, Headern oder Seiten siehe Anfragen, Anmeldung und Seiten. header_name darf nicht Host, Cookie, Content-Length, Connection, Transfer-Encoding, Upgrade oder ein Proxy--Header sein, und auch kein Header, den screenRIG selbst setzt.

Anfragen, Anmeldung und Seiten

Eine csv- oder json-Quelle sendet ein GET an ihre url. Mit diesen Einstellungen senden Sie einen Body oder zusätzliche Header, melden sich an, lesen mehr als eine Seite und setzen das heutige Datum in eine Anfrage. Jede Anfrage hat 20 Sekunden, ein ganzer Lauf 60.

Ein Secret mit dem Namen header.NAME wird als Header NAME gesendet, sodass eine API mit zwei Zugangs-Headern header.X-Client-Id und header.X-Api-Key verwendet. Ein Secret mit dem Namen query.NAME wird der Adresse als NAME=value angehängt. Jede Art erlaubt bis zu 8, beide werden versiegelt gespeichert und nie angezeigt, und die Vorschau gibt ein Abfrage-Secret als NAME=*** aus.

screenRIG hält ein Token im Arbeitsspeicher, nie im Speicher, und erneuert es eine Minute vor dem Ablauf. Lehnt die Adresse ein Token mit 401 ab, fordert es einmal ein neues an. Eine Ablehnung an der Token-Adresse (HTTP 400, 401 oder 403) ist auth_failed, und nichts, was die Token-Adresse sagt, wird zitiert.

{
  "url": "https://api.example.com/v2/orders/summary",
  "method": "POST",
  "body": {"from": "{{today-7d}}", "to": "{{today}}"},
  "time_zone": "America/Vancouver",
  "auth": "oauth2",
  "token_url": "https://login.example.com/oauth/token",
  "client_id": "screen-signs",
  "scope": "orders.read",
  "mapping": {"body": "{{body.total}} orders this week"}
}

screenrig source create --kind json --card crd_BOARD --name "Orders" \
  --settings @orders.json --secret client_secret=@client.secret

Datumsplatzhalter füllen die Adresse, den Body und headers: {{now}} (2026-11-01T17:30:00Z), {{today}} (2026-11-01) und {{unix}} (Sekunden), jeweils mit einem optionalen Versatz wie {{now-90m}}, {{now+7d}} oder {{today-1d}} (Einheiten m, h und d; {{today}} kennt nur Tage). Sie werden in time_zone gelesen oder in UTC. Jeder Lauf füllt sie aus der Uhr, sodass der Lauf von morgen das Datum von morgen anfragt.

Seiten. pagination ist {type, max_pages}, mit max_pages von 1 bis 20 (standardmäßig 5). Eine json-Quelle setzt rows_path, damit die Zeilen der Seiten in einem Array zusammenlaufen, und eine csv-Quelle verbindet die Tabellenzeilen.

Die nächste Adresse muss beim eigenen Ursprung der Quelle bleiben, damit ein Secret ihn nie verlässt. Eine wiederholte Seite oder mehr Seiten als max_pages beenden das Lesen mit einer Warnung, und alle Seiten zusammen umfassen höchstens 5 MB.

XML und RSS. Eine Antwort, die mit < beginnt, oder format xml wird als XML gelesen. body enthält das Wurzelelement: Attribute sind @name, der Text eines Elements mit Kindern ist #text, wiederholte Elemente sind Listen, und Namen behalten ihr Präfix (item["media:thumbnail"]["@url"]). Ein RSS- oder Atom-Feed erhält zusätzlich body.items, jeden Eintrag mit title, link, published, summary (reiner Text, bis zu 1.000 Zeichen) und image, sofern der Eintrag sie hat. Ein DOCTYPE wird nie verfolgt, und nichts wird daraus abgerufen.

source test zeigt in request die erste Anfrage, wie sie abgeschickt wurde: die ausgefüllten Platzhalter, Abfrage-Secrets als NAME=***, die Namen der Header außer Accept und Content-Type ohne ihre Werte, das erste KiB des Body und die Anzahl der gelesenen Seiten.

Was eine Datenquelle liest

• CSV und Tabellenblätter. Gewöhnliches CSV: Eine Byte-Order-Mark, Felder in Anführungszeichen, verdoppelte Anführungszeichen, Zeilenumbrüche innerhalb von Anführungszeichen und CRLF-Zeilenenden werden gelesen. Zellen werden gekürzt, Zeilen ohne Inhalt entfallen. Eine Kopfzeile wird zu einem Schlüssel in Kleinbuchstaben ohne Akzente, wobei jede Folge anderer Zeichen zu einem einzigen _ wird, sodass Sold out zu sold_out wird; eine leere Kopfzeile wird zu column_3 (ihrer Position) und eine Wiederholung zu _2, _3. Eine Datei, die kein UTF-8-Text ist, etwa eine Tabellendatei, ist parse_failed: Speichern Sie sie als CSV in UTF-8.
• JSON. Zahlen behalten ihre Ziffern. Mit rows_path sucht die Datenquelle dort das Array der Zeilen; ein Pfad, der kein Array findet, ist mapping_failed bei rows_path, und ein leeres Array ist eine Tabelle ohne Zeilen.
• Grenzen. Eine Tabelle wird bis zu 10.000 Zeilen und 200 Spalten gelesen. Darüber hinaus gelingt die Synchronisierung, und der Status zeigt eine Warnung, die die ausgelassenen Zeilen oder Spalten zählt.
• Eine Webseite an der Adresse statt der Daten ist parse_failed.

Die Zuordnung

Die Zuordnung ist eine JSON-Vorlage. Eine Zeichenfolge mit Platzhaltern wie {{item.price}} ist Text, und eine Zeichenfolge, die genau ein Platzhalter ist, behält den Typ des Werts. Ein Pfad, der nichts enthält, ist in Text leer und lässt einen einzelnen Wert weg, sodass die Karte dann benennt, was ihr fehlt. Wo ein Pfad beginnen kann, hängt von der Art ab:

Bevorzugen Sie by_key gegenüber einer Position wie rows[2]: Eine über ihren Schlüssel gefundene Zeile bleibt gefunden, wenn jemand das Tabellenblatt sortiert oder darüber eine Zeile einfügt. Schreiben Sie einen Schlüssel mit Leerzeichen als by_key["Net sales"].value. Teilen sich zwei Zeilen einen Schlüssel, gewinnt die erste, und der Status zeigt eine Warnung, die die Wiederholungen zählt. Keine Warnung zitiert eine Zelle.

Zellen sind Text, wandeln Sie sie also um: {"$number": "{{item.price}}"} liest 1,234.50, $4.50, 3,50 € und 12% (fügen Sie "$decimal": "," für ein Dezimalkomma hinzu), und {"$bool": "{{item.sold_out}}"} liest true, yes, y, 1 und x. $each durchläuft eine Liste mit item und index im Geltungsbereich, $group mit $by gruppiert Zeilen in der Reihenfolge des ersten Auftretens mit group.key und group.items im Geltungsbereich, und $text mit $max kürzt Text. Die Vorlage wird beim Speichern der Datenquelle geprüft.

Eine Speisekarte aus einem Tabellenblatt mit den Spalten Section, Item, Price und Sold out gruppiert die Zeilen nach Abschnitt:

{
  "url": "https://docs.google.com/spreadsheets/d/SHEET_ID/edit#gid=0",
  "mapping": {
    "sections": {
      "$group": "{{rows}}", "$by": "{{item.section}}",
      "$template": {
        "name": "{{group.key}}",
        "items": {
          "$each": "{{group.items}}",
          "$template": {
            "name": "{{item.item}}",
            "price": { "$number": "{{item.price}}" },
            "soldOut": { "$bool": "{{item.sold_out}}" }
          }
        }
      }
    }
  }
}

Eine Kennzahlentafel aus einem Tabellenblatt mit den Spalten Metric, Value, Unit und Change sucht jede Kennzahl über ihren Namen, sodass Sortieren des Blatts nichts verschiebt:

{
  "url": "https://docs.google.com/spreadsheets/d/SHEET_ID/edit#gid=0",
  "key_column": "Metric",
  "mapping": {
    "tiles": [
      { "label": "Revenue", "value": { "$number": "{{by_key.Revenue.value}}" },
        "unit": "{{by_key.Revenue.unit}}", "delta": { "$number": "{{by_key.Revenue.change}}" } },
      { "label": "Orders", "value": { "$number": "{{by_key.Orders.value}}" },
        "delta": { "$number": "{{by_key.Orders.change}}" } }
    ]
  }
}

Eine Tabellenkarte listet jede Zeile auf:

{
  "mapping": {
    "rows": {
      "$each": "{{rows}}", "$limit": 50,
      "$template": {
        "team": "{{item.team}}",
        "points": { "$number": "{{item.points}}" },
        "played": { "$number": "{{item.played}}" }
      }
    }
  }
}

Um zu sehen, was eine Datenquelle liest, testen Sie mit der Zuordnung {"columns": "{{columns}}", "rows": "{{rows}}"}. Die Karte lehnt dieses Dokument ab, und die Vorschau gibt es trotzdem aus, mit jedem Schlüssel und jeder Zeile.

ok bei einer dieser Datenquellen bedeutet, dass die Adresse geantwortet und die Karte das zugeordnete Dokument akzeptiert hat. Es sagt nicht, dass das Tabellenblatt oder die Antwort die Zeilen enthält, die Ihre Zuordnung erwartet: Eine verschwundene Spalte lässt ihr Feld weg, und die Karte lehnt ein Dokument ab, dem ein Pflichtfeld fehlt.

Berechnete Werte

Eine Zuordnung kann auf dem Server auch Wahr oder Falsch und Zahlen berechnen, sodass eine Seitenbedingung, die nur Gleichheit prüft, wie visibility.data mit equals: true, einer Zahl folgen kann. Die Zuordnungen von Karten-Webhooks und Overlay-Triggern haben dieselben Hilfsfunktionen.

• Ein Vergleich, der sich nicht ausführen lässt, ist falsch, mit einer Warnung, die die Stelle nennt und nie den Wert, sodass ein fehlender, leerer oder nicht numerischer Wert nie eine Seite einschaltet. $bool ist der einzige Leser, der einen fehlenden Wert als falsch nimmt.
• Listen. $of liest einen Platzhalter aus jedem Element, wobei item und index verfügbar sind, und $where behält die Elemente, für die eine Bedingung gilt. Ein leeres oder nicht numerisches Element wird übersprungen, und eine Warnung zählt sie. Gibt es nichts zu addieren, sind $sum und $count gleich 0, und $avg, $min und $max lassen ihr Mitglied weg.
• Zahlen. Ein Dezimalkomma (3,50, 1.234,50) braucht "$decimal": ",". $avg rundet auf 2 Stellen, und "$round" legt 0 bis 6 fest. $sum, $min und $max sind exakt.

Ein Niedrigbestand-Flag aus einer JSON-Antwort. Eine Seite, deren visibility.data das Dokument mit path /low_stock und equals true benennt, erscheint nur, solange der Bestand niedrig ist:

{
  "sku": "{{body.sku}}",
  "stock": {"$number": "{{body.stock}}"},
  "low_stock": {"$lt": ["{{body.stock}}", 5]}
}

Aus einem Tabellenblatt jedes Produkt unter seinem eigenen Nachbestellwert:

{"low_stock": {"$gt": [{"$count": "{{rows}}", "$where": {"$lt": ["{{item.stock}}", "{{item.reorder_at}}"]}}, 0]}}

Dokumente mit Schlüsseln

JSON-, CSV- und Sheets-Quellen akzeptieren key_template, zum Beispiel room-{screen.field.room}. Bilden Sie den Feed auf ein documents-Array aus {"fields":{"room":"A101"},"document":{"body":"Room A101"}}-Objekten ab. Ein Karten-Webhook verwendet --key-template mit derselben Ausgabe oder empfängt das umschließende Objekt direkt ohne Zuordnung.

{
  "key_template": "room-{screen.field.room}",
  "mapping": {
    "documents": {
      "$each": "{{rows}}",
      "$template": {
        "fields": {"room": "{{item.room}}"},
        "document": {"body": "{{item.title}}"}
      }
    }
  }
}

Platzieren Sie die zugehörige crd_-Instanz mit data: "room-{screen.field.room}"; jeder Bildschirm liest nur den Schlüssel, der aus seinem eigenen Feld room gebildet wird. Alle Ausgaben verwenden das Kartenschema der Instanz. Verwenden Sie getrennte Instanzen, Zuordnungen und Präfixe für verschiedene Kartentypen aus demselben Feed.

Zeigen Sie mit source test eine Vorschau an. Ungültige Dokumente, fehlende Felder und doppelte Schlüssel führen zur Ablehnung des Stapels vor dem Schreiben. Ein Speicherfehler kann einen teilweise geschriebenen Stapel hinterlassen: Senden Sie denselben Webhook-Inhalt mit demselben Idempotency-Key erneut oder aktualisieren Sie die Quelle. Ausgelassene Schlüssel behalten ihre bisherigen Daten und Ablaufzeiten; Webhooks setzen keine Ablaufzeit. Entfernen Sie die Vorlage eines Webhooks mit --clear-key-template.

Tipps für Dateien und Tabellenblätter

• OneDrive und SharePoint. Ein Freigabelink öffnet eine Vorschauseite, die eine Quelle als Webseite liest (parse_failed). Hängen Sie ?download=1 an den Link einer CSV-Datei an, oder &download=1, wenn er schon ein ? hat, damit der Link die Datei selbst liefert. Der Link muss ohne Anmeldung funktionieren.
• Zeilen nach Namen nachschlagen. Setzen Sie key_column auf die Spalte, die jede Zeile benennt, über ihre Überschrift in beliebiger Schreibweise, und lesen Sie eine Zeile als by_key.NAME.column: Sortieren des Tabellenblatts oder Einfügen einer Zeile ändert nichts. Ein Name, der zu keiner Spalte passt, ergibt mapping_failed bei key_column, und ein wiederholter Schlüssel behält die erste Zeile mit einer Warnung, die die Wiederholungen zählt.

Besprechungsräume

Eine Raumquelle liest Kalender von Besprechungsräumen und füllt eine room-Karte, das Türschild eines Raums, oder eine room-board-Karte, alle Räume eines Gebäudes. Sie kann auch eine events-Agenda oder eine study-rooms-Karte füllen, und eine Kalenderadresse (ICS) füllt dieselben Karten.

Die Karten ermitteln auf dem Bildschirm jede Sekunde aus den Buchungen, die sie halten, ob ein Raum frei oder belegt ist und was als Nächstes kommt, sodass ein Schild auch bei getrenntem Bildschirm stimmt. Eine Raumquelle liest nur: Eine Karte zeigt Buchungen und nimmt keine Eingaben an, daher wird von einem Bildschirm aus nichts gebucht, beendet oder eingecheckt.

Microsoft-365-Raumpostfächer

Der Typ microsoft365 liest Exchange-Online-Raumpostfächer über Ihre eigene Microsoft-Entra-App, sodass die App, ihr Geheimnis und das, was sie lesen darf, bei Ihnen bleiben. Zwei weitere Einstellungen: tenant, die Verzeichnis-ID oder eine verifizierte Domäne wie contoso.com (common, organizations und consumers werden abgelehnt), und client_id, die Anwendungs-ID (Client-ID) der App. Das Geheimnis client_secret ist der Wert des geheimen Clientschlüssels der App.

1. Registrieren Sie im Microsoft-Entra-Admin-Center eine App mit nur einem Mandanten ohne Weiterleitungs-URI, fügen Sie einen geheimen Clientschlüssel hinzu (kopieren Sie seinen Wert, nicht die Geheimnis-ID), fügen Sie die Microsoft-Graph-Anwendungsberechtigung Calendars.Read hinzu und erteilen Sie die Administratoreinwilligung.
2. Beschränken Sie die App auf die Raumpostfächer. Calendars.Read erreicht jedes Postfach der Organisation, bis eine Anwendungszugriffsrichtlinie es einschränkt. Legen Sie die Räume in eine E-Mail-aktivierte Sicherheitsgruppe und führen Sie die ersten beiden Befehle unten in Exchange Online PowerShell aus; Test-ApplicationAccessPolicy antwortet Granted für einen Raum in der Gruppe. Exchange-RBAC für Anwendungen beschränkt eine App auf dieselbe Weise.
3. Raumpostfächer ersetzen den Betreff einer Besprechung durch den Namen des Organisators, sofern nichts anderes eingestellt ist. Um die Titel der Besprechungen anzuzeigen, führen Sie den dritten Befehl für jeden Raum aus.
4. Sehen Sie sich die Vorschau an und speichern Sie dann. source test meldet sich an, liest jeden Raum und berichtet, welche Räume und Buchungen gelesen wurden, eine Zahl pro Raum und, wenn die App auch Place.Read.All besitzt, wie viele Räume die Organisation auflistet.

# Exchange Online PowerShell
New-ApplicationAccessPolicy -AppId CLIENT_ID -PolicyScopeGroupId rooms@example.com -AccessRight RestrictAccess -Description "screenRIG room signs"
Test-ApplicationAccessPolicy -AppId CLIENT_ID -Identity boardroom@example.com
Set-CalendarProcessing -Identity boardroom@example.com -DeleteSubject $false -AddOrganizerToSubject $false

# screenRIG (source create takes the same options, plus --name)
screenrig source test --kind microsoft365 --card crd_ROOM \
  --set tenant=contoso.com --set client_id=CLIENT_ID --set time_zone=America/Los_Angeles \
  --set 'rooms=[{"key":"boardroom","email":"boardroom@example.com","name":"Boardroom","floor":"Level 4","capacity":12}]' \
  --secret client_secret=@secret.txt

• Zuordnung. Private und vertrauliche Besprechungen zeigen den privaten Titel und keinen Organisator. Als frei oder „Arbeitet an einem anderen Ort“ markierte Besprechungen und Besprechungen, die der Raum abgelehnt hat, sind freie Zeit; vorläufige Besprechungen gelten als belegt; abgesagte entfallen. Ganztägige Termine sind Daten in der Zeitzone des Raums.
• Takt. Eine Raumquelle synchronisiert alle 2 Minuten. Die Anmeldung gilt etwa eine Stunde und wird wiederverwendet.
• Fehler. Fehlercode und Fehlertext von Microsoft werden zitiert, zum Beispiel AADSTS7000215 bei falschem geheimem Clientschlüssel, und ein Raum, den die App nicht lesen kann, lässt die Synchronisierung fehlschlagen und wird genannt.
• Stattdessen eine Verbindung. Setzen Sie connection_id auf eine Microsoft-Verbindung des Projekts, in beiden Modi möglich, anstelle von tenant, client_id und client_secret. Die Quelle hält dann kein Secret und meldet sich so an wie die Verbindung.

Google-Workspace-Ressourcenkalender

Der Typ google_calendar liest Ressourcen- und Raumkalender mit Ihrem eigenen Google-Dienstkonto. Das Geheimnis service_account_key ist die Schlüsseldatei, wie Google sie ausstellt, und sein Hinweis ist die Adresse des Kontos. Die optionale Einstellung subject nennt den Nutzer, als der das Konto bei domänenweiter Delegierung handelt.

1. Aktivieren Sie in Google Cloud die Google Calendar API, erstellen Sie ein Dienstkonto und laden Sie einen JSON-Schlüssel dafür herunter.
2. Geben Sie dem Konto Zugriff auf die Räume. Entweder geben Sie jeden Raumkalender für die Adresse des Kontos frei, mit der Berechtigung „Alle Termindetails anzeigen“, oder Sie aktivieren in der Admin-Konsole die domänenweite Delegierung für das Konto mit dem Bereich https://www.googleapis.com/auth/calendar.events.readonly und setzen subject auf einen Nutzer, der die Räume sehen kann.
3. Die calendar_id eines Raums ist die Kalender-ID der Ressource in der Admin-Konsole unter Gebäude und Ressourcen; sie endet auf @resource.calendar.google.com. Sehen Sie sich die Vorschau mit source test an und speichern Sie dann.

screenrig source test --kind google_calendar --card crd_ROOM \
  --set time_zone=America/Los_Angeles \
  --set 'rooms=[{"key":"boardroom","calendar_id":"CALENDAR_ID","name":"Boardroom"}]' \
  --secret service_account_key=@key.json

• Zuordnung. Private und vertrauliche Termine zeigen den privaten Titel und keinen Organisator. Als transparent markierte Termine und Termine, die der Raum abgelehnt hat, sind freie Zeit; abgesagte Termine entfallen. Ganztägige Termine behalten ihre Daten.
• Fehler. Der Fehlertext von Google wird zitiert. Ein Kalender, den das Konto nicht sieht, wird im Fehler genannt, mit dem Hinweis, wie er freigegeben wird.
• Stattdessen eine Verbindung. Setzen Sie connection_id auf eine Google-Verbindung des Projekts anstelle von service_account_key. Mit der App von screenRIG liest die Quelle die Kalender, die das Konto sehen kann, das sie genehmigt hat. Dieses Konto muss also jeden Raumkalender sehen, den die Quelle auflistet, und subject ist nicht erlaubt.

Grenzen und Datenschutz

• Eine room-Karte hält die 200 frühesten Buchungen und eine room-board-Karte 60 pro Raum. Gibt es mehr, zeigt der Status eine Warnung mit der Zahl der ausgelassenen.
• Das Dokument der Karte enthält nur, was die Karte darstellt, weil jeder Bildschirm, der eine Karte zeigt, ihr Dokument behält. Eine room-Karte erhält Organisatoren nur, wenn showOrganizer eingeschaltet ist. Eine room-board-Karte erhält nie Organisatoren und erhält den privaten Titel anstelle jedes Besprechungstitels, außer showTitles ist eingeschaltet. Eine Änderung einer der beiden Einstellungen erreicht die Karte bei der nächsten Synchronisierung. Eine private Besprechung trägt in beiden Fällen den privaten Titel.
• Meldungen dieser Typen zitieren den Fehlertext, den Microsoft oder Google geantwortet hat, und niemals ein Geheimnis.

Das Buchungssystem eines Veranstaltungsorts

Die Art momentus liest die Funktionen (jede Nutzung eines Raums mit Datum und Uhrzeit) und die Räume einer Momentus-Enterprise-Installation, des früher als Ungerboeck und EBMS vertriebenen Systems, mit einem API-Benutzer, den Ihr Administrator in Momentus anlegt (Main Menu, Api Users). Sie füllt eine events-Card für ein Veranstaltungsverzeichnis, eine room-board-Card für eine Lobby oder einen Flur oder eine room-Card für einen Raum, und mit einem Dokument je Raum zeigt jeder Bildschirm die Buchungen seines eigenen Raums. Ein Raum, der sich kurz vor einer Veranstaltung ändert, erscheint innerhalb des Aktualisierungsintervalls, standardmäßig einer Minute.

Zwei Secrets: api_key, eine der Schlüssel-GUIDs des API-Benutzers, und api_secret, seine Secret-GUID. Beide werden versiegelt gespeichert, nie wieder angezeigt und neu eingegeben, wenn die Quelle auf einen anderen Server, eine andere Organisation oder einen anderen API-Benutzer zeigt.

screenrig source test --kind momentus --card crd_EVENTS \
  --set base_url=https://momentus.example.com/prod --set organization=10 \
  --set api_user=venue-api --set time_zone=America/Los_Angeles \
  --set 'exclude_status_codes=["XX"]' \
  --secret api_key=@key.guid --secret api_secret=@secret.guid
screenrig source create --kind momentus --card crd_EVENTS --name "Venue events" \
  --settings @momentus.json --secret api_key=@key.guid --secret api_secret=@secret.guid

source test liest Momentus, bringt das Dokument in Form, prüft es gegen die Card und zeigt die gelesenen Räume und Veranstaltungen (functions, functions_other_spaces, events_KEY). Es wird nichts gespeichert oder geschrieben.

• Was aus einer Funktion wird. Das Space der Funktion wählt den Raum, ihr Description ist der Titel (title_field kann eine ihrer alternativen Beschreibungen nennen) und der Name des Raums ist der Ort. Eine Funktion ohne Startzeit ist eine ganztägige Veranstaltung. Eine Funktion über mehrere Tage mit Uhrzeiten zeigt diese Uhrzeiten an jedem Tag; eine, die endet, bevor sie beginnt, läuft über Nacht.
• Private Titel. Ein room-board zeigt den privaten Titel, außer show_titles ist eingeschaltet, wie bei den anderen Raumarten.
• Fehler. Der eigene Text von Momentus wird nie zitiert, weil der Server Ihrer ist: auth_failed heißt, dass API-Benutzer, Schlüssel oder Secret falsch sind oder Funktionen und Räume nicht lesen dürfen, config_invalid, dass ein Filter keine gültige Momentus-Suche ist, und parse_failed, dass base_url eine Webseite und nicht die API erreicht hat.

Ein Schild für jeden Raum

Legen Sie room_key_prefix fest (zum Beispiel momentus-room-), und die Quelle schreibt zusätzlich für jeden Raum ein room-Dokument unter diesem Präfix gefolgt vom Raumschlüssel. Geben Sie dem Bildschirm jedes Raums seinen Raum und platzieren Sie eine room-Card, deren data-Schlüssel das Präfix gefolgt vom eigenen Feld des Bildschirms ist:

screenrig screen update scr_BALLROOM --field room=ballroom-a

Verwenden Sie den Inline-Katalogtyp room in diesem Wiedergabelisten-Primitiv:

{"id":"door","primitive":"card","card":"room","layout":"full","content_fit":"fill","params":{"room":"{screen.field.room}"},"data":"momentus-room-{screen.field.room}"}

crd_-Primitive verwenden params und major der Instanz; lassen Sie diese Felder weg. Das optionale data wählt einen Dokumentschlüssel oder eine Schlüsselvorlage pro Bildschirm. --card crd_ID der Quelle benennt weiterhin ihr Synchronisierungsziel. Setzen Sie für die Seite visibility.data.key auf momentus-room-{screen.field.room} und fügen Sie danach eine bedingungslose Ersatzseite hinzu.

Das Backend füllt das Feld im Manifest jedes Bildschirms, sodass eine Playlist jedem Bildschirm seinen eigenen Raum zeigt und ein Bildschirm ohne Raumfeld für diese Card nichts zeigt. area_key_prefix macht dasselbe für eine Fluranzeige: Der area jedes Raums gruppiert ihn, und eine room-board der Räume dieses Bereichs wird unter dem Präfix gefolgt vom Bereichsschlüssel geschrieben (area_card kann events sein). screen_field und area_field benennen die Bildschirmfelder, die die Prüfung unten liest (standardmäßig room und area).

Die Zuordnung prüfen

screenrig source rooms src_ID (und der Abschnitt Raumzuordnung auf der Seite der Quelle im Dashboard) listet die Räume, die die Quelle anbietet und die kein Bildschirm anzeigt, sowie die Bildschirme, deren Raum fehlt oder einen Raum nennt, den Momentus nicht hat:

screenrig source rooms src_VENUE

Ein Bildschirm erscheint im Bericht, wenn er einen Wert für das Feld hat oder wenn seine eigene Playlist eine Card platziert, die den Schlüssel liest. Jeder ist mapped, missing (die Playlist liest das Feld, der Bildschirm hat keins) oder unknown (der Wert nennt keinen Raum; der Bericht nennt den vermutlich gemeinten Raum, etwa dieselben Buchstaben in anderer Schreibweise). Korrigieren Sie einen Bildschirm mit screenrig screen update scr_ID --field room=ROOM_KEY. Der Bericht liest die Räume der letzten guten Aktualisierung der Quelle und ruft nichts ab; eine Quelle, die ihre rooms auflistet, kennt sie schon vor der ersten Aktualisierung.

Speisekarten aus Ihrer Kasse

Eine Square-, Shopify- oder Toast-Quelle füllt eine menu-Karte (Abschnitte mit Zeilen, jede mit einem Preis) oder eine price-matrix-Karte (Artikel an der Seite, Größen oben) aus dem Katalog, den Sie ohnehin pflegen. Eine Preisänderung, ein neuer Artikel oder eine Ausverkauft-Markierung erreicht die Bildschirme bei der nächsten Synchronisierung, alle 5 Minuten, oder sofort mit source refresh.

echo '{"title":"Counter","sections":[{"name":"Menu","items":[{"name":"Coffee"}]}]}' > menu.json
screenrig card create --type menu --file menu.json
screenrig source test --kind square --card crd_CARD --secret access_token=@square.token
screenrig source create --kind square --card crd_CARD --name "Counter menu" \
  --secret access_token=@square.token

Die erste Synchronisierung ersetzt die eigenen Abschnitte der Karte durch die des Katalogs. source test gibt das Dokument aus, das die Karte zeigen würde, ob die Karte es akzeptiert und was aufgefallen ist.

Was auf der Karte ankommt

• Abschnitt. Square: die Kategorie des Artikels. Shopify: die Kollektion, die Sie angeben, sonst der Produkttyp.
• Artikel und Größen. Square: der Artikel und seine Variationen. Shopify: das Produkt und seine Varianten (Default Title ist keine Größe).
• Preis. Square: der Preis der Variation oder der eigene Preis des Standorts dafür. Shopify: der Preis der Variante in der Währung des Shops.
• Beschreibung. Square: die Beschreibung des Artikels als reiner Text. Shopify: die Produktbeschreibung, die ersten 400 Zeichen.
• Tags. Square: die Ernährungspräferenzen vegan, vegetarisch und glutenfrei. Shopify: die Produkt-Tags vegan, vegetarian, gluten-free, spicy, new und popular.
• Ausverkauft. Square: die Ausverkauft-Markierung der Kasse am Standort, bis sie abläuft. Shopify: keine Variante ist verkäuflich. Keiner von beiden beurteilt Lagerbestände.

Ein Artikel mit mehreren Größen erscheint auf einer menu-Karte in einer Zeile je Größe (Latte (Small), Latte (Large)) und auf einer price-matrix-Karte in einer Spalte je Größe. Archivierte und gelöschte Artikel, Entwürfe und archivierte Produkte werden weggelassen. Bilder werden nicht übernommen: Eine Karte mit Fotos verwendet Projektmedien. Preise kommen in der Währung des Katalogs an, und die Einstellung currency der Karte zeichnet das Symbol; setzen Sie sie auf der Karte (€ für Euro). Der Status warnt, solange eine Karte noch $ vor Preisen in einer anderen Währung zeigt.

Square

1. Erstellen Sie im Square Developer Dashboard eine Anwendung. Das ist kostenlos und ändert nichts in Ihrem Geschäft.
2. Stellen Sie das Dashboard auf Production um, öffnen Sie Credentials, kopieren Sie das Production-Zugriffstoken und speichern Sie es in einer Datei. Verwenden Sie für die Sandbox deren Token und setzen Sie environment auf sandbox.
3. Legen Sie die Datenquelle mit --secret access_token=@FILE an. Ein Konto mit einem aktiven Standort verwendet ihn. Bei mehreren setzen Sie location_id; source test listet die Standorte des Kontos auf, wenn einer nötig ist.

Ein Square-Zugriffstoken trägt alle Berechtigungen des Kontos und lässt sich nicht einschränken. screenRIG verwendet es für zwei Lesevorgänge, die Standorte und die Artikelbibliothek, und sendet es nur an die eigenen Server von Square. Es wird verschlüsselt gespeichert, nur mit seinen letzten vier Zeichen angezeigt, und Sie können es jederzeit im Developer Dashboard ersetzen oder widerrufen.

Shopify

Die App benötigt die Berechtigung read_products und sonst nichts. Verbinden Sie sich mit einer von zwei Arten von Apps:

• Eine benutzerdefinierte App. Öffnen Sie im Shopify-Admin Einstellungen, Apps und Vertriebskanäle, Apps entwickeln. Geben Sie der App read_products, installieren Sie sie, lassen Sie das Admin-API-Zugriffstoken anzeigen und speichern Sie es in einer Datei. Legen Sie die Datenquelle mit --secret access_token=@FILE an.
• Eine App aus dem Dev Dashboard. Erstellen Sie auf dev.shopify.com eine App mit read_products und installieren Sie sie im Shop. Setzen Sie client_id und legen Sie die Datenquelle mit --secret client_secret=@FILE an. screenRIG tauscht beides gegen ein Zugriffstoken ein, das einen Tag gilt und sich selbst erneuert.

Toast

Eine Toast-Quelle liest die Speisekarten und Bestände eines Restaurants mit dem Standard-API-Zugang, den das Restaurant selbst anlegt: schreibgeschützt und für einen Standort.

1. Öffnen Sie in Toast Web Integrations, Toast API access, Manage credentials und erstellen Sie Zugangsdaten mit den Bereichen menus:read und stock:read. Toast verlangt Restaurant Management Suite Essentials oder höher und die Berechtigung Manage Integrations.
2. Kopieren Sie die Client-ID und das Client-Secret. Toast sendet die GUID des Restaurants per E-Mail, wenn es die Zugangsdaten erstellt.
3. Legen Sie die Quelle mit restaurant (der GUID), client_id und --secret client_secret=@FILE an.

screenrig source test --kind toast --card crd_MENU \
  --set restaurant=RESTAURANT_GUID --set client_id=CLIENT_ID --secret client_secret=@toast.secret

• Abschnitte und Zeilen. Eine Menügruppe mit Artikeln ist ein Abschnitt, und eine Untergruppe ist ein eigener Abschnitt. Ein Artikel in mehreren Gruppen ist ein einziger Artikel, unter der ersten davon. Ein nach Größe bepreister Artikel ergibt eine Zeile pro Größe.
• Preise. Basis- und Menüpreise, wie Toast sie liefert, und ein zeitabhängiger Preis, solange sein Zeitplan die Gegenwart abdeckt. Ein offener Preis hat keinen. Toasts Antwort enthält keine Währung, setzen Sie also currency an der Karte.
• Ausverkauft. Ein Artikel, den Toast als nicht vorrätig markiert, oder mit einer Menge von null oder weniger. Ein niedriger Bestand wird nie als ausverkauft gelesen.
• Tageszeiten. Ist zu der Uhrzeit keine Speisekarte verfügbar, schlägt die Synchronisierung mit config_invalid fehl, und die Karte behält ihre letzte Speisekarte. Eine Tafel, die Tageszeiten folgt, nimmt eine Quelle für jede oder nennt ihre Speisekarte.
• Zugangsdaten. Das Secret ist an die Umgebung und das Restaurant gebunden, sodass das Ändern von einem von beiden es erneut verlangt (source_secret_required). screenRIG meldet sich einmal pro Lauf an und teilt die Anmeldung zwischen Quellen mit denselben Zugangsdaten, wie Toast es verlangt. Modifikatoren, Kombis, Allergene, Portionen und Bilder werden nicht gelesen.

Was Sie erwarten können

• Größen. Eine price-matrix-Karte hat bis zu 6 Größenspalten, in der Reihenfolge, in der die Größen zum ersten Mal vorkommen. Sie nimmt variations nicht an.
• Grenzen. Eine menu-Karte fasst 8 Abschnitte mit 24 Zeilen, eine price-matrix-Karte 12 Abschnitte mit 40 Artikeln. Alles darüber wird weggelassen, und der Status zeigt eine Warnung mit der Anzahl; wählen Sie mit include_sections, was angezeigt wird.
• Ein zu großer Katalog (mehr als 30 Seiten mit Square-Artikeln und -Kategorien oder 500 Shopify-Produkte) lässt die Synchronisierung mit too_large fehlschlagen, statt einen Teil einer Speisekarte zu zeigen. Nennen Sie Kollektionen oder Abschnitte, um weniger anzuzeigen.
• Nichts anzuzeigen. Bleibt nach den Einstellungen kein Artikel übrig, schlägt die Synchronisierung mit config_invalid fehl, und die Karte behält ihre letzte Speisekarte.
• Ratenbegrenzung. Die Synchronisierung wartet bis zu 10 Sekunden, bis sich das Kontingent von Shopify aufgefüllt hat; eine begrenzte Synchronisierung wird im nächsten Intervall wiederholt.
• Clover und Lightspeed geben API-Zugang nur genehmigten Partnern, daher sind sie keine Quellen.

Gespeicherte Zugangsdaten sind an die Square-Umgebung oder den Shopify-Shop gebunden, für die sie eingegeben wurden. Wird die Datenquelle auf eine andere Umgebung oder einen anderen Shop gerichtet, werden die Zugangsdaten erneut verlangt (source_secret_required), sodass eine Datenquelle sie nirgendwohin sonst senden kann. Anfragen gehen nur an die Server von Square und an NAME.myshopify.com und lesen ausschließlich.

Sicherheit

Eine Adresse, die Zugriff gewährt, ist eine Zugangsdaten. screenRIG speichert sie verschlüsselt, gibt nur Schema und Host zurück und verwendet sie ausschließlich für die Synchronisierung. Datenquellen lesen öffentliche http(s)-Adressen auf Port 80 oder 443 und folgen höchstens drei Weiterleitungen; eine Adresse, die nicht zu einem öffentlichen Host aufgelöst wird, eine abgelehnte Verbindung und ein fehlgeschlagener Handshake lesen sich alle gleich, sodass eine Datenquelle nicht zum Erkunden eines Netzwerks taugt. Keine Meldung zitiert eine Adresse oder die erhaltene Antwort. Datenquellen lesen nur: Sie schreiben nie in einen Kalender.

Verwandt

• Karten: Kartentypen, Eigenschaften und Live-Daten.
• Signage-CLI: jeder Befehl screenrig.
• Verbindungen: eine gespeicherte Anmeldung bei Microsoft oder Google für Raumquellen, Power BI und Mediensynchronisierung.
• API-Referenz: die Routen /api/sources und ihre Probleme.