gdt-auto/docs/ADGROUP_CREATE_GUIDE.md

腾讯广告创建功能说明

功能概述

本文档介绍如何使用gdt-auto项目创建腾讯广告组(Adgroup)。

核心实现

1. Service层实现

TencentAdsAdgroupService.java

public AdgroupsAddResponseData createAdgroup(String accountId, AdgroupsAddRequest request) 
        throws TencentAdsResponseException, TencentAdsSDKException, Exception {
    log.info("开始创建广告,accountId={}, adgroupName={}", accountId, request.getAdgroupName());
    
    // 获取TencentAds实例
    TencentAds tencentAds = clientFactory.getTencentAds(accountId);
    
    // 设置账户ID
    request.setAccountId(Long.parseLong(accountId));
    
    // 调用SDK创建广告
    AdgroupsAddResponseData response = tencentAds.adgroups()
        .adgroupsAdd(request);
    
    log.info("创建广告成功,adgroupId={}", response.getAdgroupId());
    
    return response;
}

2. 测试实现

TencentAdsAdgroupCreateTest.java

测试类实现了：

• 完整的创建广告测试用例
• 根据您提供的测试数据构建请求对象
• 定向设置的构建（地域、性别、年龄、排除人群等）

测试数据说明

基础字段

字段	类型	说明	示例
adgroup_name	String	广告名称	"测试ROI-0204" + 时间戳
marketing_goal	MarketingGoal	营销目标	MARKETING_GOAL_USER_GROWTH
marketing_carrier_type	MarketingCarrierType	营销载体类型	MARKETING_CARRIER_TYPE_JUMP_PAGE
begin_date	String	开始日期	"2026-02-03"
end_date	String	结束日期	"2026-02-03"
optimization_goal	OptimizationGoal	优化目标	OPTIMIZATIONGOAL_APP_REGISTER
time_series	String	投放时间段	336位字符串
bid_amount	Long	出价金额(分)	100
daily_budget	Long	日预算(分)	1000
conversion_id	Long	转化ID	74719216
bid_mode	BidMode	出价模式	BID_MODE_OCPM
auto_derived_creative_enabled	Boolean	自动衍生创意	false
bid_scene	BidScene	出价场景	BID_SCENE_UNKNOWN

定向设置(targeting)

地域定向(geo_location)

GeoLocations geoLocation = new GeoLocations();
List<String> locationTypes = new ArrayList<>();
locationTypes.add("LIVE_IN"); // 居住地
geoLocation.setLocationTypes(locationTypes);
List<Long> regions = new ArrayList<>();
regions.add(1156L); // 中国
geoLocation.setRegions(regions);

性别定向(gender)

List<String> gender = new ArrayList<>();
gender.add("MALE"); // 男性

年龄定向(age)

List<AgeStruct> age = new ArrayList<>();
AgeStruct ageRange = new AgeStruct();
ageRange.setMin(35L);
ageRange.setMax(66L);
age.add(ageRange);

排除转化用户(excluded_converted_audience)

ExcludedConvertedAudience excludedConverted = new ExcludedConvertedAudience();
excludedConverted.setExcludedDimension(ExcludedDimension.EXCLUDED_DIMENSION_GROUP);

List<String> conversionBehaviorList = new ArrayList<>();
conversionBehaviorList.add("OPTIMIZATIONGOAL_BRAND_CONVERSION");
conversionBehaviorList.add("OPTIMIZATIONGOAL_PAGE_SCAN_CODE");
excludedConverted.setConversionBehaviorList(conversionBehaviorList);

excludedConverted.setExcludedDay(ExcludedDay.EXCLUDED_DAY_ONE_MONTH);

排除自定义人群(excluded_custom_audience)

List<Long> excludedCustomAudience = new ArrayList<>();
excludedCustomAudience.add(43712084L);
excludedCustomAudience.add(44107982L);
excludedCustomAudience.add(44106830L);
excludedCustomAudience.add(44241932L);

投放站点(site_set)

List<String> siteSet = new ArrayList<>();
siteSet.add("SITE_SET_SEARCH_SCENE");      // 搜索场景
siteSet.add("SITE_SET_MOBILE_UNION");      // 移动联盟
siteSet.add("SITE_SET_WECHAT");            // 微信
siteSet.add("SITE_SET_KANDIAN");           // 看点
siteSet.add("SITE_SET_QQ_MUSIC_GAME");     // QQ音乐游戏
siteSet.add("SITE_SET_TENCENT_NEWS");      // 腾讯新闻
siteSet.add("SITE_SET_TENCENT_VIDEO");     // 腾讯视频

运行测试

1. 修改配置

在 src/main/resources/application-local.yml 中配置：

• 腾讯广告的账户信息
• Access Token

2. 运行测试

cd /Users/pudongliang/moka_workspace/gdt-auto
mvn test -Dtest=TencentAdsAdgroupCreateTest#testCreateAdgroupWithTestData

3. 查看测试数据JSON

可以运行打印JSON的测试方法查看请求数据结构：

mvn test -Dtest=TencentAdsAdgroupCreateTest#printTestDataJson

API文档参考

• 腾讯广告创建广告API文档
• SDK版本：marketing-api-java-sdk 1.1.106

注意事项

1. 时间序列: time_series是336位字符串,表示7天*48个半小时的投放时间,1表示投放,0表示不投放
2. 金额单位: bid_amount和daily_budget的单位都是分(¥0.01)
3. 枚举值: SDK中的枚举类型需要使用valueOf()方法转换字符串
4. 定向设置: targeting是一个复杂对象,包含多种定向条件
5. 账户ID: 需要在调用前确保账户已完成OAuth授权

常见问题

Q1: 如何获取Access Token?

A: 需要先进行OAuth授权,具体参考TencentAdsAuthService.java

Q2: 如何查看更多字段?

A: 参考SDK中的AdgroupsAddRequest.class类,包含所有可用字段

Q3: 如何自定义定向条件?

A: 可以参考WriteTargetingSetting类,支持更多定向维度

相关文件

• Service层: TencentAdsAdgroupService.java
• 测试类: TencentAdsAdgroupCreateTest.java
• API客户端工厂: TencentAdsApiClientFactory.java
• 实体类: TencentAdsAdgroup.java