感谢您选择火山引擎VeCDP 开放平台OpenAPI，本文档将为您介绍开放平台的接入全流程，助力您全方位实现数据管理和赋能，可以通过Openapi来开发对接下游系统，以满足企业更多元的业务需求。

VeCDP 目前分为两个不同版本：私部(On-Premise)以及SaaS版本。在不同的版本下接口访问的方式会有相应变化。

2.1 确认URL

访问OpenAPI的URL由两部分组成, base以及path。

http://<base>/<path>

其中base部分用于定位VeCDP的OpenAPI所在网络地址，而path部分用于确定具体的接口。
在下面的例子中， https://xxx.datarangers-onpremise.volces.com 是base部分，而/open_platform/openapi是path部分。

# 访问所有标签列表
https://xxx.datarangers-onpremise.volces.com/open_platform/openapi

私部
私部环境下OpenAPI的访问地址大多数情况下与VeCDP主页面前缀相同，具体以实际部署为准。

https://e168-2-169.datarangers-onpremise.volces.com/open_platform/openapi

SaaS

https://console.volcengine.com/cdp/open\_platform/openapi

2.2 确认访问账号和安全凭证

1.23版本及之后的版本，原自定义渠道中的API密钥管理能力，合并到了开放平台-应用管理功能，保持原有API获取密钥功能不变,同时增加了更多能力，详情可查看应用管理功能。（历史帮助文档中如果涉及需要从自定义渠道管理中获取密钥但未修改的，统一到应用管理中获取）

• 进入 VeCDP，点击进入“项目中心 -> 集团管理 -> 应用管理”界面中，点击“新建应用”按钮，配置应用访问可授权的项目，并关联授权用户。

• 在应用管理列表中可以看到创建的应用，复制秘钥（AK，SK）
• 使用该 AK，SK 调用 6.1 中的获取用户临时 Token 接口获取临时凭证（包含了临时 AK，SK 和 token）
• 使用临时 AK，SK 和 token（有时效性） 可以访问其他 OpenAPI（或者通过 SDK 的方式调用，调用方式见 8. SDK 的使用。

注：通过 STS 临时凭证直接调用 OpenAPI 时，AK 和 SK 的使用方式和之前相同，在此基础上，新增 header：X-Cdp-Security-Token，value 为 token

3.1 SDK调用示例

目前提供 Golang、Java两种语言版本的SDK。
在使用 SDK 调用 OpenAPI 过程中不需要传入 ApiAction 和 ApiVersion，只需要在构造 Client 时指定 basePath，AK 和 SK，或者传入 《权限相关接口》1.获取用户临时Token接口获得的临时 AK SK 和 token 构造； 详细见 SDK 说明和示例：

3.1.1 Golang SDK

1. 获取与安装

环境要求：

• Go 环境版本必须不低于 1.15安装cdp SDK for Go:

  go get -u github.com/volcengine/cdp-openapi-sdk-go@v1.19.0

2. 相关配置并初始化客户端

设置安全凭证和连接超时等配置

var basePath = "https://XXX/open_platform/openapi"
var accessKeyId = "ak"
var accessKeySecret = "sk"

httpCLient := http.Client{Timeout: 1 * time.Second}
//初始化配置对象
Config := Configuration{AccessKeyId: accessKeyId, AccessKeySecret: accessKeySecret,
   BasePath: basePath, HTTPClient: &httpCLient}
   
// 使用 6.1 接口获得的临时 ak sk 和 token 构造连接配置
Config := Configuration{AccessKeyId: "ak", AccessKeySecret: "sk", SessionToken: "token", BasePath: "basePath", HTTPClient: &httpCLient}
   
//实例化客户端
client, err := NewAPIClient(&Config)

3. API调用示例

文档中示例代码仅供参考
分群相关API

1. 分群列表

opts := SegmentationApiLegacyGetSegmentListOpts{Current: optional.NewInt32(1), PageSize: optional.NewInt32(20)}
responseBody, httpRespose, err := client.SegmentationApi.LegacyGetSegmentList(context.Background(), 1, &opts)

2. 分群详细信息

tenantId := 1
segId : =123
responseBody, httpRespose, err := client.SegmentationApi.LegacyGetSegment(context.Background(), tenantId, segId)

3.1.2 Java SDK

代码仓库:

开源Github: https://github.com/volcengine/cdp-openapi-sdk-java

Maven: https://search.maven.org/search?q=a:cdp-openapisdk-java

添加依赖

<dependency>
    <groupId>com.volcengine</groupId>
    <artifactId>cdp-openapisdk-java</artifactId>
    <version>1.19.0</version>
</dependency>

Version同CDP版本

使用示例

// 通过渠道账号获取的 AK SK 来访问（不推荐）
private final ApiClient client = new ApiClient(
    "ak",
    "sk",
   "https://xxxx/open_platform/openapi"
);

// 使用基于 STS 的方式来访问（推荐）见 2.2 步骤中获取 App 秘钥（ak，sk），另外需要传入绑定账号名
private final ApiClient client = new ApiClient(
    "ak",
    "sk",
    "account"
   "https://xxxx/open_platform/openapi"
);

private final SegmentationApi segClient = new SegmentationApi(client);

@Test
public void sdkTest() throws Exception {
    try {
        File file = segClient.downloadSegFile(1, 1000008, "txt", false);
        System.out.println(file.getName());
        ByteDanceResponseSegmentationUploadResp res = segClient.uploadSegFile(file, 1);
        System.out.println(res);
    } catch (ApiException e) {
        throw e;
    }
}

@Test
public void sdkAsyncTest() throws Exception {
    try {
        segClient.legacyGetSegmentListAsync(
            1, 1, 10, null, null, null, null, null, null, null, null,
            new ApiCallback<ByteDanceResponseSegmentationListResp>() {

                public void onFailure(ApiException e, int statusCode, Map<String, List<String>> responseHeaders) {}

                public void onSuccess(ByteDanceResponseSegmentationListResp result, int statusCode, Map<String, List<String>> responseHeaders) {
                    System.out.println(result);
                }

                public void onUploadProgress(long bytesWritten, long contentLength, boolean done) {}

                public void onDownloadProgress(long bytesRead, long contentLength, boolean done) {}
            });
        Thread.sleep(5000);
    } catch (ApiException e) {
        throw e;
    }
}

3.2 接口调用加密算法请求结构

OpenAPI的请求结构如下：
服务地址
参考 2.1 确认URL。
通信协议
支持通过 HTTP 或 HTTPS 两种方式进行请求通信，推荐使用安全性更高的 HTTPS方式发送请求。
请求方法
请求方法详见各个接口具体的需求。OpenAPI大多数支持GET或POST请求。
请求参数
OpenAPI请求包含两类参数：公共请求参数和接口请求参数。其中公共请求参数在每个请求中都必须包含。接口请求参数需参考各个服务的接口文档。
字符编码
请求及返回结果使用UTF-8的字符集进行编码。

3.2.1 公共参数

所有接口请求中都必须携带公共参数，为了避免重复说明，产品的API文档中可能不再重复描述这部分参数，请您在请求API时携带这部分参数，否则请求将无法通过合法性验证。
公共参数如下：
1. ApiAction 与 ApiVersion
注： ApiAction 与 ApiVersion 必须放到 query 中

2. 签名参数
注：签名参数放在 header 中

Authorization中的信息含义：

3.2.2 签名机制

此处介绍上文签名参数的生成机制。具体为两个字段的生成机制即Credential和SignedHeaders，这两个字段合并成authorization。
几个简写：

Hash代指SHA256算法
HexEncode代指转16进制编码
Hmac指代Hmac_SHA256

1. 创建一个正规化请求CanonicalRequest

CanonicalRequest = HTTPRequestMethod + '\n' + CanonicalURI + '\n' + CanonicalQueryString + '\n' + CanonicalHeaders + '\n' + SignedHeaders + '\n' + HexEncode(Hash(RequestPayload))

其中每个字段的含义如下：

• HTTPRequestMethod：指代http请求的method，例如：GET、POST等。
• CanonicalURI：指代正规化后的URI。如果URI为空，那么使用"/"作为绝对路径。在CDP中绝大多数接口的URI都为"/"。如果是复杂的path，请通过RFC3986规范进行编码。
• CanonicalQueryString：指代正规化后的Query String。对于Query String的正规化大致的过程如下：
  • urlencode（注：同RFC3986方法）每一个querystring参数名称和参数值。
  • 按照ASCII字节顺序对参数名称严格排序，相同参数名的不同参数值需保持请求的原始顺序。
  • 将排序好的参数名称和参数值用=连接，按照排序结果将“参数对”用&连接。
  • 例如：

CanonicalQueryString = "ApiAction=ListUsers&ApiVersion=2018-01-01"

• CanonicalHeaders：指代正规化后的Header，具体操作如下：
  • 将Header的名称全部转化成小写
  • 去掉Header的值的前后多余的空格
  • 用":"连接header的名称和值
  • 每个header占一行，拼接成一个String
• SignedHeaders：指参与签名的header，和CanonicalHeaders包含的header是一一对应的，目的是指明哪些header参与签名计算，从而忽略请求被proxy添加的额外header，其中host、x-date如果存在header中则必选参与。具体操作如下：
  • 将上面CanonicalHeaders中的每一组header都转小写，用";"隔开，不换行了。
• HexEncode(Hash(RequestPayload))：RequestPayload指完整的请求body，此处先对其计算SHA256，再转16进制编码

2. 创建签名字符串StringToSign

签名字符串主要包含请求以及正规化请求的元数据信息，由签名算法、请求日期、信任状和正规化请求哈希值连接组成，伪代码如下：

StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + HexEncode(Hash(CanonicalRequest))

• Algorithm：指代签名的算法，目前CDP仅支持HMAC-SHA256的签名算法。
• RequestDate：指代请求UTC时间，请使用如下格式：YYYYMMDD'T'HHMMSS'Z' 。
• CredentialScope：指代信任状，格式为：YYYYMMDD/region/service/request。
• CanonicalRequest：上面计算出的结果。

3. 计算签名秘钥（signing-key)

在计算签名前，首先从私有访问密钥（secret Access Key）派生出签名密钥（signing key），而不是直接使用私有访问密钥。具体计算过程如下：

kSecret = *Your Secret Access Key*
kDate = HMAC(kSecret, Date)
kRegion = HMAC(kDate, Region)
kService = HMAC(kRegion, Service)
kSigning = HMAC(kService, "request")

其中Date精确到日，与RequestDate中YYYYMMDD部分相同。

4. 计算签名

Signature = HexEncode(HMAC(kSigning, StringToSign))

然后构建header

Authorization: HMAC-SHA256 Credential={AccessKeyId}/{CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}

表达式中用{}括起来的代表上文计算出的中间过程。
ak/sk获取
私部环境

• 进入CDP, 点击“项目中心”->"资产输出"->"渠道管理"->"自定义渠道"， 点击“添加渠道应用”，配置访问的App 以及相应的账号

签名示例
以这个调用为例：

AK:BDPPee313bdff6ef33555d6c5c1e7b8152aa
SK:75e089c0f77268a20f0ce78d97eea0f

GET https://e0-0-220cdp.datarangers-onpremise.volces.com/open_platform/openapi?ApiAction=ListUsers&ApiVersion=2023-02-10&Limit=10&Offset=0 HTTP/1.1
Host: e0-0-220cdp.datarangers-onpremise.volces.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Content-Sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Date:20201230T081805Z

说明：
header: X-Content-Sha256 表示对请求中的二进制的body进行SHA-256 哈希。
如果是Get请求，则对[]byte{} 进行sha256 哈希，哈希值是"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

规范请求

CanonicalRequest = HTTPRequestMethod + '\n' + CanonicalURI + '\n' + CanonicalQueryString + '\n' + CanonicalHeaders + '\n' + SignedHeaders + '\n' + HexEncode(Hash(RequestPayload))

• HTTPRequestMethod

GET

• CanonicalURI

/open_platform/openapi

• CanonicalQueryString

ApiAction=ListUser&ApiVersion=2023-02-10&Limit=10&Offset=0

• CanonicalHeaders

将需要参与签名的header的key全部转成小写， 然后以ASCII排序后以key-value的方式组合后换行构建。

x-date:20230313T051101Z
// 多一个换行

• SignedHeaders

x-date

• HexEncode(Hash(RequestPayload))

无论是GET请求还是POST请求都有RequestPayload，其中此请求中的RequestPayload是空字符串。
这里的hash算法代指：sha256 []byte

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

• 最终CanonicalRequest

GET
/open_platform/openapi
ApiAction=ListUser&ApiVersion=2023-02-10&Limit=10&Offset=0
x-date:20230313T051101Z

x-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

待字符串

StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + HexEncode(Hash(CanonicalRequest))

• Algorithm

目前是一个固定的字符串

HMAC-SHA256

• RequestDate

请求发起的时间， 与X-Date相同。

20230313T051101Z

CredentialScope
指代信任状，格式为：YYYYMMDD/region/service/request
此请求信息如下：

20230313/cn/open_platform/request

• HexEncode(Hash(CanonicalRequest))

933cfa461d6630a796a773a9e3ef13489bdf12fe4ad1a99ee724634b2b6a9ee6

• 最终StringToSign

HMAC-SHA256
20230313T051101Z
20230313/cn/open_platform/request
933cfa461d6630a796a773a9e3ef13489bdf12fe4ad1a99ee724634b2b6a9ee6

签名

HMAC这里代指HMAC-SHA256

• Signingkey示例

HMAC(HMAC(HMAC(HMAC(kSecret,"20230313"),"cn"),"open_platform"),"request")

以下示例显示了此 HMAC 哈希操作序列生成的派生签名密钥。这说明了此二进制签名密钥中每个字节的十六进制表示形式。

b40d8e9b81c28d8494218b3c7ddb07155345ec33bf858b2026b6bb335eb6de58

• Signature示例

signature = HexEncode(HMAC(Signingkey, StringToSign))

最终的结果如下：

c808c9fce0d830df36b957e8797fc58728c0209f41193d21f6e117d1b6932dc9

将签名添加到请求当中
在请求中增加Authorization的header如下：

Authorization: HMAC-SHA256 Credential={AccessKeyId}/{CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}

完整结果如下：

Authorization: HMAC-SHA256 Credential=BDPPee313bdff6ef33555d6c5c1e7b8152aa/20230313/cn/open_platform/request, SignedHeaders=x-date, Signature=c808c9fce0d830df36b957e8797fc58728c0209f41193d21f6e117d1b6932dc9

CDP 提供了Java, Golang语言的SDK, SDK的使用参见文档 SDK使用。

3.2.3 返回结果

公共错误码

返回结果 Json 结构

下面具体接口描述响应参数列表中，只说明此处未列出的字段。

接口调用中 X-Tenant、tenantCode、tenantId、appId、projectId 均为项目ID，代表相同含义，仅参数名称不同，获取方式见附录1.租户code获取方式。