元字段定义使用说明

元字段定义（Metafield definition）用于规定元字段的数据结构、数据类型与访问权限。写入元字段值之前，建议先创建元字段定义，以便在 SHOPLINE 商家后台展示和管理元字段定义。本文说明如何通过 REST Admin API 管理元字段定义。

什么是元字段定义​

元字段定义不等同于元字段值本身。元字段定义与元字段值的关系如下：

对象说明示例
元字段定义规定元字段的字段模型、数据类型和访问权限。为商品资源创建“产品简介”的元字段定义，并将数据类型设为 multi_line_text_field（多行文本）。
元字段值存储在具体资源实例上的实际数据。具体商品的“产品简介”实际内容。

元字段定义由以下核心字段组成：

参数名类型说明
owner_resourcestring元字段定义所归属的资源类型，如 products。
namespacestring元字段定义的命名空间，与 key 共同构成元字段定义的唯一标识。
keystring元字段定义在命名空间下的唯一标识符。仅支持字母、数字、连字符与下划线。
最小长度限制：3
最大长度限制：64
typestring元字段定义支持的数据类型，如 single_line_text_field、boolean。详情参见 数据类型。
namestring元字段定义的名称，用于在 SHOPLINE 商家后台展示。
最大长度限制：255
descriptionstring元字段定义的描述。
最大长度限制：255
access.adminstring元字段定义的访问权限，详情参见 访问权限。

适用场景​

以下场景建议创建元字段定义：

  • 需要长期维护，且数据类型和数据校验规则相对固定的扩展字段（如商品保养说明、合规标签）。

  • 需要在 SHOPLINE 商家后台中展示并由商家维护的扩展字段。

  • 需要限制元字段的访问和管理范围，例如仅允许创建该定义的应用访问和管理元字段。

管理元字段定义​

你可以通过 REST Admin API 创建、查询、更新和删除元字段定义。

前置条件​

在开始调用 REST Admin API 前，确认你已具备以下条件：

  • 已创建应用，并完成店铺授权。

  • 已根据 应用授权 获取有效的 access token。

  • 已明确元字段定义所归属的资源类型（如 products、orders）和支持的数据类型。

访问权限​

在创建或更新元字段定义时，可以通过 access.admin 配置访问权限。各权限值的访问范围如下：

权限值创建该定义的应用SHOPLINE 商家后台其他应用
MERCHANT_READ_WRITE可管理元字段定义可管理元字段定义和元字段值不可读写
MERCHANT_READ可管理元字段定义仅可查看元字段定义，不可删除不可读写
PUBLIC_READ可管理元字段定义仅可查看元字段定义，不可删除只读
PRIVATE可通过 REST Admin API 管理元字段定义不支持查看不可读写
NONE可管理元字段定义可管理元字段定义和元字段值可读写

配置数据校验规则​

在创建或更新元字段定义时，可以通过 validations 根据数据类型配置相应的数据校验规则。数据校验规则用于约束允许写入元字段的值，避免无效或错误数据。validations 包含以下字段：

参数名类型说明示例
namestring数据校验规则的名称。枚举值为固定枚举，具体取值取决于元字段的数据类型。list.min
valuestring数据校验规则的值。2

完整规则名称、支持的数据类型、规则的值格式与校验方式参见 数据校验规则。

注意
  • 每个数据校验规则名称在同一元字段定义中最多出现一次。
  • 修改 validations 后，SHOPLINE 会异步扫描存量元字段值；不符合新规则的存量值会被标记为无效。
  • 更新元字段定义时，请求体中 validations 为空数组时表示清空数据校验规则。

创建元字段定义​

端点：POST /metafield_definition.json

为指定资源（owner_resource）创建元字段定义。接口详情参见 创建元字段定义。建议使用最新稳定版本。

请求示例​

curl --request POST 'https://{handle}.myshopline.com/admin/openapi/v20260901/metafield_definition.json' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "definition": {
      "owner_resource": "products",
      "namespace": "size_fields",
      "key": "size_label",
      "name": "Size label",
      "description": "Product size label",
      "type": "single_line_text_field",
      "validations": [
        {
          "name": "choices",
          "value": "[\"S\",\"M\",\"L\",\"XL\"]"
        }
      ]
    }
  }'

响应示例​

建议保存响应中的 id、key 和 namespace，供后续查询、更新与写入元字段值使用。

{
  "definition": {
    "id": 43601019606,
    "owner_resource": "products",
    "namespace": "size_fields",
    "key": "size_label",
    "name": "Size label",
    "description": "Product size label",
    "type": "single_line_text_field",
    "validations": [
      {
        "name": "choices",
        "value": "[\"S\",\"M\",\"L\",\"XL\"]"
      }
    ],
    "access": null,
    "created_at": "2025-04-15T16:21:03+08:00",
    "updated_at": "2025-04-15T16:21:03+08:00"
  }
}

查询元字段定义​

端点：GET /metafield_definition.json

根据元字段定义 ID 查询元字段定义详情。接口详情参见 查询元字段定义。建议使用最新稳定版本。

请求示例​

curl --request GET 'https://{handle}.myshopline.com/admin/openapi/v20260901/metafield_definition.json?id={definition_id}' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer {access_token}'

响应示例​

{
  "definition": {
    "id": 43601019606,
    "owner_resource": "products",
    "namespace": "size_fields",
    "key": "size_label",
    "name": "Size label",
    "description": "Product size label",
    "type": "single_line_text_field",
    "validations": [
      {
        "name": "choices",
        "value": "[\"S\",\"M\",\"L\",\"XL\"]"
      }
    ],
    "access": null,
    "created_at": "2025-04-15T16:21:03+08:00",
    "updated_at": "2025-04-15T16:21:03+08:00"
  }
}

更新元字段定义​

端点：PUT /metafield_definition.json

更新已有元字段定义的名称、描述和访问权限等信息。接口中非必填字段不传和传 null 则保留原值，传空字符串表示清空数据。接口详情参见 更新元字段定义。建议使用最新稳定版本。

请求示例​

curl --request PUT 'https://{handle}.myshopline.com/admin/openapi/v20260901/metafield_definition.json' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "definition": {
      "owner_resource": "products",
      "namespace": "size_fields",
      "key": "size_label",
      "name": "Size label",
      "description": "Updated description"
    }
  }'

响应示例​

{
  "definition": {
    "id": 43601019606,
    "owner_resource": "products",
    "namespace": "size_fields",
    "key": "size_label",
    "name": "Size label",
    "description": "Updated description",
    "type": "single_line_text_field",
    "validations": [
      {
        "name": "choices",
        "value": "[\"S\",\"M\",\"L\",\"XL\"]"
      }
    ],
    "access": null,
    "created_at": "2025-04-15T16:21:03+08:00",
    "updated_at": "2025-07-15T16:54:00+08:00"
  }
}

删除元字段定义​

端点：DELETE /metafield_definition.json

删除指定的元字段定义。接口详情参见 删除元字段定义。建议使用最新稳定版本。

注意

删除元字段定义可能影响线上数据与主题展示。生产环境操作前确认是否备份或迁移关联元字段值。

常见问题​

何时必须先创建元字段定义​

当你需要为元字段值配置数据校验规则、在 SHOPLINE 商家后台中展示和管理字段，或设置访问权限时，应先创建元字段定义。若仅需快速写入元字段值、且可接受未定义元字段的管理限制，可考虑使用 批量操作元字段 接口直接写入元字段值。

数据校验规则应在哪一步配置​

在创建或更新元字段定义时通过 validations 配置数据校验规则。写入元字段值时无需重复传入数据校验规则，系统会根据关联的元字段定义自动校验该值。

这篇文章对你有帮助吗？
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
条款协议
隐私
条款
开发者协议
LinkedInEmail
LinkedInEmail
© Copyright 2013-2026 SHOPLINE Limited.