用途:查询广告账户内广告活动(CAMPAIGN)、广告组(AD_SET)、广告账户(AD_ACCOUNT)、商业实体(BUSINESS)、素材(CREATIVE)等实体的变更时间线,用于审计谁改了什么、跟踪预算修改、查看状态变化和整体活动情况。
主要能力:调用接口 GET /ad_accounts/{ad_account_id}/change_history。支持按 entity_type、entity_ids、entity_name(不区分大小写的子串匹配,2-255 字符,需配合 entity_type)、change_ids、actor_ids、principal_type(USER、SERVICE)、change_category(STATUS、BUDGET、TARGETING、CREATIVE、SCHEDULING、SETTINGS、BILLING)、created_gte、created_lte 过滤;支持 limit(1-50,默认 50)、offset 分页,以及 sort_direction(ASC、DESC)、sort_field(TIMESTAMP、ENTITY_TYPE、PRINCIPAL_TYPE)排序。返回记录含 change_id、timestamp、entity_type、entity_id、entity_name、operation(CREATED、CHANGED、REMOVED)、actor(名称与类型)、changes 字段级前后值(before/after)。
使用方式:先设置插件根目录与请求封装: PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}" api() { "$PLUGIN_ROOT/scripts/api-request.sh" change-history "$@"; } 首次调用 Ads API v3 前,阅读并遵循 $PLUGIN_ROOT/skills/api-reference/references/live-openapi.md。可用 api --env 获取 TOKEN、AD_ACCOUNT_ID、AUTO_EXECUTE、BASE_URL 等设置值,输出可直接 eval。典型查询如: api GET "ad_accounts/{ad_account_id}/change_history?limit=20&sort_direction=DESC" 可按用户意图映射参数,如按类别与时间范围组合过滤,并可用 offset 翻页、用 change_ids 查单条记录详情。
执行与限制:auto_execute 为 true 时直接执行 curl,否则先展示命令并请求确认;始终先检查 curl 输出的 HTTP_STATUS 行,再解释响应体;出错时展示响应体中的错误信息,不自动重试。数据仅保留滚动 180 天窗口。未提及收费、价格或其他平台信息。