活动导出
使用 CloudX CLI 创建并下载异步展示、请求和出价活动导出。
活动导出
使用 cloudx export 命令组为已结束的 UTC 日期创建异步活动导出：
cloudx export impressions用于展示级收入数据cloudx export requests用于请求级竞价活动cloudx export bids用于出价和未出价活动
每个命令都会打印导出 ID 和当前状态。添加 --wait 可等待任务进入终态；使用 --output <路径> 可等待任务完成并下载 gzip 压缩的 CSV 文件。
cloudx export bids
创建全天出价活动导出，并生成 gzip 压缩的 CSV 文件。默认情况下，文件同时包含出价响应以及未出价、超时和错误记录，便于从竞价方请求到出价结果进行分析。导出采用异步方式运行，因此大型结果集无需装入普通 API 响应。
获胜记录包含实际出价。对于落败出价，bid_price_cpm 始终为 0，bid_price_disclosure 为 redacted。
用法
cloudx export bids --date YYYY-MM-DD [过滤条件] [--wait] [--output <路径>]--date 为必填项，必须指定过去 45 天内已经结束的 UTC 日期。当天 UTC 日期尚未结束，因此不能导出。
选项
| 标志 | 必填 | 说明 |
|---|---|---|
--date | 是 | YYYY-MM-DD 格式的已结束 UTC 日期，必须在过去 45 天内。 |
--app | 否 | 应用包名，例如 com.example.game。 |
--ad-unit-id | 否 | CloudX 广告单元 ID。 |
--country | 否 | ISO 3166-1 alpha-2 国家代码，例如 US 或 GB。 |
--device-os | 否 | 设备操作系统。可选值：iOS、Android。 |
--bidder | 否 | 竞价方/广告网络代码。 |
--bids-only | 否 | 排除未出价、超时和错误记录。 |
--test-mode | 否 | 要包含的流量：production、test 或 all。默认值：production。 |
--wait | 否 | 轮询直至导出就绪或失败。 |
--output | 否 | 将就绪的 .csv.gz 文件下载到此路径。隐含启用 --wait。 |
每个账户同时最多只能处理两个出价活动导出任务。使用相同日期与过滤条件再次提交时，CLI 会复用匹配的排队中、运行中或已完成导出，而不会创建重复任务。
导出就绪后，CloudX 会返回一个有效期为一小时的下载 URL。在生成文件仍处于保留期内时，重新运行相同命令可获取新的 URL。生成文件最长保留七天。
示例
提交导出任务，并打印导出 ID 与当前状态：
cloudx export bids --date 2026-08-10等待任务完成并下载所有竞价方结果：
cloudx export bids \
--date 2026-08-10 \
--output ./bids-2026-08-10.csv.gz仅下载某个应用和竞价方的出价响应：
cloudx export bids \
--date 2026-08-10 \
--app com.example.game \
--bidder example-bidder \
--bids-only \
--output ./example-bidder-2026-08-10.csv.gzAPI 工作流
API 客户端可以通过 POST /export/bids 创建同样的导出。响应包含 export_id，状态为 processing、ready 或 failed。轮询 GET /export/bids/{export_id} 直到任务进入终态；就绪响应会包含短期有效的 url 和 expires_at。
{
"date": "2026-08-10",
"app_bundle": "com.example.game",
"bidder": "example-bidder",
"include_non_bids": true,
"test_mode": "production"
}CSV 字段
CSV 中每一行对应一条匹配的竞价方结果。不保证行顺序。
| 字段 | 说明 |
|---|---|
event_time | UTC 竞价方结果事件时间。 |
processing_date_and_hour | YYYYMMDD_HH 格式的 UTC 处理小时。 |
auction_id | 竞价 ID，也是关联其他导出的连接键。 |
time_usec | 以 Unix epoch 微秒表示的事件时间。 |
bid_id | 出价 ID（竞价方返回时）。 |
imp_id | OpenRTB 展示 ID。 |
round_number | 竞价轮次编号。 |
priority | 竞价轮次优先级。 |
app_bundle | 应用包名。 |
ad_unit_id | CloudX 广告单元 ID。 |
bidder | 竞价方/广告网络代码。 |
status | 记录的竞价方结果，例如 bid、nobid、timeout 或 error。 |
nonbid_reason | 数字型未出价原因。请参阅下方的代码说明。 |
bid_rejection_reason | winner、outbid、已记录的拒绝原因或未出价状态。 |
bid_price_cpm | 以 CPM 表示的出价。获胜出价为实际值；落败出价始终为 0。 |
bid_price_disclosure | actual、redacted 或 not_applicable。 |
effective_floor_cpm | 以 CPM 表示的有效卖方底价。 |
effective_floor_source | 用于确定有效底价的来源。 |
deal_id | 出价返回的 Deal ID（如有）。 |
country | 大写 ISO 国家代码。 |
device_os | 设备操作系统。 |
test_mode | 测试流量为 true；生产流量为 false。 |
http_status | 竞价方 HTTP 响应状态（如有）。 |
latency_ms | 竞价方响应延迟，单位为毫秒。 |
error_type | 记录的竞价方错误类型（如适用）。 |
currency | CPM 币种。当前为 USD。 |
nonbid_reason 遵循 IAB Tech Lab Seat Non-Bid 状态码范围。CloudX 会保留竞价方返回的 1–99 OpenRTB nbr 值。当 CloudX 确定结果时，当前会输出以下值：
| 值 | 含义 |
|---|---|
0 | 未出价：常规。竞价方未提供 nbr 或返回无效值时也使用此值。 |
100 | 错误：常规。 |
101 | 错误：超时。 |
103 | 错误：无法连接竞价方。 |
300 | 响应被拒绝：常规。 |
301 | 响应被拒绝：低于底价。 |
303 | 响应被拒绝：类别映射无效。 |
304 | 响应被拒绝：低于交易底价。 |
305 | 响应被拒绝：不支持出价币种。此值为 CloudX 专用值。 |
351 | 响应被拒绝：不允许该创意尺寸。 |
352 | 响应被拒绝：创意不安全。 |
cloudx export requests
将完整一天的请求活动异步导出为 gzip 压缩的 CSV 文件，每一行对应一个 CloudX 竞价请求。可用于分析请求量、填充决策、竞价方参与情况和竞价延迟。导出任务在后台运行，因此大型结果集无需在普通 API 响应的时限内完成。
当竞价选出获胜方时，request_status 为 filled；未选出获胜方时为 unfilled；请求处理失败时为 error。请求已填充并不保证客户端最终完成展示；请使用 auction_id 关联展示导出，以核对展示送达和收入。
用法
cloudx export requests --date YYYY-MM-DD [过滤条件] [--wait] [--output <路径>]--date 为必填项，必须是过去 45 天内已经结束的 UTC 日期。当前 UTC 日期尚未结束，因此不能导出。
选项
| 标志 | 必填 | 说明 |
|---|---|---|
--date | 是 | YYYY-MM-DD 格式的已结束 UTC 日期，必须在过去 45 天内。 |
--app | 否 | 应用包名，例如 com.example.game。 |
--ad-unit-id | 否 | CloudX 广告单元 ID。 |
--country | 否 | ISO 3166-1 alpha-2 国家代码，例如 US 或 GB。 |
--device-os | 否 | 设备操作系统。可选值：iOS、Android。 |
--request-status | 否 | 请求结果。可选值：filled、unfilled、error。 |
--test-mode | 否 | 要包含的流量：production、test 或 all。默认值：production。 |
--wait | 否 | 轮询直至导出就绪或失败。 |
--output | 否 | 将就绪的 .csv.gz 文件下载到此路径。隐含启用 --wait。 |
每个账户同时最多只能处理两个请求活动导出任务。使用相同日期与过滤条件再次提交时，CLI 会复用匹配的排队中、运行中或已完成导出，而不会创建重复任务。
导出就绪后，CloudX 会返回一个有效期为一小时的下载 URL。在生成文件仍处于保留期内时，重新运行相同命令可获取新的 URL。生成文件最长保留七天。
示例
等待任务完成并下载所有请求结果：
cloudx export requests \
--date 2026-08-10 \
--output ./requests-2026-08-10.csv.gz下载某个应用和国家的生产环境未填充请求：
cloudx export requests \
--date 2026-08-10 \
--app com.example.game \
--country US \
--request-status unfilled \
--output ./unfilled-requests-2026-08-10.csv.gzAPI 工作流
API 客户端可以通过 POST /export/requests 创建同样的导出。响应包含 export_id，状态为 processing、ready 或 failed。轮询 GET /export/requests/{export_id} 直到任务进入终态；就绪响应会包含短期有效的 url 和 expires_at。
{
"date": "2026-08-10",
"app_bundle": "com.example.game",
"request_status": "unfilled",
"test_mode": "production"
}CSV 字段
CSV 中每一行对应一个匹配的 CloudX 竞价请求。不保证行顺序。
| 字段 | 说明 |
|---|---|
event_time | UTC 请求事件时间。 |
processing_date_and_hour | YYYYMMDD_HH 格式的 UTC 存储处理小时。 |
auction_id | 竞价 ID，也是关联出价和展示导出的连接键。 |
time_usec | 以 Unix epoch 微秒表示的事件时间。源数据精度为毫秒。 |
app_id | 根据当前库存配置解析的 CloudX 应用 ID（如有）。 |
app_bundle | 请求中收到的应用包名。 |
app_name | 请求中收到的应用名称（如有）。 |
ad_unit_id | 根据当前库存配置解析的 CloudX 广告单元 ID；无法解析时使用请求中的广告位 ID。 |
ad_format | 根据当前库存配置解析的广告格式（如有）。 |
request_status | filled、unfilled 或 error。 |
is_filled_request | CloudX 选出竞价获胜方时为 true。 |
http_status | 竞价端点返回的 HTTP 状态。 |
imp_count | 请求中的 OpenRTB 展示机会数量。 |
priority | 获胜轮次或最后尝试的竞价轮次优先级。 |
bidder_count | 整个竞价过程中发起的竞价方调用数。 |
bid_count | 整个竞价过程中记录的出价响应数。 |
nonbid_count | 整个竞价过程中记录的未出价结果数。 |
has_winner | 竞价选出获胜方时为 true。 |
winner_bidder | 已填充时的获胜广告网络代码。 |
auction_duration_ms | 竞价处理时长，单位为毫秒。 |
country | 可识别时为大写 ISO 3166-1 alpha-2 国家代码。 |
device_os | 设备操作系统。 |
device_type | 记录的设备类型（如有）。 |
os_version | 设备操作系统版本（如有）。 |
sdk_version | CloudX SDK 版本（如有）。 |
session_id | publisher SDK 提供的会话标识符（如有）。 |
test_mode | 测试流量为 true；生产流量为 false。 |
ab_test_id | 分配的 CloudX A/B 测试 ID（如有）。 |
ab_test_variant | 分配的 A/B 测试版本（如有）。 |
error | 记录的请求处理错误（如适用）。 |
cloudx export impressions
将完整一天的展示级收入数据异步导出为 gzip 压缩的 CSV 文件。导出任务在后台运行，因此大型结果集无需在普通 API 请求的时限内完成。当发布商提供哈希用户 ID 且适用的隐私信号允许时，导出文件会包含该值，以支持用户级收入分析。
用法
cloudx export impressions --date YYYY-MM-DD [过滤条件] [--wait] [--output <路径>]--date 为必填项，必须是过去 45 天内已经结束的 UTC 日期。当前 UTC 日期尚未结束，因此不能导出。
选项
| 标志 | 必填 | 说明 |
|---|---|---|
--date | 是 | YYYY-MM-DD 格式的已结束 UTC 日期，必须在过去 45 天内。 |
--app-id | 否 | CloudX 应用 ID。不能与 --app 同时使用。 |
--app | 否 | 应用包名，例如 com.example.game。不能与 --app-id 同时使用。 |
--ad-unit-id | 否 | CloudX 广告单元 ID。 |
--country | 否 | ISO 3166-1 alpha-2 国家代码，例如 US 或 GB。 |
--device-os | 否 | 设备操作系统。可选值：iOS、Android。 |
--bidder | 否 | 竞价方/广告网络代码。 |
--line-item-id | 否 | CloudX 订单项 ID。 |
--test-mode | 否 | 要包含的流量：production、test 或 all。默认值：production。 |
--wait | 否 | 轮询直至导出就绪或失败。最长可等待 2 小时 15 分钟。 |
--output | 否 | 将就绪的 .csv.gz 文件下载到此路径。隐含启用 --wait。 |
每个账户同时最多只能处理两个展示导出任务。使用相同日期与过滤条件再次提交时，CLI 会复用匹配的排队中、运行中或已完成导出，而不会创建重复任务。
导出就绪后，CloudX 会返回一个有效期为一小时的下载 URL。在生成文件仍处于保留期内时，重新运行相同命令可获取新的 URL。生成文件最长保留七天。
示例
提交导出任务，并打印导出 ID 与当前状态：
cloudx export impressions --date 2026-07-16等待任务完成并下载结果：
cloudx export impressions \
--date 2026-07-16 \
--output ./impressions-2026-07-16.csv.gz导出美国地区某个 iOS 应用的生产流量展示：
cloudx export impressions \
--date 2026-07-16 \
--app com.example.game \
--country US \
--device-os iOS \
--test-mode production \
--output ./example-game-us-ios.csv.gz检查下载的压缩文件并预览表头与前几行：
gzip -t ./impressions-2026-07-16.csv.gz
gzip -cd ./impressions-2026-07-16.csv.gz | headAPI 工作流
API 客户端可以通过 POST /export/impressions 创建同样的导出。响应包含 export_id，状态为 processing、ready 或 failed。轮询 GET /export/impressions/{export_id} 直到任务进入终态；就绪响应会包含短期有效的 url 和 expires_at。
CSV 字段
CSV 中每一行对应一条匹配的展示记录。不保证行顺序。
| 字段 | 说明 |
|---|---|
event_time | UTC 展示事件时间。 |
impression_id | 唯一展示事件 ID。 |
auction_id | 关联的竞价 ID。 |
bid_id | 获胜出价 ID。 |
app_id | CloudX 应用 ID。 |
app_bundle | 应用包名。 |
ad_unit_id | CloudX 广告单元 ID。 |
ad_unit_name | 广告单元显示名称。 |
ad_format | 该展示记录的广告格式。 |
placement | 发布商广告位值。 |
custom_data | 发布商提供的自定义数据。 |
hashed_user_id | 在竞价时记录的发布商提供的哈希用户 ID。未设置 ID、隐私信号阻止持久化或值超过 128 个字符时为空。 |
country | 大写 ISO 国家代码。 |
device_os | 设备操作系统。 |
device_type | 该展示记录的设备类型。 |
advertising_id | 设备广告标识符（如有）。 |
advertising_vendor_id | 供应商标识符（如有）。 |
test_mode | 测试流量为 true；生产流量为 false。 |
network | 竞价方/广告网络代码。 |
line_item_id | CloudX 订单项 ID。 |
price_cpm | 以 CPM 表示的获胜价格。 |
revenue_usd | 此次单次展示产生的美元收入。 |
currency | 收入币种。当前为 USD。 |
revenue_precision | 收入精度。当前为 exact。 |
creative_id | 创意 ID（如有）。 |
network_placement_id | 广告网络侧广告位 ID（如有）。 |
ab_test_id | A/B 测试 ID（如适用）。 |
ab_test_variant | A/B 测试版本（如适用）。 |