CloudX API

了解如何认证请求并使用 CloudX API 参考。

CloudX API

使用 CloudX API 获取报表指标、检查竞价、管理任务，并读取或写入账号配置。

基础 URL

https://provisioning.cloudx.io/api/v1

认证

在 Settings > API Keys 中创建 API key，然后将它作为 bearer token 发送：

curl https://provisioning.cloudx.io/api/v1/auth/status \
  -H "Authorization: Bearer $CLOUDX_API_KEY"

只有管理员可以创建、管理和撤销 API key。

权限

根据集成需要调用的端点选择权限。

权限	允许访问
`reports:read`	`/report/` 下的报表端点和 `/export/` 下的活动导出端点
`auctions:read`	`/auction/*` 下的竞价检查端点
`configuration:read`	`/config/*` 下的配置端点和任务读取端点
`configuration:write`	`/config/*` 下的配置写入端点和任务写入端点

广告网络报表

使用 GET /report/network 读取来自 Digital Turbine、InMobi、Liftoff、Meta 和 Moloco 数据源连接的每日报表。可按日期、广告网络、应用、国家/地区、平台、广告格式或广告位拆分结果，按精确值过滤，并以 JSON 或 CSV 分页读取。

Unity Ads

在数据源设置中连接 Unity Ads，即可在需求对比中对比 Unity 的报表与 CloudX 的数据。GET /report/network 暂不返回 Unity Ads 数据。

CloudX 需要您从 Unity Monetization 后台获取以下四个值：

字段	在 Unity 中的位置
Organization ID	Organization settings → Organization core ID。该页面显示两个组织 ID，请使用 core ID。
Stats API key	API management → Monetization Stats API Access。如果没有 key，请选择 Create API key。
Key ID	服务账号的 key。请参阅下方步骤。
Secret key	与 Key ID 一起生成。Unity 只显示一次。

创建服务账号需要您是该 Unity 组织的 Owner 或 Manager：

打开 Settings → Organization → Manage organization → Service accounts，选择 + New。部分后台版本将 Service accounts 放在 Administration 下。
在服务账号页面，进入 Organization roles，选择 + Manage organization roles。在 Monetization 列表中添加 Monetize Projects Viewer。
在 Keys 中选择 + Add key，复制 Key ID 和 Secret key。

CloudX 只读取您的 Unity 报表、项目和广告位，因此服务账号不需要编辑或管理员角色，但必须具有第 2 步中的角色。缺少该角色时，CloudX 会在保存时显示 These keys can’t read this Unity organization’s reporting and projects。

保存后，CloudX 会同步最近 30 天的 Unity 报表，之后每天同步一次。

活动导出

通过 POST /export/impressions、POST /export/requests 或 POST /export/bids 创建异步的全天活动导出报表，然后轮询对应的 GET 端点，直到导出就绪。

大多数报表会在 5–45 分钟内准备好供下载。处理时间取决于所选日期和过滤条件对应的数据量。导出就绪后，状态响应会包含一个短期有效的下载 URL。

请参阅活动导出，了解 API 和 CLI 共用的请求正文、轮询示例和 CSV 架构。

配置写入

使用 POST /config/edit 为应用、广告单元、广告单元组、列表、标签、测试设备、网络映射和订单项创建或更新配置草稿。该端点也支持 A/B 测试操作；创建 A/B 测试会返回草稿，更新、开始、结束、提升和删除会发布生成的配置。

请求使用带类型的操作键，例如 create_app、update_ad_unit、upsert_network_mapping 和 update_line_item。底价在订单项上设置；创建和更新广告单元的操作不接受 bidfloor。订单项的 bidfloor 使用十进制 USD CPM，因此 1.5 表示 $1.50 CPM。

任务

使用 /scheduled-agents 端点管理定期运行的 CloudX 分析。为保持兼容性，API 端点路径使用 scheduled-agents，产品和 CLI 中则称为任务。

使用提示词和五字段 cron 计划创建任务：

curl https://provisioning.cloudx.io/api/v1/scheduled-agents \
  -X POST \
  -H "Authorization: Bearer $CLOUDX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "每周收入回顾",
    "prompt": "检查每周收入并标记重大变化",
    "schedule": "0 9 * * 1",
    "timezone": "Asia/Shanghai",
    "access_mode": "workspace"
  }'

任务端点支持完整生命周期：

方法	端点	操作
`GET`	`/scheduled-agents`	列出任务。
`POST`	`/scheduled-agents`	创建任务。
`GET`	`/scheduled-agents/{scheduled_agent_id}`	获取一个任务。
`PATCH`	`/scheduled-agents/{scheduled_agent_id}`	更新一个或多个字段。
`DELETE`	`/scheduled-agents/{scheduled_agent_id}`	删除任务。
`POST`	`/scheduled-agents/{scheduled_agent_id}/run`	立即将已启用的任务加入队列。

读取操作需要 configuration:read 权限；变更操作需要 configuration:write 权限。使用用户身份认证进行变更时，还需要编辑者权限。账号必须已启用 Tasks 功能。

将 access_mode 设置为 private 或 workspace。私有任务必须有最终用户创建者，并且仅对该用户可见。使用 API key 创建的任务没有最终用户创建者，对整个工作区可见，且不能更改为私有任务。

任务响应包含 cron 表达式、IANA 时区、可读计划、启用状态、访问模式、可选的创建者用户 ID、下次运行时间、时间戳和创建来源。

API 参考

API 参考由 CloudX 托管的实时 OpenAPI schema 生成。