sf-datacloud-prepare

sf-datacloud-prepare：Data Cloud の準備フェーズ

ユーザーが取り込みとレイクの準備作業を必要としている場合に、このスキルを使用します。対象には、データストリーム、Data Lake オブジェクト（DLO）、変換、Document AI、非構造化データの取り込み、コネクタの設定から稼働中のストリームへの引き継ぎが含まれます。

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

次の作業が含まれる場合は、sf-datacloud-prepare を使用します。

• sf data360 data-stream *
• sf data360 dlo *
• sf data360 transform *
• sf data360 docai *
• Data Cloud へのデータの取り込み方法の選定
• ソースの更新後の取り込みの再実行または再スキャン
• コネクタの設定完了後に行う、Ingestion API を利用したストリームの準備

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

• ソース接続をまだ作成またはテストしている → sf-datacloud-connect
• DMO へのマッピング、または IR／データグラフの設計をしている → sf-datacloud-harmonize
• 取り込み済みのデータをクエリしている → sf-datacloud-retrieve

---

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

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

• 対象の組織エイリアス
• ソース接続名
• ソースオブジェクト／データセット／ドキュメントソース
• 希望するストリームの種類
• DLO の命名に関する要件
• ユーザーがストリームの作成、更新、実行、削除のどれを行うか
• ソースが CRM、データベースコネクタ、非構造化ファイルソース、Ingestion API フィードのどれか

---

基本的な運用ルール

• Data Cloud コマンドを実行する前に、外部プラグインのランタイムを確認します。
• 取り込みアセットを変更する前に、共通の準備状況分類を実行します：node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json。
• 新しい取り込みアセットを作成する前に、既存のストリームと DLO の確認を優先します。
• 通常の使用時は、2>/dev/null を使ってリンクされたプラグインの警告ノイズを抑制します。
• DLO の命名とフィールドの命名は、CRM 固有ではなく Data Cloud 固有のものとして扱います。
• ストリームを作成する前に、各データセットを Profile、Engagement、Other のどれとして扱うべきか確認します。
• 非構造化ソースを扱う際は、ストリームレベルの更新と接続レベルでの再実行を区別します。
• 初回のストリームまたは非構造化アセットの作成がプラットフォームによって制限されている場合は、UI での設定を意図的に使用します。
• 取り込みアセットが正常であることを明確に確認してから、Harmonize に引き継ぎます。

---

推奨ワークフロー

1. 準備作業に向けて準備状況を分類する

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

2. 既存の取り込みアセットを確認する

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

3. 作成前にストリームのカテゴリを確認する

カテゴリを提案する際は、次のルールを使用します。

カテゴリ	用途	一般的な要件
Profile	個人／エンティティのレコード	主キー
Engagement	時系列イベントまたはインタラクション	主キー + イベント時刻フィールド
Other	参照／設定／補助データセット	主キー

ソースが曖昧な場合は、そのデータセットを Profile、Engagement、Other のどれとして扱うべきか、ユーザーに明確に確認します。

4. 意図を明確にしてストリームを作成または確認する

sf data360 data-stream get -o <org> --name <stream> 2>/dev/null
sf data360 data-stream create-from-object -o <org> --object Contact --connection SalesforceDotCom_Home 2>/dev/null
sf data360 data-stream create -o <org> -f stream.json 2>/dev/null
sf data360 data-stream run -o <org> --name <stream> 2>/dev/null

5. DLO の構造を確認する

sf data360 dlo get -o <org> --name Contact_Home__dll 2>/dev/null

6. 適切な更新方法を選択する

ユーザーの目的に合う、より範囲の小さい更新方法を使用します。

sf data360 data-stream run -o <org> --name <stream> 2>/dev/null
sf data360 connection run-existing -o <org> --name <connection-id> 2>/dev/null

• data-stream run は、ストリームレベルの更新または再スキャンに最も近い方法です。
• connection run-existing は接続レベルで実行され、一部のコネクタのワークフローでは役立ちますが、非構造化ソースのストリーム更新を確実に代替する方法ではありません。
• 非構造化ドキュメントコネクタでは、新しく追加または変更されたファイルを再スキャンすることが目的の場合、data-stream run を優先します。

7. 非構造化ソースを慎重に扱う

SharePoint 形式のドキュメント取り込みでは、最小限の非構造化 DLO ペイロードは次のようになります。

{
  "name": "my_udlo",
  "label": "My UDLO",
  "category": "Directory_Table",
  "dataSource": {
    "sourceType": "SF_DRIVE",
    "directoryAndFilesDetails": [
      {
        "dirName": "SPUnstructuredDocument/<CONNECTION_ID>/<SITE_ID>",
        "fileName": "*"
      }
    ],
    "sourceConfig": {
      "reservedPrefix": "$dcf_content$"
    }
  }
}

ユーザーがより包括的なエンドツーエンドのパイプラインを必要としている場合は、初回の非構造化データ設定に UI を使用します。UI の手順では、最小限の CLI による DLO 作成フローでは自動的にプロビジョニングされない追加のドキュメントメタデータフィールドや下流のアセットを用意できる場合があります。

8. データ送信ワークフローにはローカルの Ingestion API の例を使用する

外部システムから Data Cloud にレコードを送信する場合：

1. sf-datacloud-connect でコネクタを作成します
2. sf data360 connection schema-upsert でスキーマをアップロードします
3. 必要に応じて、UI でストリームを作成します
4. examples/ingestion-api/ のローカルの例を使ってレコードを送信します

cd examples/ingestion-api
cp .env.example .env
python3 send-data.py

重要な詳細：

• 認証は段階的なフローです：JWT → Salesforce トークン → Data Cloud トークン
• 取り込みエンドポイントでは、Salesforce インスタンス URL ではなくテナント URL を使用します
• 202 はペイロードが処理対象として受け付けられたことを意味し、レコードをすぐにクエリできることを意味するわけではありません
• 検証エラーは、多くの場合 Problem Records DLO ファミリーに表示されます

9. その後にのみハーモナイゼーションに進む

ストリームと DLO が正常に動作するようになったら、sf-datacloud-harmonize に引き継ぎます。

---

重要な注意点

• CRM 連携ストリームの動作は、完全なカスタムコネクターフレームワークによる取り込みと同じではありません。
• sf data360 data-stream run と sf data360 connection run-existing は互換性がありません。非構造化データの再スキャンには、ストリームレベルの更新を優先してください。
• SFDC ストリームはプラットフォーム管理のスケジュールで同期されます。CRM コネクターの更新において、data-stream run は一般的な制御経路ではありません。
• 一部の外部データベースコネクターは API 経由で作成できますが、ストリームの作成には UI のフローや組織固有のブラウザー自動化が必要な場合があります。すべてのコネクタータイプで CLI のみでストリームを作成できると約束しないでください。
• SharePoint のような非構造化データの初期設定では、最小限の CLI による DLO 作成フローよりも、UI のほうが多くの設定を行える場合があります。
• ストリームを削除すると、削除モードで別途指定されていない限り、関連付けられた DLO も削除される場合があります。
• DLO のフィールド名は CRM のフィールド名と異なり、__c が _c に変換されるなどの違いがあります。
• リストの出力だけで十分だと決めつけず、Data Cloud SQL で DLO のレコード数をクエリしてください。
• CdpDataStreams は、現在の組織またはユーザーではストリームモジュールが制限されていることを意味します。むやみに再試行するのではなく、プロビジョニングや権限の確認を案内してください。

---

出力形式

Prepare task: <stream / dlo / transform / docai>
Source: <connection + object>
Target org: <alias>
Artifacts: <stream names / dlo names / json definitions>
Verification: <passed / partial / blocked>
Next step: <harmonize or retrieve>

---

参考資料

• README.md
• examples/ingestion-api/README.md
• ../sf-datacloud/assets/definitions/data-stream.template.json
• ../sf-datacloud/references/plugin-setup.md
• ../sf-datacloud/references/feature-readiness.md