data360-code-extension-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

data360-code-extension-generate Skill

data360-code-extension-generate 技能

Overview

概述

This skill provides a complete workflow for developing, testing, and deploying custom Python code extensions to Salesforce Data Cloud. Code extensions allow you to write Python transformations that read from and write to Data Lake Objects (DLOs) and Data Model Objects (DMOs).

此技能为开发、测试并将自定义Python代码扩展部署至Salesforce Data Cloud提供完整工作流。代码扩展允许你编写Python转换逻辑，读取和写入数据湖对象（DLOs）与数据模型对象（DMOs）。

When to Use

使用场景

User wants to create a new code extension project
User needs to test a code extension locally
User wants to scan code for required permissions
User needs to deploy a code extension to Data Cloud
User is working with Data Cloud transformations
User wants to read/write DLO or DMO data programmatically

用户想要创建新的代码扩展项目
用户需要在本地测试代码扩展
用户想要扫描代码以检查所需权限
用户需要将代码扩展部署至Data Cloud
用户正在处理Data Cloud转换任务
用户想要以编程方式读取/写入DLO或DMO数据

Prerequisites Check

前置条件检查

Before executing any code extension commands, verify prerequisites:

SF CLI with plugin installed

bash

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

If not installed:

bash

sf plugins install @salesforce/plugin-data-codeextension

Python 3.11
bash
```
python --version  # Should show 3.11.x
```

Data Cloud Custom Code SDK

bash

pip list | grep salesforce-data-customcode

If not installed:

bash

pip install salesforce-data-customcode

Docker running (for deploy only)
bash
```
docker ps
```

Authenticated org

bash

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

执行任何代码扩展命令前，请验证以下前置条件：

已安装SF CLI及对应插件

bash

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

若未安装：

bash

sf plugins install @salesforce/plugin-data-codeextension

Python 3.11环境

bash

python --version  # 应显示3.11.x版本

Data Cloud自定义代码SDK

bash

pip list | grep salesforce-data-customcode

若未安装：

bash

pip install salesforce-data-customcode

Docker正在运行（仅部署时需要）
bash
```
docker ps
```

已认证的Salesforce组织

bash

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

Skill Workflow

技能工作流

Phase 1: Initialize Project

阶段1：初始化项目

Create a new code extension project with scaffolding.

Commands:

For script-based code extensions (batch transformations):

bash

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

For function-based code extensions (real-time):

bash

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

Required Option:

```
--package-dir, -p
```
- Directory path where the package will be created

What it creates:

text

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

创建带有脚手架的新代码扩展项目。

命令：

适用于脚本型代码扩展（批量转换）：

bash

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

适用于函数型代码扩展（实时处理）：

bash

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

必填选项：

```
--package-dir, -p
```
- 用于创建项目包的目录路径

生成的目录结构：

text

my-transform/              # 项目根目录
├── payload/               # 关键：部署时--package-dir必须指向此目录
│   ├── entrypoint.py      # 主转换代码文件
│   └── config.json        # 代码扩展配置文件
├── requirements.txt       # Python依赖声明
└── README.md

Directory Context During Workflow

工作流中的目录上下文

IMPORTANT: Understanding the directory structure is critical for successful deployment.

Commands and their directory requirements:

Command	Run From	Path/File Argument
`init`	Parent directory	`<project-name>` or `.`
`scan`	Project root	`./payload/entrypoint.py`
`run`	Project root	`./payload/entrypoint.py`
`deploy`	Project root	`--package-dir ./payload` (REQUIRED)

CRITICAL: The
--package-dir
argument in deploy command MUST point to the
payload
directory, not the project root.

重要提示： 理解目录结构对成功部署至关重要。

命令及其目录要求：

命令	运行目录	路径/文件参数
`init`	父级目录	`<project-name>` 或 `.`
`scan`	项目根目录	`./payload/entrypoint.py`
`run`	项目根目录	`./payload/entrypoint.py`
`deploy`	项目根目录	`--package-dir ./payload` （必填）

关键注意事项： deploy命令中的

--package-dir

参数必须指向

payload

Phase 2: Develop Transformation

阶段2：开发转换逻辑

Edit

payload/entrypoint.py

with transformation logic.

Script Example (Batch):

python

from datacustomcode import Client

client = Client()

编辑

payload/entrypoint.py

文件，编写自定义转换逻辑。

脚本示例（批量处理）：

python

from datacustomcode import Client

client = Client()

Read from DLO

从DLO读取数据

df = client.read_dlo('Employee__dll')

Transform data (uppercase position field)

转换数据（职位字段转为大写）

df['position_upper'] = df['position'].str.upper()

Write to output DLO

将数据写入输出DLO

client.write_to_dlo('Employee_Upper__dll', df, 'overwrite')


**Function Example (Real-time):**
```python
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

Common Operations:

```
client.read_dlo('DLO_Name__dll')
```
- Read from DLO
```
client.read_dmo('DMO_Name')
```
- Read from DMO

client.write_to_dlo('DLO_Name__dll', df, 'overwrite')

- Write to DLO

client.write_to_dmo('DMO_Name', df, 'upsert')

- Write to DMO

client.write_to_dlo('Employee_Upper__dll', df, 'overwrite')


**函数示例（实时处理）：**
```python
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

Phase 3: Scan for Permissions

阶段3：权限扫描

Scan the entrypoint file to detect required permissions and generate config.json.

Command:

bash

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

What it detects:

Read permissions for DLOs/DMOs
Write permissions for DLOs/DMOs
Python package dependencies
Updates
```
config.json
```
and
```
requirements.txt
```

扫描入口文件以检测所需权限并生成config.json配置文件。

命令：

bash

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

扫描内容：

DLO/DMO的读取权限
DLO/DMO的写入权限
Python包依赖
更新
```
config.json
```
和
```
requirements.txt
```
文件

Phase 4: Validate DLO Schema (Pre-Test Check)

阶段4：验证DLO Schema（测试前检查）

CRITICAL: Before running tests locally, validate that all DLOs used in your code exist and have the expected fields.

关键注意事项： 在本地运行测试前，请验证代码中使用的所有DLO是否存在且包含预期字段。

Step 4a: Extract DLOs from config.json

步骤4a：从config.json提取DLO信息

After scanning, review the generated

config.json

to identify all DLOs:

bash

cat payload/config.json

扫描完成后，查看生成的

config.json

文件以确认所有涉及的DLO：

bash

cat payload/config.json

Step 4b: Validate Each DLO Schema

步骤4b：验证每个DLO的Schema

Use the
data360-schema-get
skill to verify DLOs exist and check field names.

For each DLO referenced in your code:

Verify DLO exists:

bash

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

Verify field names match — compare fields used in your
```
entrypoint.py
```
against the DLO schema.
Check all DLOs:
- Validate all DLOs in
```
read
```
  permissions
- Validate all DLOs in
```
write
```
  permissions
- Check field names match exactly (case-sensitive)
- Verify data types are compatible with operations

使用
data360-schema-get
技能验证DLO是否存在并检查字段名称。

针对代码中引用的每个DLO：

验证DLO存在：

bash

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

验证字段名称匹配 — 将
```
entrypoint.py
```
中使用的字段与DLO Schema进行对比。
检查所有DLO：
- 验证
```
read
```
  权限中的所有DLO
- 验证
```
write
```
  权限中的所有DLO
- 检查字段名称是否完全匹配（区分大小写）
- 验证数据类型与操作兼容

Step 4c: Validation Checklist

步骤4c：验证清单

Phase 5: Test Locally

阶段5：本地测试

After validating DLO schemas, run the code extension locally against your Data Cloud org.

Command:

bash

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

Options:

```
--target-org, -o
```
- SF CLI org alias (required)
```
--config-file, -c
```
- Custom config file path

If you get errors:

Re-validate DLO schemas
Check field names are exact matches
Verify data types are compatible
Review error messages for field/DLO issues

验证DLO Schema后，在本地针对你的Data Cloud组织运行代码扩展。

命令：

bash

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

可选参数：

```
--target-org, -o
```
- SF CLI组织别名（必填）
```
--config-file, -c
```
- 自定义配置文件路径

若出现错误：

重新验证DLO Schema
检查字段名称是否完全匹配
验证数据类型是否兼容
根据错误信息排查字段/DLO相关问题

Phase 6: Deploy to Data Cloud

阶段6：部署至Data Cloud

Deploy the code extension to Data Cloud for scheduled or on-demand execution.

CRITICAL: You MUST specify
--package-dir ./payload
to point to the payload directory created by init.

Command:

bash

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

Required Options:

```
--target-org, -o
```
- SF CLI org alias
```
--name, -n
```
- Name for code extension deployment
```
--package-dir
```
- Path to payload directory (REQUIRED - must be
```
./payload
```
when running from project root)
```
--package-version
```
- Version string (default: 0.0.1)
```
--description
```
- Description of code extension

Optional Options:

```
--cpu-size
```
- CPU size: CPU_L, CPU_XL, CPU_2XL (default), CPU_4XL
```
--function-invoke-opt
```
- Function invoke options (for function type)
```
--network
```
- Docker network (default: default)

After deployment:

Navigate to Data Cloud in Salesforce UI
Go to Data Transforms section
Find your deployment by name
Click "Run Now" to execute
Schedule for recurring execution

将代码扩展部署至Data Cloud，用于定时或按需执行。

关键注意事项： 你必须指定

--package-dir ./payload

以指向init命令生成的payload目录。

命令：

bash

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目录路径（必填 - 在项目根目录运行时必须为
```
./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）区域
通过名称查找你的部署
点击“立即运行”执行
设置定时任务以重复执行

Error Handling

错误处理

Common Issues and Solutions

常见问题及解决方案

Error	Solution
`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`	Use pyenv: `pyenv install 3.11.0 && pyenv local 3.11.0`
`Cannot connect to Docker daemon`	Start 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`	Verify DLO exists (use data360-schema-get skill), check spelling and `__dll` suffix
`Permission denied writing`	Re-run scan, verify target DLO exists and is writable
`Deploy fails - wrong directory`	Ensure `--package-dir` points to `payload/` directory, not project root

错误信息	解决方案
`command data-code-extension not found`	执行 `sf plugins install @salesforce/plugin-data-codeextension` 安装插件
`datacustomcode CLI not found`	执行 `pip install salesforce-data-customcode` 安装SDK
`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/` 目录，而非项目根目录

Best Practices

最佳实践

Development

开发环节

Always scan before testing — run scan after code changes
Test locally first — use
```
run
```
command before deploying
Use version control — git commit after each successful test
Version your deployments — use semantic versioning (1.0.0, 1.1.0, etc.)
Deploy from project root with
```
--package-dir ./payload
```

测试前务必扫描——代码变更后重新执行扫描
先在本地测试——部署前使用
```
run
```
命令验证
使用版本控制——每次测试成功后提交git
为部署版本编号——使用语义化版本（如1.0.0、1.1.0等）
在项目根目录执行部署并指定
```
--package-dir ./payload
```

Performance

性能优化

CPU_L: Small datasets (< 1M records)
CPU_2XL: Medium datasets (1M-10M records)
CPU_4XL: Large datasets (> 10M records)

CPU_L：小型数据集（<100万条记录）
CPU_2XL：中型数据集（100万-1000万条记录）
CPU_4XL：大型数据集（>1000万条记录）

Security

安全规范

No hardcoded credentials — use SF CLI authentication only
Validate input data — check for nulls and data types
Limit write permissions — only grant necessary DLO/DMO access

禁止硬编码凭证——仅使用SF CLI认证
验证输入数据——检查空值及数据类型
限制写入权限——仅授予必要的DLO/DMO访问权限

Integration with Other Skills

与其他技能的集成

Use with data360-schema-get skill (CRITICAL for validation):

The

data360-schema-get

skill is required for validating DLOs before testing code extensions.

Use with Datakit Workflow:

Create DLO via code extension
Map DLO to DMO using datakit workflow
Use DMO in segments and activations

与data360-schema-get技能配合使用（验证环节必备）：

data360-schema-get

技能是测试代码扩展前验证DLO的必备工具。

与Datakit工作流配合使用：

通过代码扩展创建DLO
使用datakit工作流将DLO映射至DMO
在细分和激活环节使用DMO

Command Reference

命令参考

Command	Purpose	Required Args
`script init`	Create new script project	--package-dir
`function init`	Create new function project	--package-dir
`script scan`	Generate config	entrypoint file
`script run`	Test locally	entrypoint file, --target-org
`script deploy`	Deploy to Data Cloud	--target-org, --name, --package-dir, --package-version, --description

命令	用途	必填参数
`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

Resources

参考资源

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

SF CLI插件：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/

Notes

注意事项

Code extensions run in isolated Python 3.11 environment
Docker is required only for deployment, not for local testing
Use SF CLI authentication only (no separate credential files)
Scan command auto-detects permissions from code
Local run uses actual Data Cloud data (not mocked)
Deployments are versioned and can be rolled back in UI

代码扩展运行在独立的Python 3.11环境中
Docker仅在部署时需要，本地测试无需Docker
仅使用SF CLI认证（无需单独的凭证文件）
扫描命令会自动从代码中检测所需权限
本地运行使用真实的Data Cloud数据（非模拟数据）
部署版本可在UI中回滚