sf-datacloud-connect

sf-datacloud-connect：Data Cloud 接続フェーズ

ユーザーがソース接続の作業を必要としている場合に、このスキルを使用します。コネクタの調査、接続メタデータの確認、接続テスト、ソースオブジェクトの参照、コネクタスキーマの調査、外部ソース向けのコネクタ固有の設定ペイロードなどが該当します。

このスキルが担当するタスク

次の作業を行う場合は、sf-datacloud-connect を使用します。

• sf data360 connection *
• コネクターカタログの調査
• 接続の作成、更新、テスト、削除
• ソースのオブジェクト、項目、データベース、スキーマの参照
• すでに使用されているコネクターの種類の特定
• Snowflake、SharePoint Unstructured、Ingestion API ソース向けのコネクター定義の準備

次の場合は、ほかのスキルに委任します。

• データストリームまたは DLO の作成 → sf-datacloud-prepare
• DMO、マッピング、IR ルールセット、データグラフの作成 → sf-datacloud-harmonize
• Data Cloud SQL または検索インデックスのワークフローの作成 → sf-datacloud-retrieve

---

最初に確認する必要があるコンテキスト

次の情報を尋ねるか、推測してください。

• 対象 org のエイリアス
• コネクターの種類またはソースシステム
• ユーザーが確認のみを希望しているか、実際の変更も希望しているか
• 既存の接続名または ID
• 認証情報が CLI の外部ですでに設定されているか
• 接続設定の直後にストリームも作成する想定か
• ソースがデータベース、非構造化ドキュメントのソース、Ingestion API フィードのいずれか

---

基本的な運用ルール

• まずプラグインのランタイムを確認してください。詳細は ../sf-datacloud/references/plugin-setup.md を参照してください。
• 接続を変更する前に、共有のレディネス分類ツールを実行してください：node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json。
• 接続を作成する前に、読み取り専用で調査することを優先してください。
• 通常の使用では、2>/dev/null を指定して、リンクされたプラグインの警告ノイズを抑制してください。
• connection list には --connector-type が必要です。
• connection test で名前から Salesforce 以外の接続を特定する場合は、--connector-type を指定してください。
• org の状況が不明な場合は、まずストリームから既存のコネクターの種類を調べてください。
• コネクター固有の認証情報やパラメーターを独自に考案する前に、厳選されたサンプルペイロードを使用してください。
• 厳選されたサンプルに含まれないコネクターの種類については、JSON を作成する前に、REST 経由で UI から作成済みの正常な接続を調べてください。
• 接続の作成に成功したからといって、あらゆるコネクターの種類で API によるストリーム作成が可能だと約束しないでください。

---

推奨ワークフロー

1. 接続作業の準備状況を分類する

node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json

2. コネクターの種類を調べる

sf data360 connection connector-list -o <org> 2>/dev/null
sf data360 data-stream list -o <org> 2>/dev/null

3. 種類ごとに接続を調べる

sf data360 connection list -o <org> --connector-type SalesforceDotCom 2>/dev/null
sf data360 connection list -o <org> --connector-type REDSHIFT 2>/dev/null
sf data360 connection list -o <org> --connector-type SNOWFLAKE 2>/dev/null

4. 特定の接続またはアップロード済みスキーマを調べる

sf data360 connection get -o <org> --name <connection> 2>/dev/null
sf data360 connection objects -o <org> --name <connection> 2>/dev/null
sf data360 connection fields -o <org> --name <connection> 2>/dev/null
sf data360 connection schema-get -o <org> --name <connection-id> 2>/dev/null

5. 調査後にのみテストまたは作成する

sf data360 connection test -o <org> --name <connection> --connector-type <type> 2>/dev/null
sf data360 connection create -o <org> -f connection.json 2>/dev/null

6. 外部コネクターには厳選されたサンプルペイロードを使用する

ペイロードを一から考案する前に、このフェーズ専用のサンプルを使用してください。

• examples/connections/heroku-postgres.json
• examples/connections/redshift.json
• examples/connections/sharepoint-unstructured.json
• examples/connections/snowflake-connection.json
• examples/connections/ingest-api-connection.json
• examples/connections/ingest-api-schema.json

Ingestion API の一般的な設定フロー：

sf data360 connection create -o <org> -f examples/connections/ingest-api-connection.json 2>/dev/null
sf data360 connection schema-upsert -o <org> --name <connector-id> -f examples/connections/ingest-api-schema.json 2>/dev/null
sf data360 connection schema-get -o <org> --name <connector-id> 2>/dev/null

7. 不明なコネクターの種類のペイロード項目を調べる

UI で接続を作成してから、直接調べてください。

sf api request rest "/services/data/v66.0/ssot/connections/<id>" -o <org>

---

重要な注意点

• connection list には真のグローバルな「すべてを一覧表示」モードはありません。コネクタータイプを指定して検索してください。
• コネクターカタログ名と接続のコネクタータイプは、必ずしも同じ名称とは限りません。
• connection test では、ソースがデフォルトの Salesforce コネクターでない場合、名前解決に --connector-type が必要になることがあります。
• 接続一覧が空の場合は、通常「有効だが、まだ設定されていない」という意味であり、「機能が無効」という意味ではありません。
• Heroku Postgres、Redshift、Snowflake、SharePoint Unstructured、Ingestion API では、認証情報とパラメーターの形式がそれぞれ異なります。推測せず、用意されている例を再利用してください。
• SharePoint Unstructured では、credentials 配列に clientId、clientSecret、tokenEndpoint を指定します。parameters 配列は必要ありません。
• Snowflake はキーペア認証を使用し、多くの場合 API 経由で作成できますが、後続のストリーム作成は引き続き UI でしか行えない場合があります。
• Ingestion API コネクターの設定は、connection schema-upsert でオブジェクトスキーマをアップロードするまで完了しません。
• 一部の外部コネクターの認証情報設定では、引き続き UI 側の設定や外部システムの権限が必要です。

---

出力形式

Connect task: <inspect / create / test / update>
Connector type: <SalesforceDotCom / REDSHIFT / SNOWFLAKE / SPUnstructuredDocument / IngestApi / ...>
Target org: <alias>
Commands: <key commands run>
Verification: <passed / partial / blocked>
Next step: <prepare phase or connector follow-up>

---

参考資料

• README.md
• examples/connections/heroku-postgres.json
• examples/connections/redshift.json
• examples/connections/sharepoint-unstructured.json
• examples/connections/snowflake-connection.json
• examples/connections/ingest-api-connection.json
• examples/connections/ingest-api-schema.json
• ../sf-datacloud/references/plugin-setup.md
• ../sf-datacloud/references/feature-readiness.md
• ../sf-datacloud/UPSTREAM.md