mcpField
B
b2c-metadata

b2c-metadata

github.com/salesforcecommercecloud开发5793 次安装今天更新
代码仓库

关于 b2c-metadata

b2c-metadata 面向处理 Salesforce B2C Commerce 站点元数据 XML 的开发者，涵盖系统对象扩展、自定义对象和站点偏好设置，并建议通过权威文档核实版本相关的架构与 API。

主要功能

  1. 01说明元数据 XML 文件结构
  2. 02定义系统对象自定义属性
  3. 03介绍自定义对象定义
  4. 04配置站点偏好设置
  5. 05依据权威文档核对版本相关细节

适用场景

  1. 01为商品或订单添加属性
  2. 02创建自定义数据对象定义
  3. 03设置站点专属配置值
  4. 04核对元数据架构和 API 详情

MCP 相关

该技能建议使用 `b2c docs search` 与 `b2c docs read`，或通过 MCP 使用 `docs_search` 和 `docs_read`，核实当前架构及 API 细节。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/salesforcecommercecloud/b2c-developer-tooling --skill b2c-metadata

安装后在 Claude Code 中输入/b2c-metadata确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
trigger-evals.json
references/
SYSTEM-OBJECTS.md
XML-EXAMPLES.md

详细介绍

Metadata 技能

本技能将指导你处理 Salesforce B2C Commerce 的站点元数据 XML，包括自定义属性、自定义对象和站点首选项。

范围与依据

本技能涵盖 B2C Commerce 元数据 XML 系统（metadata.xsd 命名空间 http://www.demandware.com/xml/impex/metadata/2006-10-31），包括 system-objecttype-extensions.xml、custom-objecttype-definitions.xml 和 preferences.xml 文件结构。示例展示了属性类型、枚举值模式，以及通过 dw.system.Site 和 ExtensibleObject.custom 使用 Script API 访问自定义属性的方法。在回答涉及特定 B2C 版本、XSD 架构约束，或生成用户将运行的代码的问题之前，请通过 b2c docs search 和 b2c docs read（CLI）或 docs_search/docs_read（MCP）确认当前 API 结构和架构规则。权威的 B2C Commerce 文档是了解元数据架构演进、Script API 签名和平台对象类型的依据。

权威文档：

  • metadata - 元数据 XML 架构和结构
  • dw.system.Site - 用于站点首选项的 Script API
  • dw.system.SitePreferences - 用于访问站点首选项的 Script API
  • dw.object.CustomAttributes - 用于访问自定义属性的 Script API
  • b2c-commerce/b2c-create-impex-folder-structure-ds - 站点归档文件夹结构
  • b2c-commerce/b2c-exporting-active-data - 导出指南
  • b2c-commerce/creatingcustombusinessobjectswithdemandwarebusinessmanager - 自定义对象创建
  • b2c-commerce/b2c-business-manager-extension-points - Business Manager 扩展点

概述

元数据定义 B2C Commerce 数据的结构：

元数据类型用途
系统对象扩展为 Product、Order、Customer 等添加自定义属性
自定义对象定义全新的数据类型
站点首选项站点特定的配置值

站点归档结构

元数据按站点归档组织：

/site-archive
    /meta
        system-objecttype-extensions.xml    # Custom attributes on system objects
        custom-objecttype-definitions.xml   # Custom object definitions
    /sites
        /MySite
            preferences.xml                 # Site preferences

系统对象扩展

为现有系统对象添加自定义属性。

基本结构
<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="Product">
        <custom-attribute-definitions>
            <attribute-definition attribute-id="myCustomAttribute">
                <display-name xml:lang="x-default">My Custom Attribute</display-name>
                <type>string</type>
                <mandatory-flag>false</mandatory-flag>
                <externally-managed-flag>false</externally-managed-flag>
            </attribute-definition>
        </custom-attribute-definitions>
        <group-definitions>
            <attribute-group group-id="MyCustomGroup">
                <display-name xml:lang="x-default">My Custom Group</display-name>
                <attribute attribute-id="myCustomAttribute"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>
常见系统对象

示例列表；请通过 b2c docs read b2c-commerce/creatingcustombusinessobjectswithdemandwarebusinessmanager 和 Business Manager 对象参考确认当前平台对象类型。

对象类型用例
Product商品属性
Order订单元数据
Profile客户档案数据
Basket购物车数据
SitePreferences站点配置
Category类目属性
Content内容资源属性

有关更多类型，请参阅系统对象参考。可扩展系统对象的完整集合由 B2C 平台定义；请查阅 Business Manager 和官方文档，了解特定版本的可用性。

属性类型

根据 metadata.xsd 的 simpleType.AttributeType 定义；请通过 b2c docs schema metadata 确认当前架构。

类型描述示例
string文本（最多 4000 个字符）SKU、描述
text长文本（不限长度）富内容
int整数数量、排名
double小数百分比、重量
booleantrue/false标志
date仅日期出生日期
datetime日期和时间时间戳
email电子邮件地址联系邮箱
password加密API 密钥
htmlHTML 内容富文本
enum-of-string单选状态
enum-of-int数值枚举优先级
set-of-string多选标签
set-of-int数值多选类目
image图像引用缩略图
枚举值定义

展示枚举结构；请使用 b2c docs schema metadata 确认当前架构的排序约束。

枚举类型（enum-of-string、enum-of-int、set-of-string、set-of-int）需要 value-definitions，其中包含显示值对：

元素顺序很重要。 metadata.xsd 架构要求每个 <value-definition> 中的 <display> 必须位于 <value> 之前；请参阅 b2c docs schema metadata 了解当前架构约束。

<attribute-definition attribute-id="warrantyType">
    <display-name xml:lang="x-default">Warranty Type</display-name>
    <type>enum-of-string</type>
    <mandatory-flag>false</mandatory-flag>
    <value-definitions>
        <value-definition>
            <display xml:lang="x-default">No Warranty</display>
            <value>none</value>
        </value-definition>
        <value-definition>
            <display xml:lang="x-default">Limited Warranty</display>
            <value>limited</value>
        </value-definition>
        <value-definition>
            <display xml:lang="x-default">Full Warranty</display>
            <value>full</value>
        </value-definition>
    </value-definitions>
</attribute-definition>
元素用途
<display>在 Business Manager 中显示的易读标签（必须放在首位）
<value>存储/API 值（使用小写字母，不含空格）

产品自定义属性示例

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="Product">
        <custom-attribute-definitions>
            
            <attribute-definition attribute-id="vendorSKU">
                <display-name xml:lang="x-default">Vendor SKU</display-name>
                <type>string</type>
                <mandatory-flag>false</mandatory-flag>
                <externally-managed-flag>true</externally-managed-flag>
            </attribute-definition>

            
            <attribute-definition attribute-id="productCondition">
                <display-name xml:lang="x-default">Product Condition</display-name>
                <type>enum-of-string</type>
                <mandatory-flag>false</mandatory-flag>
                <value-definitions>
                    <value-definition>
                        <display xml:lang="x-default">New</display>
                        <value>new</value>
                    </value-definition>
                    <value-definition>
                        <display xml:lang="x-default">Refurbished</display>
                        <value>refurbished</value>
                    </value-definition>
                    <value-definition>
                        <display xml:lang="x-default">Used</display>
                        <value>used</value>
                    </value-definition>
                </value-definitions>
            </attribute-definition>

            
            <attribute-definition attribute-id="isHazardous">
                <display-name xml:lang="x-default">Hazardous Material</display-name>
                <type>boolean</type>
                <mandatory-flag>false</mandatory-flag>
                <default-value>false</default-value>
            </attribute-definition>

            
            <attribute-definition attribute-id="productFeatures">
                <display-name xml:lang="x-default">Product Features</display-name>
                <type>set-of-string</type>
                <mandatory-flag>false</mandatory-flag>
                <value-definitions>
                    <value-definition>
                        <display xml:lang="x-default">Waterproof</display>
                        <value>waterproof</value>
                    </value-definition>
                    <value-definition>
                        <display xml:lang="x-default">Recyclable</display>
                        <value>recyclable</value>
                    </value-definition>
                </value-definitions>
            </attribute-definition>
        </custom-attribute-definitions>

        <group-definitions>
            <attribute-group group-id="CustomProductInfo">
                <display-name xml:lang="x-default">Custom Product Information</display-name>
                <attribute attribute-id="vendorSKU"/>
                <attribute attribute-id="productCondition"/>
                <attribute attribute-id="isHazardous"/>
                <attribute attribute-id="productFeatures"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>

自定义对象定义

创建全新的数据类型。

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <custom-type type-id="StoreLocations">
        <display-name xml:lang="x-default">Store Locations</display-name>
        <description xml:lang="x-default">Physical store information</description>
        <staging-mode>source-to-target</staging-mode>
        <storage-scope>site</storage-scope>
        <key-definition attribute-id="storeId">
            <display-name xml:lang="x-default">Store ID</display-name>
            <type>string</type>
            <min-length>1</min-length>
        </key-definition>
        <attribute-definitions>
            <attribute-definition attribute-id="storeName">
                <display-name xml:lang="x-default">Store Name</display-name>
                <type>string</type>
                <mandatory-flag>true</mandatory-flag>
            </attribute-definition>
            <attribute-definition attribute-id="latitude">
                <display-name xml:lang="x-default">Latitude</display-name>
                <type>double</type>
            </attribute-definition>
            <attribute-definition attribute-id="longitude">
                <display-name xml:lang="x-default">Longitude</display-name>
                <type>double</type>
            </attribute-definition>
            <attribute-definition attribute-id="phone">
                <display-name xml:lang="x-default">Phone</display-name>
                <type>string</type>
            </attribute-definition>
            <attribute-definition attribute-id="isActive">
                <display-name xml:lang="x-default">Active</display-name>
                <type>boolean</type>
                <default-value>true</default-value>
            </attribute-definition>
        </attribute-definitions>
        <group-definitions>
            <attribute-group group-id="StoreInfo">
                <display-name xml:lang="x-default">Store Information</display-name>
                <attribute attribute-id="storeId" system="true"/>
                <attribute attribute-id="storeName"/>
                <attribute attribute-id="latitude"/>
                <attribute attribute-id="longitude"/>
                <attribute attribute-id="phone"/>
                <attribute attribute-id="isActive"/>
            </attribute-group>
        </group-definitions>
    </custom-type>
</metadata>

站点首选项

通过 SitePreferences 上的自定义属性进行站点特定配置。

元数据（system-objecttype-extensions.xml）
<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="SitePreferences">
        <custom-attribute-definitions>
            <attribute-definition attribute-id="enableFeatureX">
                <display-name xml:lang="x-default">Enable Feature X</display-name>
                <type>boolean</type>
                <default-value>false</default-value>
            </attribute-definition>
            <attribute-definition attribute-id="apiEndpoint">
                <display-name xml:lang="x-default">API Endpoint</display-name>
                <type>string</type>
            </attribute-definition>
            <attribute-definition attribute-id="maxItemsPerPage">
                <display-name xml:lang="x-default">Max Items Per Page</display-name>
                <type>int</type>
                <default-value>20</default-value>
            </attribute-definition>
        </custom-attribute-definitions>
        <group-definitions>
            <attribute-group group-id="CustomSettings">
                <display-name xml:lang="x-default">Custom Settings</display-name>
                <attribute attribute-id="enableFeatureX"/>
                <attribute attribute-id="apiEndpoint"/>
                <attribute attribute-id="maxItemsPerPage"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>
值（sites/MySite/preferences.xml）

可按实例类型（development、staging、production）设置首选项，也可为所有实例设置：

<?xml version="1.0" encoding="UTF-8"?>
<preferences xmlns="http://www.demandware.com/xml/impex/preferences/2007-03-31">
    <custom-preferences>
        <all-instances>
            
            <preference preference-id="maxItemsPerPage">25</preference>
        </all-instances>
        <development>
            
            <preference preference-id="enableFeatureX">true</preference>
            <preference preference-id="apiEndpoint">https://dev-api.example.com/v1</preference>
        </development>
        <staging>
            <preference preference-id="enableFeatureX">true</preference>
            <preference preference-id="apiEndpoint">https://staging-api.example.com/v1</preference>
        </staging>
        <production>
            <preference preference-id="enableFeatureX">false</preference>
            <preference preference-id="apiEndpoint">https://api.example.com/v1</preference>
        </production>
    </custom-preferences>
</preferences>
在代码中访问

示例代码；请使用 b2c docs read dw.system.Site 确认当前 API 签名和返回类型。

// See dw.system.Site Script API docs for full method signatures and return types
var Site = require('dw/system/Site');

var enableFeatureX = Site.current.getCustomPreferenceValue('enableFeatureX');
var apiEndpoint = Site.current.getCustomPreferenceValue('apiEndpoint');
var maxItems = Site.current.getCustomPreferenceValue('maxItemsPerPage');

属性定义选项

展示可用标志；请使用 b2c docs schema metadata 确认当前架构元素及其弃用状态。

<attribute-definition attribute-id="myAttribute">
    <display-name xml:lang="x-default">Display Name</display-name>
    <description xml:lang="x-default">Description for BM tooltip</description>
    <type>string</type>
    <localizable-flag>false</localizable-flag>
    <site-specific-flag>false</site-specific-flag>
    <mandatory-flag>false</mandatory-flag>
    <searchable-flag>false</searchable-flag>
    <visible-flag>true</visible-flag>
    <externally-managed-flag>false</externally-managed-flag>
    <order-required-flag>false</order-required-flag>
    <min-length>0</min-length>
    <field-length>256</field-length>
    <unit xml:lang="x-default">kg</unit>
    <default-value>default</default-value>
</attribute-definition>
标志用途
localizable-flag可按区域设置不同的值
mandatory-flag在 BM 中为必填项
externally-managed-flag在 BM 中为只读
visible-flag在 BM 中显示
site-specific-flag每个站点的值各不相同
order-required-flag订单导出时必需
searchable-flag为搜索建立索引（根据 metadata.xsd 已弃用——请改用 search2.xsd 中的 SearchableAttributes）

最佳实践

  1. 使用属性组在 Business Manager 中进行整理
  2. 为自定义属性添加前缀，使用组织名称（例如 acme_myAttribute）
  3. 对从外部系统导入的数据设置 externally-managed
  4. 对于受控词汇，优先使用枚举而非字符串
  5. 使用描述进行说明——它们会显示为工具提示

快速参考

权威文档请参阅上文的 Scope & Grounding 部分。以下文件是据此整理的快速参考摘要。

评论

支持 Markdown