关于Create an Ad Campaign API请求体values数组字段的技术问询

1. values数组的作用 #

values数组是承载广告实体结构化自定义属性的核心容器，用于传递广告配置中各类细分字段（如创意素材参数、定向规则、预算设置等）。由于不同类型广告的配置项差异较大，数组形式可以灵活适配多组键值对，避免固定请求体结构无法覆盖复杂的广告配置场景。

2. 各字段传入规则 #

• id：
  • 作用：标识单条属性项的唯一ID，用于后续更新、删除属性时精准定位
  • 规则：支持字符串或数字类型；新增广告时可省略（由后端自动生成），更新广告时需传入已存在的属性ID；同一请求内不能重复
• blockName：
  • 作用：对属性进行分组管理，将同类型的字段归类（如创意、定向、预算）
  • 规则：必填项，字符串类型，仅允许包含字母、下划线、连字符，长度不超过64字符；需匹配后端预设的分组枚举值（如creative_settings、targeting_rules、budget_settings），不能自定义未约定的分组名
• fieldName：
  • 作用：指定分组内的具体字段名
  • 规则：必填项，字符串类型；需与对应blockName下后端定义的合法字段名完全一致，不能随意自定义字段
• value：
  • 作用：字段的实际取值
  • 规则：必填项，类型需匹配fieldName定义的字段类型（如字符串、数字、数组、布尔值）；需符合字段的格式、长度限制（如图片URL需为合法HTTP/HTTPS链接，广告标题长度不超过30字符）

3. 完整示例代码 #

{
  "institutionId": "inst_897654",
  "adType": "banner_ad",
  "adStatus": "draft",
  "values": [
    {
      "id": "ad_attr_001",
      "blockName": "creative_settings",
      "fieldName": "ad_title",
      "value": "2024秋季新品首发 满300减50"
    },
    {
      "id": "ad_attr_002",
      "blockName": "creative_settings",
      "fieldName": "ad_thumbnail_url",
      "value": "https://your-domain.com/ad-assets/autumn-new.jpg"
    },
    {
      "id": "ad_attr_003",
      "blockName": "targeting_rules",
      "fieldName": "gender",
      "value": "female"
    },
    {
      "id": "ad_attr_004",
      "blockName": "targeting_rules",
      "fieldName": "interest_tags",
      "value": ["fashion", "autumn_wear", "online_shopping"]
    },
    {
      "id": "ad_attr_005",
      "blockName": "budget_settings",
      "fieldName": "total_budget",
      "value": 20000
    },
    {
      "id": "ad_attr_006",
      "blockName": "budget_settings",
      "fieldName": "is_unlimited_budget",
      "value": false
    }
  ]
}

内容的提问来源于stack exchange，提问作者Prem Kumar