# 介绍
Cloudbase Open API 让开发者可以通过 HTTP 的方式,以管理员身份调用 CloudBase 的服务。
对于 CloudBase 尚未提供 SDK 的语言(如 Java、Go、C++ 等),开发者可以通过此种方式访问 Cloudbase。
# 了解请求结构
- 服务地址
https://tcb-api.tencentcloudapi.com
- 请求方法
支持的 HTTP 请求方法:GET, POST, PUT, PATCH, DELETE
- 请求头构造
头部字段 | 类型 | 必填 | 说明 |
---|---|---|---|
X-CloudBase-Authorization | String | 是 | 结构为:"<凭证版本> <CloudBase 签名>" ,CloudBase Open API 标准凭证 |
X-CloudBase-SessionToken | String | 是 | 腾讯云 CAM 临时密钥的 Session Token |
X-CloudBase-TimeStamp | Number | 否 | Unix 时间戳,以秒为单位 |
content-type | String | 否 | POST 时请指定 application/json |
# 使用示例
查询数据库文档
curl -X GET https://tcb-api.tencentcloudapi.com/api/v2/envs/{envId}/databases/{collectionName}/documents/{docId} \
-H "X-CloudBase-Authorization: <authorization>" \
-H "X-CloudBase-TimeStamp: 1551113065" \
-H "X-CloudBase-SessionToken: <sessiontoken>" \
# 如何获取凭证
# 1. 从云托管的请求头中获取凭证
云托管的服务中,可以读取请求头中携带的凭证信息,凭证字段 x-cloudbase-authorization
,临时密钥字段 x-cloudbase-sessiontoken
。
以云托管中的 Node.js 服务为例:
const express = require("express");
const got = require("got");
const app = express();
app.get("/", async (req, res) => {
// 从请求头中获取凭证信息
const authorization = req.headers["x-cloudbase-authorization"];
const sessiontoken = req.headers["x-cloudbase-sessiontoken"];
const timestamp = parseInt(Date.now() / 1000).toString();
// 使用凭证向 CloudBase Open API 发起请求
// 以查询文档为例,先拼接url
const envId = "foo";
const collectionName = "bar";
const docId = "123";
const url = `https://tcb-api.tencentcloudapi.com/api/v2/envs/${envId}/databases/${collectionName}/documents/${docId}`;
// 发起请求,请求头中加入凭证信息
const response = await got(url, {
headers: {
"X-CloudBase-Authorization": authorization,
"X-CloudBase-TimeStamp": timestamp,
"X-CloudBase-SessionToken": sessiontoken
}
});
res.send(response.body);
});
app.listen(3000);
# 2. Node.js 服务使用签名工具包计算凭证
Node.js 开发者可以直接使用 Node.js 的签名工具包,无需自行实现签名计算流程:
import { sign } from "@cloudbase/signature-nodejs";
const tmpSecretId = "腾讯云临时密钥SecretId";
const tmpSecretKey = "腾讯云临时密钥SecretKey";
const token = "腾讯云临时密钥Token";
const headers = {
host: "tcb-api.tencentcloudapi.com",
"content-type": "application/json; charset=utf-8"
};
const timestamp = Math.floor(new Date().getTime() / 1000);
const version = "1.0";
const { authorization } = sign({
secretId: tmpSecretId,
secretKey: tmpSecretKey,
method: "POST",
url: "https://tcb-api.tencentcloudapi.com",
headers,
timestamp,
params: {}
});
// Open API 请求头
const reqHeaders = {};
reqHeaders["X-CloudBase-Authorization"] = version + " " + authorization;
reqHeaders["X-CloudBase-SessionToken"] = token;
reqHeaders["X-CloudBase-TimeStamp"] = timestamp;
TIP
使用永久密钥时,可以忽略 sessionToken 字段
# 3. 使用临时密钥自行计算凭证
对于某些场景,开发者可自行拉取腾讯云临时密钥,计算出凭证,标准流程可以参考 腾讯云 CAM 签名流程 (opens new window)。
注意
CloudBase 标准凭证与腾讯云 CAM 签名 (opens new window)的计算流程大体相同,但在参数上有所简化,以下步骤请配合 腾讯云 CAM 签名流程 (opens new window) 阅读。
# (1) CanonicalRequest
其中 CanonicalRequest
的各项参数有简化,api.tcloudbase.com
为假设域名,如下:
字段 | 取值 |
---|---|
HTTPRequestMethod | "POST" |
CanonicalURI | "//api.tcloudbase.com/" |
CanonicalQueryString | 空 |
CanonicalHeaders | "content-type:application/json\nhost:api.tcloudbase.com\n" |
SignedHeaders | "content-type;host" |
HashedRequestPayload | 空 |
所以 CanonicalRequest
固定如下:
POST
//api.tcloudbase.com/
content-type:application/json; charset=utf-8
host:api.tcloudbase.com
content-type;host
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
# (2) StringToSign
然后计算 StringToSign
,假设时间戳为 1600227242
,结果如下:
TC3-HMAC-SHA256
1600227242
2020-09-16/tcb/tc3_request
0b986c5cd287577210de28ce0ff9167ada0dbb88736b07ce307b45615a49307e
# (3) Signature
我们假设 SecretKey 为 wH72j2a5ZzhwgnXViwVNqdWhWn4AG4iasv26D4JdjBA=
,Date 为 2020-09-16
,那么 Signature 为:
0ce229810e251baa0ee2bb786c5f9eb6cb7758f55df28cbc161883c48a997e04
# (4) 拼接 Authorization
TC3-HMAC-SHA256 Credential=AKIDDo-bNhLNl3kEY5HRzEG-CNUotmyFSadvpKimESWTfND98qyfrpYLCtQJ92_z9yN8/2020-09-16/tcb/tc3_request, SignedHeaders=content-type;host, Signature=0ce229810e251baa0ee2bb786c5f9eb6cb7758f55df28cbc161883c48a997e04
# (5) 加上 CloudBase 签名版本
前面加上 1.0
即可:
1.0 TC3-HMAC-SHA256 Credential=AKIDDo-bNhLNl3kEY5HRzEG-CNUotmyFSadvpKimESWTfND98qyfrpYLCtQJ92_z9yN8/2020-09-16/tcb/tc3_request, SignedHeaders=content-type;host, Signature=0ce229810e251baa0ee2bb786c5f9eb6cb7758f55df28cbc161883c48a997e04
数据库 →