---
title: "查询元字段定义"
description: "通过元字段定义 ID 查询指定资源类型（如商品、订单）下的元字段定义。"
doc_type: openapi
doc_category: openapi
doc_version: v20260901
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/shopline-metafields/metafield-definition/get-a-metafield-definition'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/shopline-metafields/metafield-definition/get-a-metafield-definition.md'
---
# 查询元字段定义

通过元字段定义 ID 查询指定资源类型（如商品、订单）下的元字段定义。

- **Base URL:** `https://{handle}.myshopline.com/admin/openapi`
- **API Version:** v20260901
- **API Type:** Admin
- **API Protocol:** RESTful

## Endpoint

```http
GET /metafield_definition.json
```

## Base URL

* `https://{handle}.myshopline.com/admin/openapi`

  * `{handle}`: `handle` ：店铺的唯一标识符，值为店铺域名的前缀。例如，域名为 `open001.myshopline.com` 的店铺，其 `handle` 是 `open001` 。

## Request

### Query Parameters

* `id`

  string (required)

  元字段定义 ID。

### Request Headers

* `Content-Type`

  string (required)

  字段值固定为 `application/json; charset=utf-8`。

* `Authorization`

  string (required)

  资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。

## Response

### Status Codes

* `200`

  更多状态码信息，参考 [HTTP 状态码](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code.md?lang=zh-hans-cn)。

* `401`

  

* `429`

  

### Response Headers

* `traceId`

  请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。

### Response Body

#### 200

* `definition`

  object

  元字段定义。

  * `access`

    object

    元字段定义的权限信息。

    * `admin`

      string

      元字段定义的访问权限。有效枚举值包含：
      - `MERCHANT_READ_WRITE`：商家可读写
      - `MERCHANT_READ`：商家只读
      - `PUBLIC_READ`：公开可读
      - `PRIVATE`：仅限当前应用访问
      - `NONE`：未明确设置权限           

  * `created_at`

    string

    元字段定义创建的日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。

  * `description`

    string

    元字段定义的描述信息。    

  * `id`

    long

    元字段定义 ID。

  * `key`

    string

    元字段定义在其 `namespace` 下的唯一标识符。

  * `name`

    string

    元字段定义的名称。  

  * `namespace`

    string

    元字段定义的命名空间。

  * `owner_resource`

    string

    元字段定义所归属的资源类型。有效枚举值包含：  
    - `products`：商品 
    - `variants`：商品款式  
    - `collections`：商品分类
    - `customers`：客户
    - `orders`：订单
    - `pages`：页面  
    - `blogs`：博客集合
    - `articles`：博客文章
    - `shop`：店铺

  * `type`

    string

    元字段定义支持的数据类型，有效枚举值包含：
    
    - `single_line_text_field`：单个单行文本
    - ` list.single_line_text_field`：多个单行文本
    - `multi_line_text_field`：多行文本
    - `color`：单个颜色
    - `list.color`：多个颜色
    - `date`：单个日期
    - `list.date`：多个日期
    - `date_time`：单个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。
    - `list.date_time`：多个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。
    - `url`：单个 URL
    - `list.url`：多个 URL
    - `file_reference`：单个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。
    - `list.file_reference`：多个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。
    - `json`：JSON 类型
    - `weight`：单个重量，带单位
    - `list.weight`：多个重量，带单位
    - `volume`：单个体积，带单位
    - `list.volume`：多个体积，带单位
    - `dimension`：单个尺寸，带单位
    - `list.dimension`：多个尺寸，带单位
    - `number_integer`：单个整数
    - `list.number_integer`：多个整数
    - `number_decimal`：单个小数
    - `list.number_decimal`：多个小数
    - `rating`：单个等级
    - `list.rating`：多个等级
    - `page_reference`：单个页面
    - `list.page_reference`：多个页面
    - `product_reference`：单个商品
    - `list.product_reference`：多个商品
    - `variant_reference`：单个商品款式
    - `list.variant_reference`：多个商品款式
    - `collection_reference`：单个商品分类
    - `list.collection_reference`：多个商品分类
    - `boolean`：布尔类型，有效值包括 `true` 和 `false`。
    - `money`：资金，带币种单位    
        
    关于更多元字段信息，参考 [元字段功能使用指南](https://help.shopline.com/hc/zh-cn/articles/7095355017113)。              

  * `updated_at`

    string

    元字段定义更新的日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。

  * `validations`

    array<object>

    元字段定义下各元字段的数据校验规则。

    * `name`

      string

      数据校验规则的名称。

    * `value`

      string

      数据校验规则的值。


#### 401

* `errors`

  string

  错误描述。


#### 429

* `errors`

  string

  错误描述。


## OpenAPI Definition

```json
{
  "tags": [
    "查询元字段定义"
  ],
  "description": "通过元字段定义 ID 查询指定资源类型（如商品、订单）下的元字段定义。",
  "externalDocs": {
    "url": "",
    "errorTableDescription": "| Error Code | HTTP Status Code | Error Description |\n|------------|------------------|-------------------|\n| DATA_NOT_EXIST | 404 | The requested data does not exist. |\n| SUCCESS | 200 | request success |\n| ILLEGAL_PARAMS | 422 | illegal param |\n"
  },
  "operationId": "BCb1Gayh",
  "parameters": [
    {
      "name": "id",
      "in": "query",
      "description": "元字段定义 ID。",
      "required": true,
      "style": "form",
      "schema": {
        "name": "id",
        "description": "元字段定义 ID。",
        "type": "string",
        "example": "71351007083"
      },
      "example": "71351007083",
      "examples": {
        "查询元字段定义": {
          "value": "43601019606"
        }
      },
      "explode": true
    },
    {
      "name": "Content-Type",
      "in": "header",
      "description": "字段值固定为 `application/json; charset=utf-8`。",
      "required": true,
      "schema": {
        "name": "Content-Type",
        "type": "string",
        "example": "application/json; charset=utf-8"
      }
    },
    {
      "name": "Authorization",
      "in": "header",
      "description": "资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。",
      "required": true,
      "style": "string",
      "schema": {
        "name": "Authorization",
        "description": "资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。",
        "type": "string",
        "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA"
      },
      "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA"
    }
  ],
  "responses": {
    "200": {
      "description": "更多状态码信息，参考 [HTTP 状态码](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code.md?lang=zh-hans-cn)。",
      "headers": {
        "traceId": {
          "description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "name": "body",
            "type": "object",
            "properties": {
              "definition": {
                "name": "definition",
                "description": "元字段定义。",
                "type": "object",
                "properties": {
                  "access": {
                    "name": "access",
                    "description": "元字段定义的权限信息。",
                    "type": "object",
                    "properties": {
                      "admin": {
                        "name": "admin",
                        "description": "元字段定义的访问权限。有效枚举值包含：\n- `MERCHANT_READ_WRITE`：商家可读写\n- `MERCHANT_READ`：商家只读\n- `PUBLIC_READ`：公开可读\n- `PRIVATE`：仅限当前应用访问\n- `NONE`：未明确设置权限           ",
                        "type": "string"
                      }
                    },
                    "example": {
                      "admin": null
                    }
                  },
                  "created_at": {
                    "name": "created_at",
                    "description": "元字段定义创建的日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。",
                    "type": "string"
                  },
                  "description": {
                    "name": "description",
                    "description": "元字段定义的描述信息。    ",
                    "type": "string"
                  },
                  "id": {
                    "name": "id",
                    "description": "元字段定义 ID。",
                    "type": "long"
                  },
                  "key": {
                    "name": "key",
                    "description": "元字段定义在其 `namespace` 下的唯一标识符。",
                    "type": "string"
                  },
                  "name": {
                    "name": "name",
                    "description": "元字段定义的名称。  ",
                    "type": "string"
                  },
                  "namespace": {
                    "name": "namespace",
                    "description": "元字段定义的命名空间。",
                    "type": "string"
                  },
                  "owner_resource": {
                    "name": "owner_resource",
                    "description": "元字段定义所归属的资源类型。有效枚举值包含：  \n- `products`：商品 \n- `variants`：商品款式  \n- `collections`：商品分类\n- `customers`：客户\n- `orders`：订单\n- `pages`：页面  \n- `blogs`：博客集合\n- `articles`：博客文章\n- `shop`：店铺",
                    "type": "string"
                  },
                  "type": {
                    "name": "type",
                    "description": "元字段定义支持的数据类型，有效枚举值包含：\n\n- `single_line_text_field`：单个单行文本\n- ` list.single_line_text_field`：多个单行文本\n- `multi_line_text_field`：多行文本\n- `color`：单个颜色\n- `list.color`：多个颜色\n- `date`：单个日期\n- `list.date`：多个日期\n- `date_time`：单个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。\n- `list.date_time`：多个日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。\n- `url`：单个 URL\n- `list.url`：多个 URL\n- `file_reference`：单个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。\n- `list.file_reference`：多个文件，支持 10M 以内的 PDF 和图片文件，图片支持 JPG、JPEG、PNG 和 GIF 格式。\n- `json`：JSON 类型\n- `weight`：单个重量，带单位\n- `list.weight`：多个重量，带单位\n- `volume`：单个体积，带单位\n- `list.volume`：多个体积，带单位\n- `dimension`：单个尺寸，带单位\n- `list.dimension`：多个尺寸，带单位\n- `number_integer`：单个整数\n- `list.number_integer`：多个整数\n- `number_decimal`：单个小数\n- `list.number_decimal`：多个小数\n- `rating`：单个等级\n- `list.rating`：多个等级\n- `page_reference`：单个页面\n- `list.page_reference`：多个页面\n- `product_reference`：单个商品\n- `list.product_reference`：多个商品\n- `variant_reference`：单个商品款式\n- `list.variant_reference`：多个商品款式\n- `collection_reference`：单个商品分类\n- `list.collection_reference`：多个商品分类\n- `boolean`：布尔类型，有效值包括 `true` 和 `false`。\n- `money`：资金，带币种单位    \n    \n关于更多元字段信息，参考 [元字段功能使用指南](https://help.shopline.com/hc/zh-cn/articles/7095355017113)。              ",
                    "type": "string"
                  },
                  "updated_at": {
                    "name": "updated_at",
                    "description": "元字段定义更新的日期和时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。",
                    "type": "string"
                  },
                  "validations": {
                    "name": "validations",
                    "description": "元字段定义下各元字段的数据校验规则。",
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "name": "name",
                          "description": "数据校验规则的名称。",
                          "type": "string"
                        },
                        "value": {
                          "name": "value",
                          "description": "数据校验规则的值。",
                          "type": "string"
                        }
                      },
                      "example": {
                        "name": null,
                        "value": null
                      }
                    }
                  }
                },
                "example": {
                  "access": {
                    "admin": null
                  },
                  "created_at": null,
                  "description": null,
                  "id": null,
                  "key": null,
                  "name": null,
                  "namespace": null,
                  "owner_resource": null,
                  "type": null,
                  "updated_at": null,
                  "validations": null
                }
              }
            },
            "example": {
              "definition": {
                "access": {
                  "admin": null
                },
                "created_at": null,
                "description": null,
                "id": null,
                "key": null,
                "name": null,
                "namespace": null,
                "owner_resource": null,
                "type": null,
                "updated_at": null,
                "validations": null
              }
            }
          },
          "examples": {
            "查询元字段定义": {
              "description": "查询元字段定义",
              "value": {
                "definition": {
                  "access": null,
                  "created_at": "2025-04-15T16:21:03+08:00",
                  "description": "Product size label",
                  "id": 43601019606,
                  "key": "size_label",
                  "name": "Size label",
                  "namespace": "size_fields",
                  "owner_resource": "products",
                  "type": "single_line_text_field",
                  "updated_at": "2025-04-15T16:21:03+08:00",
                  "validations": [
                    {
                      "name": "choices",
                      "value": "[\"S\",\"M\",\"L\",\"XL\"]"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "headers": {
        "traceId": {
          "description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "errors": {
                "description": "错误描述。",
                "type": "string"
              }
            },
            "required": [
              "errors"
            ]
          }
        }
      }
    },
    "429": {
      "headers": {
        "traceId": {
          "description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "errors": {
                "description": "错误描述。",
                "type": "string"
              }
            },
            "required": [
              "errors"
            ]
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": []
    }
  ],
  "method": "get",
  "path": "/metafield_definition.json",
  "servers": [
    {
      "url": "https://{handle}.myshopline.com/admin/openapi",
      "variables": {
        "handle": {
          "default": "openapiceshidianpu",
          "description": "`handle` ：店铺的唯一标识符，值为店铺域名的前缀。例如，域名为 `open001.myshopline.com` 的店铺，其 `handle` 是 `open001` 。"
        }
      }
    }
  ],
  "info": {
    "title": "查询元字段定义",
    "version": "v20260901"
  }
}
```