广告单元列表

获取广告单元列表信息。

请求地址

v2: https://openapi.aiclk.com/openapi/v1/adgroup/get_v2

所属权限

ads_read

请求方式

GET

请求参数

字段名	类型	是否必须	描述
account_id	int	是	广告主ID(广告投放平台的userID)
query	string	是	请求参数结构，json格式，具体字段如下

query参数

字段名	类型	是否必须	描述
campaign_id	int	否	计划ID
adgroup_id	[]int	否	广告单元ID,示例:[3333,4444,5555]
fields	[]string	是	需要的返回字段，允许值："configure_status","effective_status","adgroup_id","campaign_id","adgroup_name","charge_type","adslot_type_group","media_group",regions","gender","age","audience_orient","audience_orient_filter","user_orient","os_type","mobile","tel_brand_choice","tel_brand_exclude","network_type","hours","app_package","app_package_value","app_filter","app_filter_value","device_orient","frequency","click_frequency","bid","cpa_bid","conversion_goal","conversion_from","ocpx_status","ocpx_expand","deep_cpa_bid","is_deep_ocpx","deep_conversion_goal","cpa_check_priority","creative_id","unable_reason","created_at","auto_stage2","conversion_filter_orient","conversion_filter_orient_duration","conversion_goal_filter","transfer_optimize","unit_study_status"
created_at	object	否	创建时间过滤，查询结果包含start和end
- start	string	否	开始时间，例如：2020-03-10
- end	string	否	结束时间，例如：2020-03-12
updated_at	object	否	修改时间过滤，start和end字段至少传一个
- start	string	否	开始时间，例如：2020-03-10
- end	string	否	结束时间，例如：2020-03-12
configure_status	[]string	否	单元状态，开启-ENABLE,暂停-PAUSED,删除-DELETED
page	int	否	页数，默认为1
page_size	int	否	页面大小，默认为10，不大于100

query示例

{
       "page": 1,
       "page_size": 10,
       "campaign_id": 333333,
       "adgroup_id": [
           3333,
           4444,
           5555
       ],
       "fields": [
           "campaign_id",
           "adgroup_id",
           "adgroup_name"
       ]
}

请求示例

curl -X GET \
  'https://openapi.aiclk.com/openapi/v1/adgroup/get?account_id=1000002&query={"campaign_id":1000054,"adgroup_id":[1000071],"page":1,"page_size":10,"fields":["campaign_id","adgroup_id","adgroup_name","configure_status","creative_id","age","gender","bid","charge_type","ocpx_status"]}' \
  -H 'Host: openapi.aiclk.com' \
  -H 'OGW_ACCESS_TOKEN: your_access_token'

返回字段释义

字段名	类型	描述
code	int	返回码
message	string	返回信息
data	object	返回值，json格式，包含如下字段
- list	object	返回值列表
-- configure_status	string	单元状态，开启-ENABLE,暂停-PAUSED,删除-DELETED
-- effective_status	string	操作状态，开启-ENABLE，暂停-PAUSED
-- adgroup_id	int	单元ID
-- campaign_id	int	计划ID
-- creative_id	string	创意ID，多个以逗号分隔
-- created_at	string	创建时间
-- adgroup_name	string	单元名称
-- charge_type	string	付费方式。枚举值
-- adslot_type_group	[]string	广告类型。
-- media_group	[]string	媒体类型。
-- regions	[]string	区域定向，枚举值
-- gender	string	性别定向，枚举值
-- age	string	年龄定向，枚举值
-- audience_orient	[]int	人群包定向
-- audience_orient_filter	[]int	人群包排除
-- user_orient	string	新老用户定向
-- os_type	string	操作系统类型，枚举值
-- mobile	[]string	手机型号定向，枚举值
-- tel_brand_choice	string	手机品牌定向，不传默认不限。设备操作系统定向为Android时可用，同一手机品牌和排除不能共存。枚举值
-- tel_brand_exclude	string	手机品牌排除，不传默认不限。设备操作系统定向为Android时可用，同一手机品牌和排除不能共存。枚举值
-- network_type	[]string	网络类型定向，枚举值
-- hours	[]int	投放时段，具体的格式参考：时间格式示例
-- app_package	string	安装包定向开关，开启-ENABLE，关闭-DISABLE
-- app_package_value	[]string	定向安装包值
-- app_filter	string	安装包排除开关，开启-ENABLE，关闭-DISABLE
-- app_filter_value	[]string	排除的安装包
-- device_orient	string	设备定向
-- frequency	int	展现频次限制
-- click_frequency	int	点击频次限制
-- bid	int	CPC/CPM/oCPX方式的点击出价，单位：分
-- cpa_bid	int	目标转化出价，单位：分
-- deep_cpa_bid	int	深度转化出价，单位：分
-- conversion_filter_orient	string	过滤已转化用户，枚举值
-- conversion_filter_orient_duration	string	过滤时间，枚举值
-- conversion_goal_filter	string	过滤已转化目标，枚举值
-- conversion_goal	string	转化目标，枚举值
-- conversion_from	string	转化来源，枚举值
-- ocpx_status	string	oCPX状态，枚举值
-- ocpx_expand	string	oCPX扩量工具，开启-ENABLE，关闭-DISABLE
-- auto_stage2	string	直接进入二阶段开关，枚举值：开启-ENABLE，关闭-DISABLE
-- retention_rate	float	单元目标次留率,大于0%，小于100%的百分数
-- is_deep_ocpx	string	是否为深度oCPX，枚举值：是-ENABLE，否-DISABLE
-- deep_conversion_goal	string	深度转化目标，枚举值
-- cpa_check_priority	string	目标成本考核，枚举值
-- transfer_optimize	string	调起优化，仅限charge_type为CPC时使用，不传默认不使用，枚举值
-- unit_study_status	int	学习状态，枚举值
-- unable_reason	string	无法投放原因
- page_info	json	分页信息
-- page	int	页数
-- page_size	int	页面大小
-- total_number	int	总数

返回示例

{
    "code": 200,
    "message": "success",
    "data": {
        "list": [
            {
                "campaign_id": 123235,
                "adgroup_id": 343233,
                "adgroup_name": "广告单元名字",
                "creative_id": "11111,22222,44444",
                "gender": "COMMON",
                "age": "BELOW_EIGHTEEN",
                "charge_type": "OCPM",
                "ocpx_status": "OCPX_STATUS_DEFAULT",
                "bid": 1500,
                "cpa_bid": 22200,
                "deep_cpa_bid": 30000,
                "configure_status": "ENABLE"
            }
        ],
        "page_info":{ 
            "page": 1, 
            "page_size": 10, 
            "total_number": 2
        } 
    }
}