跳转到主要内容

​
配置

cloudx config 命令用于检查、验证、编辑和发布 CloudX 中保存的库存配置。 可用命令：
  • cloudx config show：查看实时配置、已发布版本或草稿
  • cloudx config validate：验证本地 YAML 文件或远程配置
  • cloudx config edit：在草稿中准备应用、广告单元、广告单元组、列表、标签、测试设备、网络映射、订单项和 A/B 测试变更
  • cloudx config publish：将草稿发布为实时配置
  • cloudx config history：查看已发布配置历史和发布时的差异统计

​
cloudx config show

默认以 YAML 显示配置。 当您需要查看 CloudX 为某个账号保存的精确库存配置、对比已发布版本，或在发布前检查草稿时，请使用此命令。

​
用法

cloudx config show [flags]

​
寻址方式

默认情况下，config show 返回实时配置。 每次只能使用一种寻址方式：
方式说明
不传寻址标志显示实时配置。
--id <config-id>按稳定 ID 显示指定配置行。可指向已发布版本或草稿。
--version <number>显示账号内的已发布版本号。
--draft显示账号草稿。如存在多个草稿，请改用 --id。

​
标志

标志必需默认值说明
--id否稳定配置行 ID。
--version否已发布配置版本号。必须大于 0。
--draft否false显示当前账号草稿。
--with-metadata否false在输出中包含配置行元数据。
--json否false输出结构化 JSON，而不是默认 YAML。
验证规则：
  • --id、--version 和 --draft 只能使用一个。
  • --version 必须大于 0。

​
输出格式

默认情况下，命令只打印配置 YAML，不包含行元数据： 
cloudx config show
使用 --json 只输出原始配置数据 JSON： 
cloudx config show --version 12 --json
当需要 config ID、账号 ID、类型、版本号、创建时间、创建者元数据、YAML 和原始数据等字段时，使用 --with-metadata： 
cloudx config show --version 12 --with-metadata
cloudx config show --id cfg_123 --with-metadata --json

​
示例

显示实时配置 
cloudx config show
显示已发布版本 
cloudx config show --version 12
按 ID 显示配置 
cloudx config show --id cfg_123
显示带元数据的草稿 
cloudx config show --draft --with-metadata

​
cloudx config validate

验证本地 YAML 文件或远程配置。 在提交配置评审前、使用 cloudx config edit 创建草稿后，或需要面向自动化流程的 JSON 验证输出时，请使用此命令。

​
用法

cloudx config validate [file] [flags]

​
本地与远程验证

传入文件路径时，验证完全在本地运行，不会调用 API： 
cloudx config validate config.yaml
省略文件路径时，默认验证远程实时配置： 
cloudx config validate
使用 --id 验证指定配置行，包括由 config edit 创建的草稿；使用 --version 验证已发布版本： 
cloudx config validate --id draft_123
cloudx config validate --version 12

​
标志

标志必需默认值说明
file否要验证的本地 YAML 文件。省略时验证远程实时配置。
--id否要远程验证的稳定配置行 ID。
--version否要远程验证的已发布配置版本号。必须大于 0。
--strict否false存在验证警告时也以非零状态退出。
--json否false输出结构化 JSON，而不是人类可读输出。
验证规则：
  • 本地文件验证不支持 --id 或 --version。
  • 远程验证只支持 --id 和 --version 之一。
  • --version 必须大于 0。
  • 未使用 --strict 时，警告会显示但不会导致命令失败。
  • 使用 --strict 时，错误或警告都会让命令以非零状态退出。

​
示例

验证本地 YAML 文件 
cloudx config validate config.yaml
出现警告时失败 
cloudx config validate config.yaml --strict
验证实时配置 
cloudx config validate
验证草稿并输出 JSON 
cloudx config validate --id draft_123 --json
验证已发布版本 
cloudx config validate --version 12

​
cloudx config edit

在配置草稿中编辑库存。 大多数编辑命令只保存草稿，不会发布配置。默认情况下，CLI 会基于实时配置创建草稿。使用 --config-id 可原地编辑已有草稿，或将指定配置行复制成新的草稿后编辑。当草稿准备好上线时，请使用 cloudx config publish。 每次编辑后，CloudX 都会验证生成的草稿。默认的人类可读输出包含草稿 ID、草稿是新建还是更新、基础配置 ID、变更路径以及验证计数。如果验证发现问题，输出还会显示 cloudx config validate --id <draft-id> 命令，方便查看详情。 API 客户端可通过 POST /api/v1/config/edit 执行相同写入。该端点需要 configuration:write 权限，接收带类型的 operations 数组，并使用认证 API key 所属账号。 公共 CLI 和 API 写入面目前不提供级联删除。

​
命令

命令说明
cloudx config edit create-app / update-app / delete-app创建、修补或删除应用。
cloudx config edit create-ad-unit / update-ad-unit / delete-ad-unit创建、修补或删除广告单元。
cloudx config edit create-ad-unit-group / update-ad-unit-group / delete-ad-unit-group创建、替换成员或删除广告单元组。
cloudx config edit remove-ad-unit-from-group从广告单元组中移除一个广告单元。
cloudx config edit create-list / update-list / delete-list创建、修补或删除定向列表。
cloudx config edit create-tag / update-tag / delete-tag创建、修补或删除标签。
cloudx config edit upsert-test-device / delete-test-device创建、修补或删除应用测试设备。
cloudx config edit upsert-network-mapping / delete-network-mapping创建、修补或删除应用/广告单元网络映射。
cloudx config edit create-ab-test创建 A/B 测试草稿。
cloudx config edit update-ab-test / start-ab-test / end-ab-test / promote-ab-test / delete-ab-test修改 A/B 测试并发布生成的配置。
cloudx config edit create-line-item在配置草稿中创建订单项。
cloudx config edit update-line-item在配置草稿中修补已有订单项。
cloudx config edit delete-line-item从配置草稿中删除订单项。

​
共享标志

标志必需默认值说明
--config-id否要编辑的配置行 ID。草稿会被原地编辑；已发布或实时配置会被复制成新草稿。
--summary否根据编辑生成草稿标签或编辑摘要。
--strict否false存在验证警告时以非零状态退出。验证错误始终以非零状态退出。
--json否false输出结构化 JSON，而不是默认简洁输出。

​
应用

创建和修补应用及其核心商店元数据。更新时可通过传入空字符串清空可选字符串字段。 
cloudx config edit create-app --name "Puzzle Quest" --bundle-id com.example.puzzle --platform iOS --os-category GAMES
cloudx config edit update-app --id app_123 --status INACTIVE
cloudx config edit delete-app --id app_123

​
广告单元

创建和修补广告单元时，底价使用十进制 USD CPM。下面示例中的 --app-id、--id 和引用值在命令支持时可使用稳定 ID 或可解析名称。 
cloudx config edit create-ad-unit --name "Home Banner" --type BANNER --app-id app_123 --bidfloor 0.5 --banner-refresh-rate-ms 30000
cloudx config edit update-ad-unit --id au_123 --bidfloor 1.5
cloudx config edit delete-ad-unit --id au_123

​
广告单元组

创建和更新广告单元组时至少需要一个 --ad-unit-id。更新会用传入的 ID 替换组成员。 
cloudx config edit create-ad-unit-group --name "Homepage Banners" --ad-unit-id au_123 --ad-unit-id au_456
cloudx config edit update-ad-unit-group --id aug_123 --name "Homepage Banners" --ad-unit-id au_123
cloudx config edit remove-ad-unit-from-group --ad-unit-group-id aug_123 --ad-unit-id au_456
cloudx config edit delete-ad-unit-group --id aug_123

​
列表

列表支持 DOMAIN 和 IAB_CONTENT_CATEGORY。可重复传入 --value，或在有意创建空列表时使用 --empty。列表仍被定向或账号屏蔽列表引用时，删除会失败。 
cloudx config edit create-list --name "Blocked Domains" --type DOMAIN --value example.com --value ads.example
cloudx config edit update-list --id "Blocked Domains" --empty
cloudx config edit delete-list --id list_123

​
标签

频次上限字段必须成对提供。更新时使用 --clear-frequency-cap 清除上限。标签仍被订单项引用时，删除会失败。 
cloudx config edit create-tag --id vip --name "VIP"
cloudx config edit update-tag --id vip --frequency-cap-max-impressions 5 --frequency-cap-time-window session
cloudx config edit delete-tag --id vip

​
测试设备

测试设备按应用和设备广告标识符定位。Upsert 对已有设备只修改提供的可选字段。 
cloudx config edit upsert-test-device --app-id app_123 --device-ifa 00000000-0000-0000-0000-000000000000 --device-name "QA iPhone" --test 2 --debug true
cloudx config edit delete-test-device --app-id app_123 --device-ifa 00000000-0000-0000-0000-000000000000

​
网络映射

网络映射必须且只能指定一个应用或广告单元目标。使用重复的 --field key=value 传入适配器字段；CloudX 会在草稿验证结果中校验必填字段和格式。 
cloudx config edit upsert-network-mapping --app-id app_123 --adapter inmobi --field app_id=app-456 --field account_id=acct-789
cloudx config edit delete-network-mapping --ad-unit-id au_123 --adapter meta

​
A/B 测试

create-ab-test 创建草稿。update-ab-test、start-ab-test、end-ab-test、promote-ab-test 和 delete-ab-test 会立即发布生成的配置，并返回已发布配置 ID 和版本。 
cloudx config edit create-ab-test --ad-unit-id au_123 --name "Floor test" --traffic-ratio 0.25
cloudx config edit start-ab-test --ad-unit-id au_123
cloudx config edit end-ab-test --ad-unit-id au_123 --winner test
cloudx config edit promote-ab-test --ad-unit-id au_123
cloudx config edit delete-ab-test --ad-unit-id au_123

​
创建订单项

cloudx config edit create-line-item [flags]
创建订单项时必须提供以下核心字段：
标志说明
--name <name>订单项名称。
--priority <number>订单项优先级。数字越小越先评估。
--bidfloor <usd-cpm>订单项底价，单位为十进制 USD CPM。例如 1.5 表示 $1.50 CPM。
创建订单项还必须指定且只能指定一个目标：
标志说明
--ad-unit-id <id>目标广告单元 ID。
--ad-unit-group-id <id>目标广告单元组 ID。
可选字段：
标志说明
--status <status>订单项状态，例如 draft、active 或 paused。
--bidder <adapter>要为此订单项启用的竞价方适配器。可重复传入多个竞价方。
示例： 
cloudx config edit create-line-item \
  --name "美国激励视频" \
  --priority 2 \
  --bidfloor 1.5 \
  --ad-unit-id au_123 \
  --bidder meta \
  --bidder unityAds

​
更新订单项

cloudx config edit update-line-item --id <line-item-id> [fields]
更新命令是 patch 语义。只有 --id 始终必需；除此之外至少传入一个要修改的字段。未提供的字段保持原值不变。使用 --ad-unit-id 或 --ad-unit-group-id 更改目标时，会清除之前的目标引用。 可修补字段：
标志说明
--id <id>订单项 ID。必需。
--name <name>可选。修补订单项名称。
--priority <number>可选。修补订单项优先级。
--bidfloor <usd-cpm>可选。修补订单项底价，单位为十进制 USD CPM。
--status <status>可选。修补订单项状态。
--ad-unit-id <id>可选。修补目标广告单元 ID，并清除任何广告单元组目标。
--ad-unit-group-id <id>可选。修补目标广告单元组 ID，并清除任何广告单元目标。
--bidder <adapter>可选。用提供的竞价方适配器列表替换现有竞价方。可重复传入多个竞价方。
--clear-bidders可选。清空订单项上的所有竞价方。不能与 --bidder 同时使用。
验证规则：
  • 除 --id 外，至少传入一个要修改的字段。
  • --ad-unit-id 和 --ad-unit-group-id 只能使用一个。
  • --bidder 和 --clear-bidders 只能使用一个。
示例： 
cloudx config edit update-line-item --id li_123 --bidfloor 1.5
cloudx config edit update-line-item --id li_123 --priority 3 --status paused
cloudx config edit update-line-item --id li_123 --clear-bidders

​
删除订单项

cloudx config edit delete-line-item --id <line-item-id>
只有 --id 是必需字段。 示例： 
cloudx config edit delete-line-item --id li_123
cloudx config edit delete-line-item --id li_123 --summary "删除旧激励视频订单项"

​
OpenAPI 操作

POST /api/v1/config/edit 使用与 CLI 对应的操作名：create_app、update_app、delete_app、create_ad_unit、update_ad_unit、delete_ad_unit、create_ad_unit_group、update_ad_unit_group、delete_ad_unit_group、remove_ad_unit_from_group、create_list、update_list、delete_list、create_tag、update_tag、delete_tag、upsert_test_device、delete_test_device、upsert_network_mapping、delete_network_mapping、create_line_item、update_line_item、delete_line_item、create_ab_test、update_ab_test、start_ab_test、end_ab_test、promote_ab_test 和 delete_ab_test。 
{
  "summary": "Raise US rewarded floor",
  "operations": [
    {
      "update_line_item": [
        {
          "id": "li_123",
          "bidfloor": 1.5
        }
      ]
    }
  ]
}

​
cloudx config publish

将配置草稿发布为实时配置。 编辑并验证草稿后使用此命令。草稿上线前，CloudX 会运行与控制台相同的发布时验证检查。

​
用法

cloudx config publish --id <draft-id> [flags]

​
标志

标志必需默认值说明
--id是要发布为实时配置的草稿配置行 ID。
--version-label否已发布配置版本的可选标签。
--json否false输出结构化 JSON，而不是默认简洁输出。
验证行为：
  • 验证错误会阻止发布，并使命令以非零状态退出。
  • 警告会在成功发布后显示，但不会导致命令失败。
  • 如果仍有警告，输出会显示 cloudx config validate --id <config-id> 命令，方便查看详情。

​
示例

发布草稿 
cloudx config publish --id draft_123
发布并添加版本标签 
cloudx config publish --id draft_123 --version-label "5 月底价更新"
以 JSON 输出发布响应 
cloudx config publish --id draft_123 --json
调整竞价底价并发布 
cloudx config edit update-line-item --id li_123 --bidfloor 1.5 --summary "提高美国激励视频底价"
cloudx config validate --id draft_123
cloudx config publish --id draft_123 --version-label "提高美国激励视频底价"

​
cloudx config history

默认以表格列出配置历史行。 当您需要查看最近的配置发布、确认创建者，或查看发布时预计算的新增和删除差异数量时，请使用此命令。

​
用法

cloudx config history [flags]

​
标志

标志必需默认值说明
--since否只包含在此时间之后创建的配置。支持 RFC3339 时间戳或 YYYY-MM-DD 日期。
--author否按创建者用户 ID、邮箱或姓名子串过滤。
--include-drafts否false包含配置草稿。默认只返回已发布版本。
--json否false输出结构化 JSON，而不是默认表格。
验证规则：
  • --since 必须是 RFC3339 时间戳或 YYYY-MM-DD 日期。

​
输出格式

默认表格包含配置 ID、版本号、类型、创建时间、创建者、差异摘要、版本标签和描述。 
cloudx config history
差异值显示为 +新增/-删除，使用配置发布时计算出的 diff_additions 和 diff_deletions 值。 脚本需要原始响应字段时，使用 --json： 
cloudx config history --since 2026-05-01 --json

​
示例

列出已发布配置历史 
cloudx config history
列出最近配置变更 
cloudx config history --since 2026-05-01
按创建者过滤 
cloudx config history --author alice@example.com
包含草稿 
cloudx config history --include-drafts

​
相关链接