setting-up-a-custom-rest-source

カスタム REST ソースの設定

カスタムソースでは、JSON マニフェストを使って任意の HTTP REST API をクエリ可能なウェアハウステーブルにインポートできます。ソースごとに Python を用意する必要はありません。マニフェストは RESTAPIConfig で、PostHog の組み込み REST コネクター（Intercom、Attio、Sentry など）を動かすものと同じ形式です。そのため、汎用 REST エンジンが認証、ページネーション、JSONPath によるレコード抽出、増分カーソルを処理します。必要なのは、正しいマニフェストを作成し、ソースを作成する前に実データを使って検証することです。

この機能はベータ版です。上限は、1 つのマニフェストにつきリソース 50 個まで、1 つのプロジェクトにつきカスタムソース 5 個までです。

このスキルを使用する場合

• ユーザーが組み込みコネクターのない API（社内サービス、ニッチな SaaS、公開 API など）をインポートしたいと考えており、ドキュメントの URL を提示できるか、エンドポイントについて説明できる場合。
• ユーザーが「カスタム REST ソース」「カスタムソースのマニフェスト」「ドキュメントを基にコネクターを作成」と明示的に依頼した場合。

カスタムソースは代替手段です。ネイティブコネクターが適合しない場合にのみ使用してください。PostHog には数百種類のネイティブコネクターがあり、ここにすべてを列挙することはできません。そのため、API に組み込みコネクターがないと決めつけないでください。よく知られた SaaS アプリやデータベースのほとんどには組み込みコネクターがあり、誤って判断すると、実績のあるコネクターと重複する手書きマニフェストに誤って振り分けられてしまいます。以下のステップ 0 で、まずレジストリを確認してから作成を始めてください。適合するネイティブコネクターがある場合は、setting-up-a-data-warehouse-source に引き継いでください。

文法

作成を始める前に、references/manifest-reference.md を読んでください。これは RESTAPIConfig の全フィールドを解説するリファレンスで、認証方式、6 種類のページネーター、増分カーソル、親子のファンアウトについて、それぞれ例を示しています。この文法に沿ってマニフェストを作成し、フィールド名を推測しないでください。

基本構造：

{
  "client": {
    "base_url": "https://api.example.com/v1",
    "auth": { "type": "bearer" }
  },
  "resources": [
    {
      "name": "users",
      "primary_key": "id",
      "endpoint": {
        "path": "/users",
        "data_selector": "data",
        "paginator": { "type": "json_response", "next_url_path": "next" },
        "incremental": { "cursor_path": "updated_at", "start_param": "since" }
      }
    }
  ]
}

シークレットをマニフェストに直接記述してはいけません。 manifest_json に格納するのは、シークレット以外の構造だけです。認証情報は、client.auth.type に応じて選ばれる別のペイロードキー（ベアラー認証の場合は auth_token、api_key の場合は auth_api_key、http_basic の場合は auth_password、oauth2 の場合は auth_oauth2_client_secret。更新トークンのグラントの場合のみ auth_oauth2_refresh_token も使用）で渡します。エンジンは実行時に認証情報を注入し、PostHog はすべてのレスポンスからそれをマスキングします。トークンを直接記述すると、検証時に拒否されます。

利用可能なツール

ツール	目的
external-data-sources-wizard	PostHog がサポートするネイティブソースの種類をすべて一覧表示します。マニフェストを作成する前に、対象の API に組み込みコネクターがすでにあるかを確認するため、最初に（ステップ 0 で）実行してください。
external-data-sources-db-schema	マニフェストと認証情報を検証し、公開するリソース（テーブル）を、検出された主キーおよび増分カーソルとともに一覧表示します。これは検証と一覧表示のステップです。
external-data-sources-preview-resource	1 つのリソースから少量のライブデータを読み取ります。作成前に、実データに対して data_selector ／ primary_key ／ cursor_path を確認してください。
data-warehouse-source-setup	ソースを作成します。1 回の呼び出しで、マニフェスト内のすべてのリソースを既定の同期設定で有効にします。
external-data-sources-create	高度な作成機能です。schemas 配列を使って、同期するリソースをユーザーが個別に選択できます。
external-data-schemas-list	作成後に、テーブルごとの同期ステータスを確認します。

ワークフロー

ステップ 0 — まずネイティブコネクターを確認する

何かを作成する前に、external-data-sources-wizard を呼び出してネイティブソースの種類を一覧表示し、サービス名で照合して、対象の API が含まれているかを確認してください。カスタムソースは、ネイティブコネクターがない API 向けの代替手段です。よく知られた API ならサポートされているはずだと思い込んで、この確認を省略しないでください。ほとんどの API はサポートされています。

ネイティブコネクターが見つかった場合は、そこで処理を止めてユーザーに伝えてください。組み込みの方法のほうが簡単で実績もあり（認証、ページネーション、スキーマ、増分同期を処理します）、setting-up-a-data-warehouse-source に引き継いでください。一致するネイティブコネクターがない場合、または既存のコネクターがあるにもかかわらずカスタム REST の方法を明示的に試したい場合に限り、このスキルを続行してください。

ステップ 1 — API の構成を確認する

ドキュメントの URL（取得して、認証方式、一覧エンドポイント、レスポンスの構造、ページネーションを確認します）か、エンドポイントの自然言語による説明のいずれかを入手してください。インポートする各リソースについて、次の情報が必要です。

• 共通の base_url からの相対パスとメソッド（GET、またはクエリ形式の読み取りエンドポイントでは POST）、
• 認証方式（ベアラートークン／ヘッダーまたはクエリの API キー／HTTP ベーシック／ユーザーが所有するクライアントを使った OAuth2 — client_credentials または事前取得済みのリフレッシュトークン。対話型の authorization_code フローはサポートされていません）、
• レコードパス — JSON レスポンス内でレコードの配列が格納されている場所（例：data、results、items）、
• API のページネーション方式（次の URL、リンクヘッダー、カーソル、オフセット、ページ番号、または単一ページ）、
• 主キーフィールド、および
• 任意で、再同期時に新規または変更された行のみを取得するための増分カーソルフィールド（updated_at 形式など）。

認証情報の値をユーザーに尋ねてください。ただし、その値は auth_* ペイロードキーにのみ設定し、マニフェストには決して含めないことを伝えてください。

ステップ 2 — マニフェストを作成する

references/manifest-reference.md を参照して RESTAPIConfig を作成します。認証ブロックは認証方式に合わせ、ドキュメントに合ったページネーターを選び、data_selector にレコードのパスを設定します。API に updated_at のようなカーソルと、それに対応するクエリパラメーターがある場合は、incremental ブロックを追加します。親ごとに行を取得する必要があるエンドポイント（例：/forms/{form_id}/responses）では、親／子の resolve パラメーターを使用します。ファンアウトの例を参照してください。ネストは 1 階層までにします。

ステップ 3 — 検証してリソースを一覧表示する

external-data-sources-db-schema を { source_type: "Custom", manifest_json: "<stringified manifest>", auth_token: "<credential>" } で呼び出します。認証情報のキーは文字どおり auth_* ではありません。認証タイプに応じたキーを使用します：auth_token（bearer）、auth_api_key（api_key）、auth_password（http_basic）、または auth_oauth2_client_secret（リフレッシュトークンのグラントの場合は auth_oauth2_refresh_token も指定）。マニフェストの構造、ファンアウトのグラフ、認証情報（範囲を限定したライブプローブ）を検証し、リソースごとに detected_primary_keys と incremental_fields を含むテーブルエントリーを返します。400 が返された場合、message は平易な英語で記述されています（例：resources[0].endpoint.path: must not be empty）。マニフェストを修正して再試行してください。検証に成功するまで、この手順を繰り返します。

ステップ 4 — 各リソースをテスト読み込みする

各リソースについて、external-data-sources-preview-resource を { source_type: "Custom", payload: { manifest_json, auth_token }, resource_name: "<name>", limit: 10 } で呼び出します（auth_token キーは、ステップ 3 と同様に認証タイプによって異なります）。最大 limit 件の実際の行と、推定された columns が返されます。次の点を確認してください：

• data_selector が正しいこと — rows にラッパーオブジェクトではなく、想定したレコードが含まれていることを確認します。rows が [{ "data": [...] }] のようになっている場合、配列ではなくエンベロープを指定しています。data_selector を修正してください。
• primary_key が行に存在し、一意であること。
• 増分同期の cursor_path フィールドが行に存在し、ソート可能なタイムスタンプ／ID のように見えること。

ライブ接続に失敗した場合（ホストに到達できない、認証が拒否されたなど）、空の rows とともに error が返されます。認証情報または URL を修正して再試行してください。サンプルが正しく見えるまで、ステップ 2〜4 を繰り返します。

ステップ 5 — ソースを作成する

data-warehouse-source-setup を { source_type: "Custom", payload: { manifest_json, auth_token }, prefix: "<short_name>" } で呼び出します（auth_token キーは、ステップ 3 と同様に認証タイプによって異なります）。マニフェスト内のすべてのリソースを、適切な同期のデフォルト設定（マニフェストでカーソルが宣言されている場合は増分同期、それ以外は全件更新）で有効化し、ソースを作成します。ユーザーがリソースの一部だけを希望する場合は、代わりに schemas 配列を指定して external-data-sources-create を使用します（schemas の形式については setting-up-a-data-warehouse-source を参照してください）。短く小文字の prefix を選びます。HogQL では、テーブル名は {prefix}_{resource_name} になります。

作成後、external-data-schemas-list を呼び出して初回同期のステータスをユーザーに表示し、次のクエリ方法を案内します： SELECT * FROM {prefix}_{resource_name} LIMIT 10。

重要な注意事項

• 作成する前に必ずプレビューしてください。 db-schema ではマニフェストが解析でき、認証情報が有効であることを確認できます。プレビューでは、実際の行に対するフィールドのマッピング（data_selector / primary_key / cursor_path）を確認できます。プレビューを省略すると、同期される行がゼロになったり、行の形式が不正になったりするソースを作成してしまうことが最もよくあります。
• シークレットは auth_* にのみ設定してください。 manifest_json にトークン、キー、パスワードを直接記述しないでください。拒否されるうえ、マニフェストは非シークレット情報であり、クライアントにそのまま返されます。
• ファンアウトは1階層のみです。 子リソースはトップレベルの親リソースに依存できますが、親リソースをさらに子リソースにすることはできません。
• GET と POST のみです。 エンジンは上流のデータを読み取ります。PUT／PATCH／DELETE は拒否されるため、マニフェストによってソース API を変更することはできません。
• カーソルは慎重に選んでください。 created_at よりも、編集を検出できる updated_at のようなフィールドを優先してください。また、カーソルが日時以外（整数の ID など）の場合は、適切な型で比較されるように cursor_type を設定してください。
• OAuth2 のシークレットは、最初の db-schema／プレビュー／作成の呼び出し時に、サーバー管理の認証情報ストアに取り込まれます。 ローテーションされた使い捨てのリフレッシュトークンもサーバー側に保存されます。そのため、1つのセットアップ内でのこれらの呼び出しでは、client.auth ブロック全体を同一に保ち、毎回同じシークレットを再送信してください。セットアップの途中で認証ブロックのフィールドを変更すると、保存されたローテーション情報が破棄されます。使い捨てのリフレッシュトークンをローテーションするプロバイダーでは、その後ユーザーが新しいトークンを取得するまで、次のトークン発行が拒否されます。auth_oauth2_integration_id は自分で設定しないでください（サーバーが管理する値です）。トークンが無効になったソースに再接続するには、auth_oauth2_client_secret／auth_oauth2_refresh_token を再入力して更新してください。認証ブロックのフィールドについては、マニフェストのリファレンスにある OAuth2 のセクションを参照してください。