> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置

> cloudx config 命令参考，包括实时配置、验证、草稿编辑、发布和版本历史。

# 配置

`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 为某个账号保存的精确库存配置、对比已发布版本，或在发布前检查草稿时，请使用此命令。

### 用法

```bash theme={null}
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，不包含行元数据：

```bash theme={null}
cloudx config show
```

使用 `--json` 只输出原始配置数据 JSON：

```bash theme={null}
cloudx config show --version 12 --json
```

当需要 config ID、账号 ID、类型、版本号、创建时间、创建者元数据、YAML 和原始数据等字段时，使用 `--with-metadata`：

```bash theme={null}
cloudx config show --version 12 --with-metadata
cloudx config show --id cfg_123 --with-metadata --json
```

### 示例

**显示实时配置**

```bash theme={null}
cloudx config show
```

**显示已发布版本**

```bash theme={null}
cloudx config show --version 12
```

**按 ID 显示配置**

```bash theme={null}
cloudx config show --id cfg_123
```

**显示带元数据的草稿**

```bash theme={null}
cloudx config show --draft --with-metadata
```

## `cloudx config validate`

验证本地 YAML 文件或远程配置。

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

### 用法

```bash theme={null}
cloudx config validate [file] [flags]
```

### 本地与远程验证

传入文件路径时，验证完全在本地运行，不会调用 API：

```bash theme={null}
cloudx config validate config.yaml
```

省略文件路径时，默认验证远程实时配置：

```bash theme={null}
cloudx config validate
```

使用 `--id` 验证指定配置行，包括由 `config edit` 创建的草稿；使用 `--version` 验证已发布版本：

```bash theme={null}
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 文件**

```bash theme={null}
cloudx config validate config.yaml
```

**出现警告时失败**

```bash theme={null}
cloudx config validate config.yaml --strict
```

**验证实时配置**

```bash theme={null}
cloudx config validate
```

**验证草稿并输出 JSON**

```bash theme={null}
cloudx config validate --id draft_123 --json
```

**验证已发布版本**

```bash theme={null}
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 测试并发布生成的配置。`update-ab-test` 也可替换测试版本的国家定向。 |
| `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，而不是默认简洁输出。                 |

### 应用

创建和修补应用及其核心商店元数据。更新时可通过传入空字符串清空可选字符串字段。

```bash theme={null}
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 或可解析名称。

```bash theme={null}
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 替换组成员。

```bash theme={null}
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`。列表仍被定向或账号屏蔽列表引用时，删除会失败。

```bash theme={null}
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` 清除上限。标签仍被订单项引用时，删除会失败。

```bash theme={null}
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 对已有设备只修改提供的可选字段。

```bash theme={null}
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 会在草稿验证结果中校验必填字段和格式。

```bash theme={null}
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 和版本。

在 `create-ab-test` 或 `update-ab-test` 中使用 `--country`，可将测试版本定向到指定国家。该标志接受 ISO 3166-1 alpha-2 或 alpha-3 国家代码，可重复传入，也支持逗号分隔的值。CloudX 会在生成的配置定向中以 alpha-3 代码保存。

```bash theme={null}
cloudx config edit create-ab-test --ad-unit-id au_123 --name "Floor test" --traffic-ratio 0.25 --country US --country GB
cloudx config edit update-ab-test --ad-unit-id au_123 --name "Floor test" --traffic-ratio 0.25 --country USA,GBR
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
```

### 创建订单项

```bash theme={null}
cloudx config edit create-line-item [flags]
```

创建订单项时必须提供以下核心字段：

| 标志                     | 说明                                            |
| ---------------------- | --------------------------------------------- |
| `--name <name>`        | 订单项名称。                                        |
| `--priority <number>`  | 订单项优先级，范围为 1 到 12。数字越小越先评估。                   |
| `--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>` | 要为此订单项启用的竞价方适配器。可重复传入多个竞价方。           |

示例：

```bash theme={null}
cloudx config edit create-line-item \
  --name "美国激励视频" \
  --priority 2 \
  --bidfloor 1.5 \
  --ad-unit-id au_123 \
  --bidder meta \
  --bidder unityAds
```

### 更新订单项

```bash theme={null}
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>`     | 可选。修补订单项优先级，范围为 1 到 12。              |
| `--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` 只能使用一个。

示例：

```bash theme={null}
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
```

### 删除订单项

```bash theme={null}
cloudx config edit delete-line-item --id <line-item-id>
```

只有 `--id` 是必需字段。

示例：

```bash theme={null}
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`。

```json theme={null}
{
  "summary": "Raise US rewarded floor",
  "operations": [
    {
      "update_line_item": [
        {
          "id": "li_123",
          "bidfloor": 1.5
        }
      ]
    }
  ]
}
```

## `cloudx config publish`

将配置草稿发布为实时配置。

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

### 用法

```bash theme={null}
cloudx config publish --id <draft-id> [flags]
```

### 标志

| 标志                | 必需 | 默认值     | 说明                    |
| ----------------- | -- | ------- | --------------------- |
| `--id`            | 是  |         | 要发布为实时配置的草稿配置行 ID。    |
| `--version-label` | 否  |         | 已发布配置版本的可选标签。         |
| `--json`          | 否  | `false` | 输出结构化 JSON，而不是默认简洁输出。 |

验证行为：

* 验证错误会阻止发布，并使命令以非零状态退出。
* 警告会在成功发布后显示，但不会导致命令失败。
* 如果仍有警告，输出会显示 `cloudx config validate --id <config-id>` 命令，方便查看详情。

### 示例

**发布草稿**

```bash theme={null}
cloudx config publish --id draft_123
```

**发布并添加版本标签**

```bash theme={null}
cloudx config publish --id draft_123 --version-label "5 月底价更新"
```

**以 JSON 输出发布响应**

```bash theme={null}
cloudx config publish --id draft_123 --json
```

**调整竞价底价并发布**

```bash theme={null}
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`

默认以表格列出配置历史行。

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

### 用法

```bash theme={null}
cloudx config history [flags]
```

### 标志

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

验证规则：

* `--since` 必须是 RFC3339 时间戳或 `YYYY-MM-DD` 日期。

### 输出格式

默认表格包含配置 ID、版本号、类型、创建时间、创建者、差异摘要、版本标签和描述。

```bash theme={null}
cloudx config history
```

差异值显示为 `+新增/-删除`，使用配置发布时计算出的 `diff_additions` 和 `diff_deletions` 值。

脚本需要原始响应字段时，使用 `--json`：

```bash theme={null}
cloudx config history --since 2026-05-01 --json
```

### 示例

**列出已发布配置历史**

```bash theme={null}
cloudx config history
```

**列出最近配置变更**

```bash theme={null}
cloudx config history --since 2026-05-01
```

**按创建者过滤**

```bash theme={null}
cloudx config history --author alice@example.com
```

**包含草稿**

```bash theme={null}
cloudx config history --include-drafts
```

## 相关链接

* [CloudX CLI 概览](/zh/cli)
* [身份认证命令](/zh/cli/authentication)
* [报表命令](/zh/cli/reporting)
* [示例](/zh/cli/examples)