# 腾讯广告创建功能说明

## 功能概述

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

## 核心实现

### 1. Service层实现

[TencentAdsAdgroupService.java](file:///Users/pudongliang/moka_workspace/gdt-auto/src/main/java/com/moka/gdtauto/service/TencentAdsAdgroupService.java#L284-L312)

```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](file:///Users/pudongliang/moka_workspace/gdt-auto/src/test/java/com/moka/gdtauto/service/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)
```java
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)
```java
List<String> gender = new ArrayList<>();
gender.add("MALE"); // 男性
```

#### 年龄定向(age)
```java
List<AgeStruct> age = new ArrayList<>();
AgeStruct ageRange = new AgeStruct();
ageRange.setMin(35L);
ageRange.setMax(66L);
age.add(ageRange);
```

#### 排除转化用户(excluded_converted_audience)
```java
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)
```java
List<Long> excludedCustomAudience = new ArrayList<>();
excludedCustomAudience.add(43712084L);
excludedCustomAudience.add(44107982L);
excludedCustomAudience.add(44106830L);
excludedCustomAudience.add(44241932L);
```

### 投放站点(site_set)
```java
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. 运行测试

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

### 3. 查看测试数据JSON

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

```bash
mvn test -Dtest=TencentAdsAdgroupCreateTest#printTestDataJson
```

## API文档参考

- [腾讯广告创建广告API文档](https://developers.e.qq.com/v3.0/docs/api/adgroups/add)
- 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](file:///Users/pudongliang/moka_workspace/gdt-auto/src/main/java/com/moka/gdtauto/service/TencentAdsAuthService.java)

### Q2: 如何查看更多字段?

A: 参考SDK中的[AdgroupsAddRequest.class](file:///marketing-api-java-sdk-1.1.106.jar/com.tencent.ads.model.v3/AdgroupsAddRequest.class)类,包含所有可用字段

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

A: 可以参考[WriteTargetingSetting](file:///marketing-api-java-sdk-1.1.106.jar/com.tencent.ads.model.v3/WriteTargetingSetting.class)类,支持更多定向维度

## 相关文件

- Service层: [TencentAdsAdgroupService.java](file:///Users/pudongliang/moka_workspace/gdt-auto/src/main/java/com/moka/gdtauto/service/TencentAdsAdgroupService.java)
- 测试类: [TencentAdsAdgroupCreateTest.java](file:///Users/pudongliang/moka_workspace/gdt-auto/src/test/java/com/moka/gdtauto/service/TencentAdsAdgroupCreateTest.java)
- API客户端工厂: [TencentAdsApiClientFactory.java](file:///Users/pudongliang/moka_workspace/gdt-auto/src/main/java/com/moka/gdtauto/client/TencentAdsApiClientFactory.java)
- 实体类: [TencentAdsAdgroup.java](file:///Users/pudongliang/moka_workspace/gdt-auto/src/main/java/com/moka/gdtauto/entity/TencentAdsAdgroup.java)