Singerソース

説明

Singerソース を使用すると、Singer Tapを使って、Stripe、GitHub、Slack、BigQueryなど、幅広いSaaSアプリ、API、データベースからPlaidCloudにデータを取り込めます。各Tapは1つのソース用のコネクタです。接続を作成するときにTapを選ぶと、PlaidCloudがそのTapに必要な設定フィールドを表示します。

Singerソースの利用は、2つの部分から成ります。

Singerソース接続 は、選択したTapとその設定（APIトークン、アカウントID、開始日など）を保持します。
Import Singer Source ワークフローステップ は、Tapで利用可能なストリームを検出し、インポートするストリームとそれぞれの格納先を選択して、抽出を実行します。

Singerソース接続はTapとその設定を保持します。Import Singer Sourceステップはそのストリームを検出し、選択したものをプロジェクトテーブルに格納します。

始める前に

ソースシステムの資格情報（たとえば、GitHubのパーソナルアクセストークンやStripeのAPIキー）と、データを格納したいプロジェクトおよびワークフローが必要です。

Singerソース接続を作成する

Tools > Connections を開きます。
新規接続 をクリックし、Singerソース を選択します。
接続に名前を付けます（例: GitHub (prod)）。
ドロップダウンから Tap を選択します。その下のフォームが再構築され、そのTapのフィールドが表示されます。完全なカタログと各ソースの設定ドキュメントへのリンクについては、Singerソースを参照してください。
Tapの設定フィールドに入力し、作成をクリックします。

設定フィールドの種類

フィールドはTapによって異なり、それぞれがTapの想定する値に合わせて表示されます。

テキスト — 1行の値（例: アカウントIDや開始日）。
パスワード — APIトークンやキーなどの機密情報。機密情報は書き込み専用です。接続を編集するときには表示されず、保存時に空白のままにすると、保存済みの値が保持されます。
数値 — 整数または小数（例: ポートやページサイズ）。
リスト — 1行につき1項目（例: リポジトリやプロジェクトIDの一覧）。
JSON — JSONとして入力する構造化された値で、Tapがオブジェクトまたはオブジェクトの配列を想定している場合に使用します。たとえば、CSV Tapのファイル定義は次のとおりです。
```
[
  { "entity": "orders", "path": "/data/orders.csv", "keys": ["id"] }
]
```
チェックボックス — オン/オフのオプション。

必須フィールドにはマークが付き、フォームは保存前にそれらを検証します（JSONと数値のフィールドが正しい形式であることを含みます）。

ストリームをワークフローにインポートする

ワークフローを開き、Analyze Steps タブに移動します。
ステップを追加し、タイプとして インポート: Singerソース を選択します。エディターが、ソース タブと ストリーム タブとともに開きます。
ソース タブで次の操作を行います。
- 接続（作成したSingerソース接続）を選択します。
- 同期モード を選択します。テーブル全体（実行ごとに置換）、増分（新しいデータを追加）、アップサート（キーでマージ） のいずれかです。
- ストリームを検出 をクリックします。検出はランナー上で実行され、初回は最大で約3分かかることがあります。ステータスには、見つかったストリームの数が表示されます。
ストリーム タブには、検出されたストリームごとに1行が表示されます。対象にしたいストリームごとに、次の操作を行います。
- その ストリーム パネルを開き、このストリームをインポート にチェックを入れます。
- ストリームのデータの格納先として ターゲットテーブル を選択します。
- 同期モードが アップサート の場合は、ストリームの キー列 を設定します（1行につき1つの列名）。このフィールドのデフォルトはTapが宣言した主キーです。別の列でマージするには、これを上書きします。モードが アップサート の場合、インポートするすべてのストリームに少なくとも1つのキー列が必要です。
ステップを保存し、ワークフローの一部として（または単独で）実行します。

同期モード

テーブル全体（実行ごとに置換） は、実行のたびにストリーム全体を再抽出し、ターゲットテーブルを置き換えます。小規模なソースや、完全に更新されるソースに使用します。
増分（新しいデータを追加） は、前回の実行以降に新しくなった行だけを抽出して追加し、前回の実行が終了した場所から再開します。Tapが増分同期できるストリーム、つまりレプリケーションキー（更新日時のタイムスタンプや増加するIDなど）を公開しているストリームでのみ機能します。増分を選択し、選択したストリームにレプリケーションキーがない場合、ステップはそのストリームをテーブル全体に切り替えるか、選択を外すよう求めます。
アップサート（キーでマージ） は、実行のたびにストリーム全体を再抽出し、ストリームの キー列 でターゲットにマージします。キーが既存の行と一致する行はその場で更新され、新しいキーの行は挿入されます。今回の実行に含まれない既存の行は保持されます。追加で生じる重複や、置換による全面的な再構築を避けながら、時間とともにレコードが変化するソースとテーブルを同期させるために使用します。ターゲットテーブルは最初の実行で作成されるため、最初のアップサートではすべての行が挿入されます。

資格情報の扱い

ステップは、接続の資格情報のコピーではなく、接続への参照を保存します。各実行は、実行時に接続の現在の資格情報を読み取ります。そのため、トークンやキーをローテーションするときは、接続で1回更新するだけで、それを使用するすべてのステップが次回の実行で新しい値を取得します。個々のステップで更新する必要はありません。

抽出は、Tap自身の設定だけを受け取る分離されたジョブで実行されます。他の接続やPlaidCloudの内部サービスにはアクセスできません。