You need to enable JavaScript to run this app.
导航

开发前必读

最近更新时间2023.11.30 11:52:24

首次发布时间2021.10.13 18:19:23

1. 产品概述

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

2. 接入指南

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 确认访问账号和安全凭证

从 VeCDP 1.21 开始,在原先渠道账号的基础上,还提供了基于 STS (Security Token Service) 的认证方式。

2.2.1 渠道账号

进入VeCDP, 点击“项目中心”->"资产输出"->"渠道管理"->"自定义渠道", 点击“添加渠道应用”,配置访问的App 以及相应的账号,获取安全凭证,安全凭证包括Access Key Id(AK)和Secret Access Key(SK)。AccessKeyId 用于标识访问者的身份,Secret Access Key是用于加密签名字符串和服务器端验证签名字符串的密钥,必须严格保密。

2.2.2 STS 认证方式

通过 STS 方式可以获得一个有时效性的临时访问凭证,使用步骤如下:

  • 进入 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. 调用方法

3.1 请求结构

OpenAPI的请求结构如下:

服务地址
参考 2.1 确认URL。

通信协议
支持通过 HTTP 或 HTTPS 两种方式进行请求通信,推荐使用安全性更高的 HTTPS方式发送请求。

请求方法
请求方法详见各个接口具体的需求。OpenAPI大多数支持GET或POST请求。

请求参数
OpenAPI请求包含两类参数:公共请求参数和接口请求参数。其中公共请求参数在每个请求中都必须包含。接口请求参数需参考各个服务的接口文档。

字符编码
请求及返回结果使用UTF-8的字符集进行编码。

3.2 公共参数

所有接口请求中都必须携带公共参数,为了避免重复说明,产品的API文档中可能不再重复描述这部分参数,请您在请求API时携带这部分参数,否则请求将无法通过合法性验证

公共参数如下:

1. ApiAction 与 ApiVersion

注: ApiAction 与 ApiVersion 必须放到 query 中

名称类型是否必填参数格式描述示例值

ApiAction

String

[a-zA-Z]+

接口名称。实际调用时请参考您使用的产品的API文档取值

CreateUser

ApiVersionStringYYYY-MM-DD接口的版本。 实际调用时请参考您使用的产品的API文档取值。2023-02-10

2. 签名参数

注:签名参数放在 header 中

名称类型是否必填描述示例值

X-Date

String

使用UTC时间,精确到秒,使用遵循ISO 8601标准的格式:YYYYMMDD'T'HHMMSS'Z'

20201103T104027Z

Authorization

String

HMAC-SHA256 Credential={AccessKeyId}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}

HMAC-SHA256 Credential=AKLTMjI2ODVlYzI3ZGY1NGU4ZjhjYWRjMTlmNTM5OTZkYzE/20201230/cn/open_platform/request, SignedHeaders=content-type;x-date, Signature=28eeabbbd726b87002e0fe58ad8c1c768e619b06e2646f35b6ad7ed029a6d8a7

Authorization中的信息含义:

名称类型备注
AccessKeyIdString请求的Access Key ID。
ShortDateString请求的短时间,精确到日。使用UTC时间,请使用格式:YYYYMMDD, 例如:20180201
RegionString请求的地域例如cn,当您使用的产品按Region提供服务时,该参数值请填写您实际要访问的Region。当使用非Region服务类产品,可以填写“cn”
ServiceString请求的服务,此处填写open_platform
SignedHeadersString参与签名的Header,多个Header间用分号分隔。目的是指明哪些header参与签名计算
SignatureString计算完毕的签名。

3.3 签名机制

此处介绍上文签名参数的生成机制。具体为两个字段的生成机制即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进制编码

  1. 创建签名字符串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:上面计算出的结果。

  1. 计算签名秘钥(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部分相同。

  1. 计算签名
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.4 返回结果

公共错误码

Http Status备注
400关键参数缺失,例如Action, Version参数
401签名结果不正确,鉴权失败

返回结果 Json 结构

名称数据类型描述
dataObject返回数据内容
msgString请求出现错误,返回错误信息
codeInt返回错误码(全局常用错误码表见附录 7.3)

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

4. 参数名称统一

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