preparing-datacloud

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

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

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

次の作業を含む場合は、preparing-datacloud を使用します。

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

次の場合は、別のスキルに引き継ぎます。

• ソース接続の作成またはテスト中の場合 → connecting-datacloud
• DMO へのマッピング、または IR／データグラフの設計の場合 → harmonizing-datacloud
• 取り込み済みデータのクエリの場合 → retrieving-datacloud

---

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

次の情報を確認するか、推測します。

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

---

基本的な運用ルール

• Data Cloud コマンドを実行する前に、外部プラグインのランタイムを確認します。
• 取り込みアセットを変更する前に、共通の準備状況分類を実行します：node ../orchestrating-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 ../orchestrating-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. connecting-datacloud でコネクタを作成します
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 が正常な状態になったら、harmonizing-datacloud に引き継ぎます。

---

特に注意すべき点

• CRM を基盤とするストリームの動作は、完全なカスタムコネクターフレームワークによる取り込みとは異なります。
• sf data360 data-stream run と sf data360 connection run-existing は互換性がありません。非構造化データの再スキャンには、ストリームレベルの更新を優先してください。
• SFDC ストリームはプラットフォーム管理のスケジュールで同期されます。data-stream run は、CRM コネクター更新の一般的な制御方法ではありません。
• 外部データベースコネクターの中には、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
• ../orchestrating-datacloud/assets/definitions/data-stream.template.json
• ../orchestrating-datacloud/references/plugin-setup.md
• ../orchestrating-datacloud/references/feature-readiness.md