connecting-datacloud

connecting-datacloud：Data Cloud 接続フェーズ

ユーザーがソース接続に関する作業（コネクタの検出、接続メタデータの確認、接続テスト、ソースオブジェクトの参照、コネクタスキーマの確認、外部ソース用のコネクタ固有のセットアップペイロードの準備）を必要としている場合に、このスキルを使用します。

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

以下の作業が含まれる場合は、connecting-datacloud を使用します。

• sf data360 connection *
• コネクタカタログの確認
• 接続の作成、更新、テスト、削除
• ソースオブジェクト、フィールド、データベース、スキーマの参照
• 使用中のコネクタタイプの特定
• Snowflake、SharePoint Unstructured、Ingestion API ソース用のコネクタ定義の準備

以下の場合は、別のスキルに委任します。

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

---

最初に収集する必要があるコンテキスト

次の情報を尋ねるか、推測します。

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

---

基本的な運用ルール

• まずプラグインのランタイムを確認します。../orchestrating-datacloud/references/plugin-setup.md を参照してください。
• 接続を変更する前に、共通の準備状況分類ツールを実行します。node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json
• 接続を作成する前に、読み取り専用で情報を確認することを優先します。
• 標準的な使用時には 2>/dev/null を使って、リンクされたプラグインの警告ノイズを抑制します。
• connection list には --connector-type が必要です。
• 名前で Salesforce 以外の接続を解決する場合、connection test に --connector-type を渡します。
• 組織に不慣れな場合は、まずストリームから既存のコネクタタイプを確認します。
• コネクタ固有の認証情報やパラメーターを独自に考案する前に、厳選されたサンプルペイロードを使用します。
• 厳選されたサンプルにないコネクタタイプの場合は、JSON を作成する前に、REST 経由で正常に動作している既存の UI 作成済み接続を確認します。
• 接続の作成が成功したからといって、すべてのコネクタタイプで API によるストリーム作成ができると約束しないでください。

---

推奨ワークフロー

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

node ../orchestrating-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 には、グローバルにすべてを一覧表示する実際のモードはありません。コネクタータイプで検索してください。
• コネクターカタログ名と接続のコネクタータイプは、必ずしも同じラベルではありません。
• ソースがデフォルトの Salesforce コネクターではない場合、名前を解決するために connection test で --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
• ../orchestrating-datacloud/references/plugin-setup.md
• ../orchestrating-datacloud/references/feature-readiness.md
• ../orchestrating-datacloud/UPSTREAM.md