Sources Singer

Description

Une source Singer permet à PlaidCloud d’extraire des données d’un vaste catalogue d’applications SaaS, d’API et de bases de données (par exemple Stripe, GitHub, Slack et BigQuery) à l’aide de taps Singer. Chaque tap est un connecteur pour une source ; vous choisissez le tap lors de la création de la connexion, et PlaidCloud affiche les champs de configuration dont ce tap a besoin.

L’utilisation d’une source Singer comporte deux parties :

1. Une connexion à une source Singer contient le choix du tap et ses paramètres (jeton d’API, ID de compte, date de début, etc.).
2. Une étape de workflow Import Singer Source détecte les flux disponibles du tap, vous permet de choisir ceux à importer et la destination de chacun, puis exécute l’extraction.

Note

PlaidCloud fournit un catalogue sélectionné de taps sous licence permissive. Les champs de configuration exacts diffèrent d’un tap à l’autre : le formulaire de connexion est généré à partir du tap que vous sélectionnez.

Une connexion à une source Singer contient le tap et ses paramètres ; l’étape Import Singer Source détecte les flux du tap et enregistre ceux que vous choisissez dans des tables de projet.

Avant de commencer

Vous avez besoin des informations d’identification du système source (par exemple, un jeton d’accès personnel GitHub ou une clé d’API Stripe), ainsi que du projet et du workflow dans lesquels vous voulez enregistrer les données.

Créer une connexion à une source Singer

1. Ouvrez Tools > Connections.
2. Cliquez sur Nouvelle connexion et choisissez Source Singer.
3. Donnez à la connexion un Nom (par exemple, GitHub (prod)).
4. Choisissez un Tap dans la liste déroulante. Le formulaire situé en dessous se reconstruit pour afficher les champs de ce tap. Consultez Sources Singer pour le catalogue complet et un lien vers la documentation de configuration de chaque source.
5. Renseignez les champs de configuration du tap, puis cliquez sur Créer.

Types de champs de configuration

Les champs dépendent du tap, et chacun est affiché de façon à correspondre à la valeur attendue par le tap :

• Texte : une valeur sur une seule ligne (par exemple, un ID de compte ou une date de début).

• Mot de passe : un secret tel qu’un jeton d’API ou une clé. Les secrets sont en écriture seule : ils ne sont pas affichés lorsque vous modifiez la connexion, et en laisser un vide à l’enregistrement conserve la valeur stockée.

• Numéro : un entier ou un décimal (par exemple, un port ou une taille de page).

• Liste : une entrée par ligne (par exemple, une liste de dépôts ou d’ID de projet).

• JSON : une valeur structurée saisie en JSON, utilisée lorsqu’un tap attend un objet ou un tableau d’objets. Par exemple, les définitions de fichiers d’un tap CSV :

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

• Case à cocher : une option activée/désactivée.

Les champs obligatoires sont signalés, et le formulaire les valide (y compris le fait que les champs JSON et numériques sont bien formés) avant l’enregistrement.

Importer des flux dans un workflow

1. Ouvrez le workflow et accédez à l’onglet Analyze Steps.
2. Ajoutez une étape et choisissez Importation : source Singer comme type. L’éditeur s’ouvre avec un onglet Source et un onglet Flux.
3. Dans l’onglet Source :
   • Choisissez la Connexion (votre connexion à une source Singer).
   • Choisissez un Mode de synchronisation : Table complète (remplacée à chaque exécution), Incrémentiel (ajout des nouvelles données) ou Upsert (fusion sur la clé).
   • Cliquez sur Détecter les flux. La détection s’exécute sur le runner et peut prendre jusqu’à environ trois minutes la première fois ; l’état indique le nombre de flux trouvés.
4. Dans l’onglet Flux, vous voyez une ligne par flux détecté. Pour chaque flux voulu :
   • Ouvrez son panneau Flux et cochez Importer ce flux.
   • Choisissez une Table cible pour la destination des données du flux.
   • Si le mode de synchronisation est Upsert, définissez les Colonnes clés du flux, un nom de colonne par ligne. Le champ reprend par défaut la clé primaire déclarée du tap ; remplacez-la pour fusionner sur d’autres colonnes. Chaque flux importé nécessite au moins une colonne clé lorsque le mode est Upsert.
5. Enregistrez l’étape et exécutez-la dans le cadre du workflow (ou seule).

Attention

Les flux que vous sélectionnez constituent l’ensemble enregistré. Pour modifier les flux importés, cliquez de nouveau sur Détecter les flux ; les flux qui réapparaissent conservent la table cible et la sélection que vous avez déjà définies.

Modes de synchronisation

• Table complète (remplacée à chaque exécution) réextrait tout le flux à chaque exécution et remplace la table cible. Utilisez ce mode pour les sources de petite taille ou entièrement actualisées.
• Incrémentiel (ajout des nouvelles données) n’extrait que les lignes nouvelles depuis la dernière exécution et les ajoute, en reprenant là où l’exécution précédente s’est arrêtée. Il ne fonctionne que pour les flux que le tap peut synchroniser de manière incrémentielle, c’est-à-dire ceux qui exposent une clé de réplication (comme un horodatage de mise à jour ou un ID incrémental). Si vous choisissez le mode incrémentiel et qu’un flux sélectionné n’a pas de clé de réplication, l’étape vous demande de passer ce flux en table complète ou de le désélectionner.
• Upsert (fusion sur la clé) réextrait tout le flux à chaque exécution, puis le fusionne dans la cible sur les Colonnes clés du flux : les lignes dont la clé correspond à une ligne existante sont mises à jour sur place, et les lignes dont la clé est nouvelle sont insérées. Les lignes existantes qui ne figurent pas dans cette exécution sont conservées. Utilisez ce mode pour maintenir une table synchronisée avec une source dont les enregistrements évoluent dans le temps, sans les doublons qu’un ajout créerait ni la reconstruction complète qu’un remplacement effectuerait. La table cible est créée à la première exécution, de sorte que le premier upsert insère toutes les lignes.

Note

La progression incrémentielle est suivie par étape. La première exécution incrémentielle extrait tout ; les suivantes ne récupèrent que les nouvelles lignes.

Note

L’upsert réextrait tout le flux à chaque exécution (il n’utilise pas de clé de réplication) ; il convient donc aux sources dont les lignes existantes sont mises à jour et pour lesquelles vous voulez une ligne par clé. Définissez les Colonnes clés de chaque flux dans l’onglet Flux ; elles reprennent par défaut la clé primaire déclarée du tap.

Attention

Choisissez des colonnes clés toujours renseignées. L’upsert fait correspondre les lignes sur la valeur exacte de la clé, et une clé vide (null) ne correspond jamais à une autre : les lignes dont la clé est nulle sont donc toujours insérées plutôt que fusionnées, et peuvent s’accumuler d’une exécution à l’autre.

Gestion des informations d’identification

L’étape stocke une référence à la connexion, et non une copie de ses informations d’identification. Chaque exécution lit les informations d’identification actuelles de la connexion au moment de l’exécution. Ainsi, lorsque vous renouvelez un jeton ou une clé, il suffit de le mettre à jour une fois dans la connexion, et chaque étape qui l’utilise prend en compte la nouvelle valeur à sa prochaine exécution ; il n’y a rien à mettre à jour sur les étapes individuelles.

L’extraction s’exécute dans une tâche isolée qui ne reçoit que la configuration propre au tap ; elle n’a accès ni aux autres connexions ni aux services internes de PlaidCloud.

Voir aussi

• Catalogue des sources Singer : toutes les sources disponibles et leur documentation de configuration
• Référence de l’étape Import Singer Source
• Connexions