developing-datacloud-code-extension

developing-datacloud-code-extension スキル

概要

このスキルでは、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-codeextension
   

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 スキーマを検証する

getting-datacloud-schema スキルを使用して、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-codeextension
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 が存在することを確認し（getting-datacloud-schema スキルを使用）、スペルと __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 アクセスのみを許可します

他のスキルとの連携

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

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

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 からロールバックできます