Singer-Quellen

Beschreibung

Eine Singer-Quelle ermöglicht es PlaidCloud, mithilfe von Singer-Taps Daten aus einem umfangreichen Katalog von SaaS-Apps, APIs und Datenbanken abzurufen – etwa Stripe, GitHub, Slack und BigQuery. Jeder Tap ist ein Connector für genau eine Quelle; Sie wählen den Tap beim Erstellen der Verbindung aus, und PlaidCloud zeigt die Konfigurationsfelder an, die dieser Tap benötigt.

Die Nutzung einer Singer-Quelle besteht aus zwei Teilen:

1. Eine Singer-Quellverbindung enthält die Tap-Auswahl und deren Einstellungen (API-Token, Konto-ID, Startdatum usw.).
2. Ein Workflow-Schritt Import Singer Source ermittelt die verfügbaren Streams des Taps, lässt Sie auswählen, welche importiert werden und wo jeder abgelegt wird, und führt die Extraktion aus.

Hinweis

PlaidCloud liefert einen kuratierten Katalog von Taps mit permissiven Lizenzen mit. Die genauen Konfigurationsfelder unterscheiden sich von Tap zu Tap – das Verbindungsformular wird anhand des ausgewählten Taps erzeugt.

Eine Singer-Quellverbindung enthält den Tap und seine Einstellungen; der Schritt Import Singer Source ermittelt die Streams des Taps und legt die von Ihnen ausgewählten in Projekttabellen ab.

Vorbereitung

Sie benötigen Anmeldedaten für das Quellsystem (zum Beispiel ein persönliches GitHub-Zugriffstoken oder einen Stripe-API-Schlüssel) sowie das Projekt und den Workflow, in denen die Daten abgelegt werden sollen.

Singer-Quellverbindung erstellen

1. Öffnen Sie Tools > Verbindungen.
2. Klicken Sie auf Neue Verbindung und wählen Sie Singer-Quelle.
3. Geben Sie der Verbindung einen Namen (zum Beispiel GitHub (prod)).
4. Wählen Sie in der Dropdown-Liste einen Tap aus. Das Formular darunter baut sich neu auf und zeigt die Felder dieses Taps. Den vollständigen Katalog und einen Link zur Konfigurationsdokumentation jeder Quelle finden Sie unter Singer-Quellen.
5. Füllen Sie die Konfigurationsfelder des Taps aus und klicken Sie dann auf Erstellen.

Typen von Konfigurationsfeldern

Die Felder hängen vom Tap ab, und jedes wird passend zu dem Wert dargestellt, den der Tap erwartet:

• Text – ein einzeiliger Wert (zum Beispiel eine Konto-ID oder ein Startdatum).

• Kennwort – ein Geheimnis wie ein API-Token oder -Schlüssel. Geheimnisse sind nur schreibbar: Sie werden beim Bearbeiten der Verbindung nicht angezeigt, und wenn Sie eines beim Speichern leer lassen, bleibt der gespeicherte Wert erhalten.

• Nummer – eine Ganzzahl oder Dezimalzahl (zum Beispiel ein Port oder eine Seitengröße).

• Liste – ein Eintrag pro Zeile (zum Beispiel eine Liste von Repositorys oder Projekt-IDs).

• JSON – ein strukturierter Wert, der als JSON eingegeben wird, wenn ein Tap ein Objekt oder ein Array von Objekten erwartet. Zum Beispiel die Dateidefinitionen eines CSV-Taps:

  [
    { "entity": "orders", "path": "/data/orders.csv", "keys": ["id"] }
  ]

• Kontrollkästchen – eine Ein/Aus-Option.

Pflichtfelder sind gekennzeichnet, und das Formular validiert sie (einschließlich der korrekten Form von JSON- und Zahlenfeldern), bevor es speichert.

Streams in einen Workflow importieren

1. Öffnen Sie den Workflow und wechseln Sie zur Registerkarte Analyze Steps.
2. Fügen Sie einen Schritt hinzu und wählen Sie Import: Singer-Quelle als Typ. Der Editor öffnet sich mit einer Registerkarte Quelle und einer Registerkarte Streams.
3. Auf der Registerkarte Quelle:
   • Wählen Sie die Verbindung (Ihre Singer-Quellverbindung).
   • Wählen Sie einen Synchronisierungsmodus – Gesamte Tabelle (bei jeder Ausführung ersetzen), Inkrementell (neue Daten anfügen) oder Upsert (über Schlüssel zusammenführen).
   • Klicken Sie auf Streams ermitteln. Die Ermittlung läuft auf dem Runner und kann beim ersten Mal bis zu etwa drei Minuten dauern; der Status zeigt an, wie viele Streams gefunden wurden.
4. Auf der Registerkarte Streams sehen Sie eine Zeile pro ermitteltem Stream. Für jeden gewünschten Stream:
   • Öffnen Sie sein Panel Stream und aktivieren Sie Diesen Stream importieren.
   • Wählen Sie eine Zieltabelle, in der die Daten des Streams abgelegt werden.
   • Wenn der Synchronisierungsmodus Upsert ist, legen Sie die Schlüsselspalten des Streams fest – ein Spaltenname pro Zeile. Das Feld ist standardmäßig mit dem vom Tap deklarierten Primärschlüssel belegt; überschreiben Sie ihn, um über andere Spalten zusammenzuführen. Jeder importierte Stream benötigt im Modus Upsert mindestens eine Schlüsselspalte.
5. Speichern Sie den Schritt und führen Sie ihn als Teil des Workflows aus (oder einzeln).

Achtung

Die von Ihnen ausgewählten Streams sind die gespeicherte Menge. Um zu ändern, welche Streams importiert werden, klicken Sie erneut auf Streams ermitteln – Streams, die wieder erscheinen, behalten die bereits festgelegte Zieltabelle und Auswahl.

Synchronisierungsmodi

• Gesamte Tabelle (bei jeder Ausführung ersetzen) extrahiert den gesamten Stream bei jeder Ausführung neu und ersetzt die Zieltabelle. Verwenden Sie diesen Modus für kleine oder vollständig aktualisierte Quellen.
• Inkrementell (neue Daten anfügen) extrahiert nur die seit der letzten Ausführung neuen Zeilen und fügt sie an, wobei dort fortgesetzt wird, wo die vorherige Ausführung aufgehört hat. Das funktioniert nur für Streams, die der Tap inkrementell synchronisieren kann – also solche, die einen Replikationsschlüssel bereitstellen (etwa einen Zeitstempel der letzten Änderung oder eine fortlaufende ID). Wenn Sie inkrementell wählen und ein ausgewählter Stream keinen Replikationsschlüssel hat, fordert der Schritt Sie auf, diesen Stream auf „Gesamte Tabelle“ umzustellen oder abzuwählen.
• Upsert (über Schlüssel zusammenführen) extrahiert den gesamten Stream bei jeder Ausführung neu und führt ihn dann über die Schlüsselspalten des Streams mit dem Ziel zusammen: Zeilen, deren Schlüssel mit einer vorhandenen Zeile übereinstimmt, werden an Ort und Stelle aktualisiert, und Zeilen mit neuem Schlüssel werden eingefügt. Vorhandene Zeilen, die in dieser Ausführung nicht enthalten sind, bleiben erhalten. Verwenden Sie diesen Modus, um eine Tabelle mit einer Quelle abgeglichen zu halten, deren Datensätze sich im Laufe der Zeit ändern – ohne die Duplikate, die ein Anfügen erzeugen würde, oder den vollständigen Neuaufbau, den ein Ersetzen bedeutet. Die Zieltabelle wird bei der ersten Ausführung erstellt, sodass das erste Upsert alle Zeilen einfügt.

Hinweis

Der inkrementelle Fortschritt wird pro Schritt nachverfolgt. Die erste inkrementelle Ausführung extrahiert alles; spätere Ausführungen übernehmen nur neue Zeilen.

Hinweis

Upsert extrahiert den gesamten Stream bei jeder Ausführung neu (es verwendet keinen Replikationsschlüssel) und eignet sich daher für Quellen, in denen vorhandene Zeilen aktualisiert werden und Sie eine Zeile pro Schlüssel wünschen. Legen Sie die Schlüsselspalten jedes Streams auf der Registerkarte Streams fest; sie sind standardmäßig mit dem vom Tap deklarierten Primärschlüssel belegt.

Achtung

Wählen Sie Schlüsselspalten, die immer vorhanden sind. Upsert gleicht Zeilen anhand des exakten Schlüsselwerts ab, und ein leerer (null) Schlüssel stimmt nie mit einem anderen überein – Zeilen mit einem Null-Schlüssel werden daher immer eingefügt statt zusammengeführt und können sich über mehrere Ausführungen ansammeln.

Umgang mit Anmeldedaten

Der Schritt speichert einen Verweis auf die Verbindung, keine Kopie ihrer Anmeldedaten. Jede Ausführung liest zur Laufzeit die aktuellen Anmeldedaten der Verbindung. Wenn Sie ein Token oder einen Schlüssel rotieren, aktualisieren Sie es daher einmal an der Verbindung, und jeder Schritt, der sie verwendet, übernimmt den neuen Wert bei seiner nächsten Ausführung – an den einzelnen Schritten ist nichts zu aktualisieren.

Die Extraktion läuft in einem isolierten Auftrag, der nur die eigene Konfiguration des Taps erhält; er hat keinen Zugriff auf andere Verbindungen oder auf interne Dienste von PlaidCloud.

Verwandte Themen

• Katalog der Singer-Quellen – jede verfügbare Quelle und ihre Konfigurationsdokumentation
• Referenz des Schritts Import Singer Source
• Verbindungen