巨量引擎 Marketing API Java SDK 介绍

知识汲取者2026-05-05 17:02

文章目录

巨量引擎 Marketing API Java SDK 介绍

概述

巨量引擎 Marketing API Java SDK 是字节跳动巨量引擎开放平台的官方 Java SDK，为开发者提供了完整的广告投放管理 API 调用能力。SDK 实现了请求封装、响应解释、认证管理等功能，帮助开发者快速搭建广告投放管理系统。

SDK版本 : 1.1.85
API协议版本 : v1.0 / v2 / v3.0
Java版本 : 1.8+
构建工具 : Maven
许可证: Unlicense

GitHub：https://github.com/oceanengine/ad_open_sdk_java

目录结构

复制代码 
src/main/java/com/bytedance/ads/
├── api/                    # API端点类 (1138个)
├── model/                  # 数据模型、枚举、请求/响应对象
├── auth/                   # 认证相关类
│   ├── Authentication.java
│   ├── ApiKeyAuth.java
│   ├── HttpBasicAuth.java
│   └── HttpBearerAuth.java
├── examples/               # 各API的使用示例代码
├── ApiClient.java         # HTTP客户端 (OkHttp3封装)
├── Configuration.java     # 全局配置与版本信息
├── JSON.java              # Gson序列化工具
├── ApiException.java      # 异常处理
├── Pair.java              # 键值对工具
├── ApiResponse.java       # API响应封装
└── GzipRequestInterceptor.java  # Gzip压缩拦截器

核心组件详解

ApiClient

ApiClient 是 SDK 的核心 HTTP 客户端，负责所有 HTTP 通信和数据序列化。

主要配置项:

配置项 默认值 说明
basePath https://api.oceanengine.com API服务器地址
debugging false 调试模式
userAgent Bytedance Ads Openapi SDK 用户代理
timeout OkHttp默认 请求超时时间

初始化示例:

java 复制代码 
ApiClient apiClient = new ApiClient();
apiClient.setBasePath("https://api.oceanengine.com");
apiClient.setDebugging(true);  // 开启调试日志

设置请求超时:

java 复制代码 
apiClient.getHttpClient().newBuilder()
    .connectTimeout(30, TimeUnit.SECONDS)
    .readTimeout(30, TimeUnit.SECONDS)
    .writeTimeout(30, TimeUnit.SECONDS);

Authentication

SDK 使用 Access-Token 进行认证，基于 ApiKeyAuth 实现：

java 复制代码 
// 在请求头中添加 Access-Token
apiClient.addDefaultHeader("Access-Token", "your_token_here");

// 全局设置
Configuration.setDefaultApiClient(apiClient);

API 版本说明

SDK 支持三个版本的巨量引擎后端 API：

版本概览

SDK后缀 API路径 版本名称 接口数量 占比 说明
V30 /open_api/v3.0/... API v3.0 452 39% 升级版，包含创编、数据报表、DOU+等新能力
V2 /open_api/2/... API v2 528 45% 主力版本，功能成熟稳定
V10 /open_api/1.0/... API v1.0 166 14% 早期版本，已逐步弃用

版本选择建议

  • 新项目: 推荐使用 V30 (v3.0)，包含最新的API能力
  • 现有项目迁移: 建议逐步从 V2 迁移到 V30
  • V10: 不推荐新项目使用，遗留项目可考虑升级

V30 新增能力

根据 API 覆盖范围，V3.0 版本主要提供：

  • 创编能力升级
  • 数据报表增强
  • DOU+ 相关接口
  • 品牌广告完整能力

API 分类详解

SDK 包含丰富的 API 分类，覆盖广告投放管理全流程：

主要分类

分类 数量 说明
Tools 264 工具类接口（站点管理、视频处理、建站等）
Qianchuan 163 千川广告相关（抖音号推广等）
Star 119 星图/达人相关接口
Local 51 本地推广相关
Brand 44 品牌广告相关
Report 42 数据报表相关
File 42 文件上传下载（图片、视频等）
Dpa 39 DP漫淘（动态商品广告）
Clue 27 线索相关
Advertiser 26 广告主账户管理
Agent 23 代理商相关
Ad 9 广告管理
Campaign 4 计划管理

其他分类

还包括: Keyword(9)、Douplus(9)、Creative(8)、Security(8)、Yuntu(7)、Dmp(11)、Aic(10)、Uni(5)、Oc(5)、Oauth2(5)、Ebp(5)、Carousel(5)、Audience(5)、Project(13)、Cg(13) 等。

分类用途说明

  • Tools: 辅助工具，如视频封面推荐、锚点检查、第三方站点管理等
  • Qianchuan: 抖音号推广的完整能力支持
  • Star: 达人合作、星图任务相关
  • Report: 数据报表查询和分析
  • Dpa: 动态商品广告的素材管理和投放
  • Clue: 线索收集和客户管理

快速开始

1. 添加 Maven 依赖

xml 复制代码 
<dependencies>
    <dependency>
        <groupId>org.openapitools</groupId>
        <artifactId>oceanengine-mapi-java-client</artifactId>
        <version>[0.0.1,)</version>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <id>OceanengineOpenApi</id>
        <name>ad_open_sdk_java</name>
        <layout>default</layout>
        <url>https://artifact.bytedance.com/repository/releases/</url>
    </repository>
</repositories>

2. 阿里云镜像配置

如使用阿里云等第三方镜像，需要排除 OceanengineOpenApi:

xml 复制代码 
<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>*,!OceanengineOpenApi</mirrorOf>
        <name>阿里云公共仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>

3. 初始化客户端

java 复制代码 
import com.bytedance.ads.ApiClient;
import com.bytedance.ads.Configuration;

public class Demo {
    public static void main(String[] args) {
        // 创建并配置 ApiClient
        ApiClient apiClient = new ApiClient();
        apiClient.setBasePath("https://api.oceanengine.com");
        apiClient.addDefaultHeader("Access-Token", "your_access_token");

        // 设置为全局默认客户端
        Configuration.setDefaultApiClient(apiClient);
    }
}

4. 调用 API 示例

获取广告列表 (V2)
java 复制代码 
import com.bytedance.ads.api.AdGetV2Api;
import com.bytedance.ads.model.AdGetV2Filtering;
import com.bytedance.ads.model.AdGetV2Response;

AdGetV2Api api = new AdGetV2Api();
api.setApiClient(apiClient);

// 构建过滤条件
AdGetV2Filtering filtering = new AdGetV2Filtering();
filtering.setStatus(List.of("ENABLE"));

// 调用API
AdGetV2Response response = api.openApi2AdGetGet(
    advertiserId,    // 广告主ID
    null,           // fields
    filtering,      // 过滤条件
    1L,             // page
    20L,            // pageSize
    null,           // 其他参数...
    null,
    null,
    null
);

// 处理响应
if (response.getData() != null) {
    response.getData().getList().forEach(ad -> {
        System.out.println(ad.getAdId() + ": " + ad.getTitle());
    });
}
获取账户资金 (V3.0)
java 复制代码 
import com.bytedance.ads.api.AccountFundGetV30Api;
import com.bytedance.ads.model.AccountFundGetV30Response;

AccountFundGetV30Api api = new AccountFundGetV30Api();
api.setApiClient(apiClient);

AccountFundGetV30Response response = api.openApiV30AccountFundGetGet(
    advertiserId,  // 广告主ID
    null,          // accountType
    null           // grantTypeSplit
);

if (response.getData() != null) {
    response.getData().getList().forEach(fund -> {
        System.out.println("资金类型: " + fund.getFundType() +
                           ", 余额: " + fund.getBalance());
    });
}

数据模型说明

命名规则

SDK 中的数据模型遵循统一的命名规则：

模型类型 命名模式 示例
请求模型 {Entity}{Operation}V{Version}Request AdGetV2Request
响应模型 {Entity}{Operation}V{Version}Response AdGetV2Response
响应数据 {Entity}{Operation}V{Version}ResponseData AdGetV2ResponseData
列表项 {Entity}{Operation}V{Version}ResponseDataListInner AdGetV2ResponseDataListInner
枚举类 {Entity}{Operation}V{Version}{FieldName} AdGetV2DataPricing

响应结构

典型的 API 响应结构：

java 复制代码 
public class AdGetV2Response {
    private AdGetV2ResponseData data;      // 响应数据
    private Long code;                      // 错误码
    private String message;                 // 错误信息
}

public class AdGetV2ResponseData {
    private List<AdGetV2ResponseDataListInner> list;  // 数据列表
    private Long page;                      // 当前页
    private Long pageSize;                  // 每页大小
    private Long total;                      // 总数
}

错误处理

异常类型

SDK 定义了 ApiException 用于处理 API 调用错误：

java 复制代码 
try {
    AdGetV2Response response = api.openApi2AdGetGet(...);
} catch (ApiException e) {
    // 获取错误信息
    System.err.println("错误码: " + e.getCode());
    System.err.println("错误信息: " + e.getMessage());

    // 获取原始响应
    if (e.getResponse() != null) {
        System.err.println("HTTP状态: " + e.getResponse().getStatusCode());
    }
}

错误码说明

错误码 说明
0 成功
401 认证失败，检查 Access-Token
403 权限不足，确认应用已开通对应API权限
400 请求参数错误，检查参数格式
429 请求过于频繁，调用频率超限
500 服务器内部错误

依赖库

库名 版本 用途
okhttp3 4.10.0 HTTP客户端
okhttp3:logging-interceptor 4.10.0 HTTP日志拦截
gson 2.9.1 JSON序列化
gson-fire 1.8.5 Gson扩展
jackson-databind-nullable 0.2.6 可空类型处理
javax.annotation-api 1.3.2 注解支持
jsr305 3.0.2 类型注解
reflections 0.10.2 反射工具

高级配置

自定义 OkHttpClient

java 复制代码 
import okhttp3.OkHttpClient;
import java.util.concurrent.TimeUnit;

OkHttpClient customClient = new OkHttpClient.Builder()
    .connectTimeout(60, TimeUnit.SECONDS)
    .readTimeout(60, TimeUnit.SECONDS)
    .writeTimeout(60, TimeUnit.SECONDS)
    .addInterceptor(new YourCustomInterceptor())
    .build();

ApiClient apiClient = new ApiClient(customClient);

多环境切换

java 复制代码 
// 测试环境
apiClient.setBasePath("https://api-sg.oceanengine.com");

// 生产环境
apiClient.setBasePath("https://api.oceanengine.com");

设置自定义服务器

java 复制代码 
apiClient.setServers(Arrays.asList(
    new ServerConfiguration("https://primary.example.com", "Primary", null),
    new ServerConfiguration("https://backup.example.com", "Backup", null)
));
apiClient.setServerIndex(0);  // 选择第一个服务器

线程安全

ApiClient 实例本身不是线程安全的。建议：

  • 每个线程使用独立的 ApiClient 实例
  • 或使用线程本地变量：
java 复制代码 
private static final ThreadLocal<ApiClient> clientHolder =
    ThreadLocal.withInitial(() -> {
        ApiClient client = new ApiClient();
        client.addDefaultHeader("Access-Token", getTokenForCurrentThread());
        return client;
    });

// 获取当前线程的 client
ApiClient client = clientHolder.get();

相关资源

资源 链接
开发者快速入门 https://open.oceanengine.com/labels/7/docs/1696710498372623
API接口列表 https://open.oceanengine.com/labels/7
Maven仓库 https://artifact.bytedance.com/repository/releases/
GitHub仓库 https://github.com/openapitools/openapi-generator

注意事项

  1. 镜像源配置 : 使用阿里云等第三方镜像时需排除 OceanengineOpenApi
  2. 权限要求: 使用 SDK 前需确保应用已开通相应 API 权限
  3. 代码生成: SDK 代码由 OpenAPI Generator 自动生成，请勿手动修改
  4. Token管理: 定期刷新 Access-Token，避免过期
  5. 频率限制: 注意 API 调用频率限制，避免触发限流

技术支持

如遇问题可联系运营同学或加入 SDK 使用沟通群。

相关推荐
182******20831 小时前
2026年40岁自学java还能找到工作吗
java·开发语言
yuzhiboyouye2 小时前
java线程池
java·开发语言·firefox
网络工程小王2 小时前
【LCEL 链式调用详解】调用篇-2
java·服务器·前端·数据库·人工智能
Zzzzmo_2 小时前
【JavaEE】文件操作和IO
java·java-ee·io·文件操作·file·流对象
NE_STOP3 小时前
Redis-持久化之RDB
java
苍煜3 小时前
SpringBoot AOP切面编程精讲：实现方式、Spring区别及与自定义注解生产实战
java·spring boot·spring
胡小禾3 小时前
企业内部文件处理方案
java
无限进步_4 小时前
二叉搜索树完全解析：从概念到实现与应用场景
c语言·开发语言·数据结构·c++·算法·github·visual studio
常利兵4 小时前
Spring Boot：别再重复造轮子，这些内置功能香麻了
java·spring boot·后端
热门推荐
01要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法02GitHub 镜像站点03Codex 接入 DeepSeek API 完整配置文档04零基础教你claude code 接入 deepseek V405【AI】2026 年具身智能模型和世界模型总结06裂开！ChatGPT 居然开始要手机号验证，附详细解决方法07几个好用的ip纯净度检测网站082026年AI前瞻：量子AI、具身智能与科学发现的新纪元09CC-Switch & Claude 基于 Linux 服务器安装使用指南10在Windows 11上安装Docker的踩坑记录