data360-prepare

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

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

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

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

• sf data360 data-stream *
• sf data360 dlo *
• sf data360 transform *
• sf data360 docai *
• データを Data Cloud に取り込む方法の選択
• ソースの更新後に取り込みを再実行または再スキャンする
• コネクタの設定完了後に、Ingestion API によってバックアップされたストリームを準備する

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

• ソース接続の作成またはテストを続けている場合 → data360-connect
• DMO へのマッピング、または IR／データグラフの設計を行う場合 → data360-harmonize
• 取り込み済みデータをクエリする場合 → data360-query

---

最初に確認する必須コンテキスト

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

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

---

基本的な運用ルール

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

---

推奨ワークフロー

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

node ../data360-orchestrate/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. data360-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 トークン
• Ingestion エンドポイントでは、Salesforce インスタンスの URL ではなくテナント URL を使用します
• 202 はペイロードが処理対象として受け付けられたことを意味し、レコードをすぐにクエリできることを意味するものではありません
• 検証エラーは、多くの場合、Problem Records DLO ファミリーに表示されます

9. その後、ハーモナイズに進む

ストリームと DLO が正常であることを確認してから、data360-harmonize に引き継ぎます。

---

重要な注意点

• CRM を基盤とするストリームの動作は、完全なカスタムコネクターフレームワークの取り込みとは異なります。
• sf data360 data-stream run と sf data360 connection run-existing は互換性がありません。非構造化データの再スキャンには、ストリームレベルの更新を優先してください。
• SFDC ストリームはプラットフォーム管理のスケジュールで同期されます。data-stream run は、CRM コネクターの更新における一般的な制御方法ではありません。
• 一部の外部データベースコネクターは API 経由で作成できますが、ストリームの作成には UI フローまたは組織固有のブラウザー自動化が引き続き必要な場合があります。すべてのコネクタータイプで純粋な CLI によるストリーム作成が可能だと約束しないでください。
• SharePoint スタイルの非構造化データを初期設定する場合、UI では最小限の CLI による DLO 作成フローよりも多くの設定が可能なことがあります。
• ストリームを削除すると、削除モードによっては関連する 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>

---

参考資料

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