如何通过Shopify Admin GraphQL API为产品添加分类元字段？

问题概述 #

尝试通过Shopify Admin GraphQL API为产品（及其变体）添加分类专属元字段，但元字段无法创建。已尝试productSet、productCreate、metafieldsSet三种mutation，操作流程为：先通过产品分类法获取分类和属性，配置对应选项后作为产品分类元字段提交至Shopify，但操作失败。

核心问题排查与修复方案 #

1. 元字段type参数不符合规范 #

Shopify元字段的type必须使用官方定义的标准类型（例如single_line_text_field、multi_line_text_field、integer、boolean等），自定义字符串（如示例中的"asdas"）会直接导致创建失败。

2. 命名空间与Key格式校验 #

命名空间（namespace）和key仅允许包含小写字母、数字、下划线、连字符，且不能使用Shopify保留的命名空间（如shopify）。示例中的"adasd"格式合法，但需确认未使用保留命名空间。

3. productSet中metafields的结构正确性 #

确保C#代码序列化后，元字段的键名是namespace而非@namespace（C#中@是关键字转义符，序列化时需正确输出为"namespace"）。同时每个元字段必须包含namespace、key、value、type四个必填字段。

4. API权限验证 #

确认你的API密钥拥有write_products权限，无此权限将无法创建或修改产品元字段。

5. 变体元字段的单独配置 #

若要为变体添加元字段，需在variants数组的每个变体对象中单独定义metafields字段，而非放在产品层级的metafields中。

修正后的示例代码 #

// 修正元字段类型与结构
var metafields = new[]
{
    new
    {
        key = "category_attr",
        value = "your_category_value",
        type = "single_line_text_field", // 使用Shopify标准类型
        @namespace = "custom_category" // 自定义合法命名空间
    }
};

// 变体元字段示例（若需要为变体添加）
var variantsForMutation = new[]
{
    new
    {
        id = "gid://shopify/ProductVariant/123456",
        sku = "VAR-001",
        metafields = new[]
        {
            new
            {
                key = "variant_category_attr",
                value = "variant_value",
                type = "single_line_text_field",
                @namespace = "custom_category"
            }
        }
    }
};

var mutation = new
{
    query = @"mutation productSet($input: ProductSetInput!, $synchronous: Boolean!) {
        productSet(synchronous: $synchronous, input: $input) {
            product {
                id
                title
                totalInventory
                category{
                    name
                    fullName
                    id
                    isLeaf
                }
                variants(first: 250) {
                    nodes {
                        id
                        sku
                        inventoryItem {
                            id
                            tracked
                        }
                        metafields(first: 10) {
                            nodes {
                                key
                                value
                                namespace
                                type
                            }
                        }
                    }
                }
                metafields(first: 10) {
                    nodes {
                        key
                        value
                        namespace
                        type
                    }
                }
            }
            userErrors {
                field
                message
            }
        }
    }",
    variables = new
    {
        synchronous = true,
        input = new
        {
            title = mainProduct.Name,
            category = category.ShopifyId,
            descriptionHtml = mainProduct.Description,
            vendor = mainProduct.Brand?.Name ?? string.Empty,
            productType = category.Name,
            files = filesForMutation,
            productOptions,
            metafields,
            variants = variantsForMutation
        }
    }
};

额外调试建议 #

• 执行mutation后，务必查看返回的userErrors字段，其中会包含具体的错误原因（如类型不合法、权限不足等），这是定位问题的关键。
• 若使用metafieldsSet单独创建元字段，需确保传入正确的ownerId（产品或变体的GID）。

内容的提问来源于stack exchange，提问作者Kadir Emre Parlak