data360-code-extension-generate

data360-code-extension-generate スキル

概要

このスキルでは、Salesforce Data Cloud 用のカスタム Python コード拡張機能を開発、テスト、デプロイするための完全なワークフローを提供します。コード拡張機能を使用すると、Data Lake オブジェクト（DLO）や Data Model オブジェクト（DMO）を読み書きする Python 変換処理を記述できます。

使用する場面

• 新しいコード拡張機能のプロジェクトを作成したい場合
• コード拡張機能をローカルでテストする必要がある場合
• 必要な権限をコードからスキャンしたい場合
• コード拡張機能を Data Cloud にデプロイする必要がある場合
• Data Cloud の変換処理を使用している場合
• DLO または DMO のデータをプログラムで読み書きしたい場合

前提条件の確認

コード拡張機能のコマンドを実行する前に、前提条件を確認してください。

1. プラグインがインストールされた SF CLI

   sf plugins --core | grep data-code-extension
   

   インストールされていない場合：

   sf plugins install @salesforce/plugin-data-code-extension
   

2. Python 3.11

   python --version  # Should show 3.11.x
   

3. Data Cloud Custom Code SDK

   pip list | grep salesforce-data-customcode
   

   インストールされていない場合：

   pip install salesforce-data-customcode
   

4. Docker が実行中であること（デプロイ時のみ）

   docker ps
   

5. 認証済みの組織

   sf org display --target-org <org_alias> --json
   

スキルのワークフロー

フェーズ 1：プロジェクトの初期化

ひな形を使って新しいコード拡張機能プロジェクトを作成します。

コマンド：

スクリプトベースのコード拡張機能（バッチ変換）の場合：

sf data-code-extension script init --package-dir <directory>

関数ベースのコード拡張機能（リアルタイム）の場合：

sf data-code-extension function init --package-dir <directory>

必須オプション：

• --package-dir, -p - パッケージを作成するディレクトリパス

作成されるもの：

my-transform/              # Project root
├── payload/               # CRITICAL: This is what --package-dir must point to for deploy
│   ├── entrypoint.py      # Main transformation code
│   └── config.json        # Code extension configuration
├── requirements.txt       # Python dependencies
└── README.md

ワークフロー中のディレクトリの指定

重要： ディレクトリ構造を理解することは、デプロイを成功させるうえで重要です。

コマンドと実行時に必要なディレクトリ：

コマンド	実行場所	パス／ファイル引数
init	親ディレクトリ	<project-name> または .
scan	プロジェクトルート	./payload/entrypoint.py
run	プロジェクトルート	./payload/entrypoint.py
deploy	プロジェクトルート	--package-dir ./payload（必須）

重要：deploy コマンドの --package-dir 引数には、プロジェクトルートではなく payload ディレクトリを指定する必要があります。

フェーズ 2：変換処理の開発

payload/entrypoint.py を編集して、変換ロジックを記述します。

スクリプトの例（バッチ）：

from datacustomcode import Client

client = Client()

# Read from DLO
df = client.read_dlo('Employee__dll')

# Transform data (uppercase position field)
df['position_upper'] = df['position'].str.upper()

# Write to output DLO
client.write_to_dlo('Employee_Upper__dll', df, 'overwrite')

関数の例（リアルタイム）：

from datacustomcode import FunctionClient

def transform(event, context):
    client = FunctionClient(context)
    input_data = event['data']
    output = {
        'name': input_data['name'].upper(),
        'status': 'processed'
    }
    return output

一般的な操作：

• client.read_dlo('DLO_Name__dll') - DLO から読み取る
• client.read_dmo('DMO_Name') - DMO から読み取る
• client.write_to_dlo('DLO_Name__dll', df, 'overwrite') - DLO に書き込む
• client.write_to_dmo('DMO_Name', df, 'upsert') - DMO に書き込む

フェーズ 3：権限のスキャン

エントリポイントファイルをスキャンして必要な権限を検出し、config.json を生成します。

コマンド：

sf data-code-extension script scan --entrypoint ./payload/entrypoint.py

検出される内容：

• DLO／DMO の読み取り権限
• DLO／DMO の書き込み権限
• Python パッケージの依存関係
• config.json と requirements.txt の更新

フェーズ 4：DLO スキーマの検証（テスト前の確認）

重要：ローカルでテストを実行する前に、コードで使用するすべての DLO が存在し、想定したフィールドを備えていることを確認してください。

ステップ 4a：config.json から DLO を抽出する

スキャン後、生成された config.json を確認し、すべての DLO を特定します。

cat payload/config.json

ステップ 4b：各 DLO のスキーマを検証する

data360-schema-get スキルを使って、DLO の存在とフィールド名を確認してください。

コードで参照している DLO ごとに、次の操作を行います。

1. DLO の存在を確認する：

   python3 scripts/get_dlo_schema.py <org_alias> <dlo_name>
   

2. フィールド名が一致することを確認する — entrypoint.py で使用しているフィールドと DLO スキーマを比較します。

3. すべての DLO を確認する：

   • read 権限に含まれるすべての DLO を検証する
   • write 権限に含まれるすべての DLO を検証する
   • フィールド名が完全に一致することを確認する（大文字と小文字を区別）
   • データ型が操作と互換性があることを確認する

ステップ 4c：検証チェックリスト

実行に進む前に、以下を確認してください。

• config.json に含まれるすべての DLO が対象組織に存在する
• コードで使用するすべてのフィールド名が DLO スキーマに存在する
• フィールドのデータ型が変換ロジックと一致している
• 主キーのフィールドが正しく特定されている
• 書き込み先の DLO が作成済みで、アクセス可能である

フェーズ 5：ローカルでテストする

DLO スキーマを検証したら、Data Cloud の組織に対してコード拡張機能をローカルで実行します。

コマンド：

sf data-code-extension script run --entrypoint <entrypoint_file> --target-org <org_alias> [options]

オプション：

• --target-org, -o - SF CLI の組織エイリアス（必須）
• --config-file, -c - カスタム設定ファイルのパス

エラーが発生した場合：

• DLO スキーマを再検証します
• フィールド名が完全に一致しているか確認します
• データ型に互換性があるか確認します
• フィールドや DLO に関する問題がないか、エラーメッセージを確認します

フェーズ 6：Data Cloud にデプロイする

スケジュール実行またはオンデマンド実行のために、コード拡張機能を Data Cloud にデプロイします。

重要：init で作成されたペイロードディレクトリを指定するには、必ず --package-dir ./payload を指定してください。

コマンド：

sf data-code-extension script deploy --target-org <org_alias> --name <name> --package-dir ./payload --package-version <version> --description <description> [options]

必須オプション：

• --target-org, -o - SF CLI の組織エイリアス
• --name, -n - コード拡張機能のデプロイ名
• --package-dir - ペイロードディレクトリへのパス（必須 - プロジェクトのルートから実行する場合は ./payload を指定する必要があります）
• --package-version - バージョン文字列（デフォルト：0.0.1）
• --description - コード拡張機能の説明

任意のオプション：

• --cpu-size - CPU サイズ：CPU_L、CPU_XL、CPU_2XL（デフォルト）、CPU_4XL
• --function-invoke-opt - 関数呼び出しオプション（関数タイプの場合）
• --network - Docker ネットワーク（デフォルト：default）

デプロイ後：

• Salesforce UI で Data Cloud に移動します
• Data Transforms セクションに移動します
• 名前でデプロイを検索します
• 「Run Now」をクリックして実行します
• 繰り返し実行するようスケジュールを設定します

エラー処理

よくある問題と解決策

エラー	解決策
command data-code-extension not found	sf plugins install @salesforce/plugin-data-code-extension
datacustomcode CLI not found	pip install salesforce-data-customcode
Python version mismatch	pyenv を使用します：pyenv install 3.11.0 && pyenv local 3.11.0
Cannot connect to Docker daemon	Docker Desktop を起動します
No org found for alias	sf org login web --alias <org_alias>
config.json not found	sf data-code-extension script scan --entrypoint ./payload/entrypoint.py
DLO not found	DLO が存在することを確認し（data360-schema-get スキルを使用）、スペルと __dll サフィックスを確認します
Permission denied writing	スキャンを再実行し、対象の DLO が存在し、書き込み可能であることを確認します
Deploy fails - wrong directory	--package-dir がプロジェクトのルートではなく、payload/ ディレクトリを指していることを確認します

ベストプラクティス

開発

1. テスト前に必ずスキャンします — コードを変更した後にスキャンを実行します
2. まずローカルでテストします — デプロイ前に run コマンドを使用します
3. バージョン管理を使用します — テストに成功するたびに git commit します
4. デプロイのバージョンを管理します — セマンティックバージョニング（1.0.0、1.1.0 など）を使用します
5. プロジェクトのルートから --package-dir ./payload を指定してデプロイします

パフォーマンス

• CPU_L：小規模データセット（< 100 万レコード）
• CPU_2XL：中規模データセット（100 万～1,000 万レコード）
• CPU_4XL：大規模データセット（> 1,000 万レコード）

セキュリティ

1. 認証情報をハードコードしないでください — SF CLI 認証のみを使用します
2. 入力データを検証します — null とデータ型を確認します
3. 書き込み権限を制限します — 必要な DLO/DMO アクセスのみを許可します

他のスキルとの連携

data360-schema-get スキルと併用します（検証に必須）：

コード拡張機能をテストする前に DLO を検証するには、data360-schema-get スキルが必須です。

Datakit ワークフローと併用します：

1. コード拡張機能で DLO を作成します
2. datakit ワークフローを使用して DLO を DMO にマッピングします
3. セグメントとアクティベーションで DMO を使用します

コマンドリファレンス

コマンド	目的	必須引数
script init	新しいスクリプトプロジェクトを作成する	--package-dir
function init	新しい関数プロジェクトを作成する	--package-dir
script scan	設定を生成する	エントリーポイントファイル
script run	ローカルでテストする	エントリーポイントファイル、--target-org
script deploy	Data Cloud にデプロイする	--target-org、--name、--package-dir、--package-version、--description

リソース

• SF CLI Plugin: https://github.com/salesforcecli/plugin-data-code-extension
• Python SDK: https://github.com/forcedotcom/datacloud-customcode-python-sdk
• Data Cloud ドキュメント: https://help.salesforce.com/s/articleView?id=sf.c360_a_intro.htm
• Python SDK PyPI: https://pypi.org/project/salesforce-data-customcode/

注意事項

• コード拡張機能は、分離された Python 3.11 環境で実行されます
• Docker が必要なのはデプロイ時のみで、ローカルテストには不要です
• SF CLI 認証のみを使用します（個別の認証情報ファイルは不要です）
• スキャンコマンドはコードから権限を自動検出します
• ローカル実行では、モックデータではなく実際の Data Cloud データを使用します
• デプロイにはバージョンが付与され、UI からロールバックできます