控制面API调用流程--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

控制面API

控制面API调用流程

概述

该文档是对控制面 API 调用流程的介绍，在使用 API 接口前，需先做好以下准备工作。
同时介绍响应体的公共参数，供用户在调用时参考。

调用流程

1. 账号注册与服务开通

通过注册账号及开通服务页面操作，完成注册账号及开通服务。

2. AK/SK 密钥获取

在调用火山引擎向量数据库 VikingDB 的各个能力之前，确保您已生成访问密钥 Access Key。
Access Key 包括 Access Key ID（简称 AK）和 Access Key Secret（简称 SK）。其中，AK 用于标识用户，SK 用于验证用户的密钥，请您妥善保管。
AK/SK 密钥获取方式如下，更多详情请参考 Access Key（密钥）管理。

单击右上角账号名称下拉框中的【密钥管理】进入对应页面。
单击【新建密钥】按钮，可获取 AK/SK，并以此为凭证调用已开通服务的接口。

注意

安全起见，建议新建子账户，并使用子账户的 AK/SK。

3. 签名生成

签名是什么？

签名是 API 请求中的一串经过计算得到的编码字符串，它用于身份认证和防止数据被篡改。

签名获取了就能一直用吗？

签名不像 AK、SK，每个请求的签名都是独立且临时的；一个签名只能用于一次特定的请求，不能长期固定使用。
下方调用示例包含从鉴权到调用的完整步骤，供参考。

4. 调用示例（以 Python 为例）

调用查看数据集详情的接口示例：
说明：运行该示例请填入 AK、SK、host、action 和 body，其中 action 和 body 见接口文档。

import os
import datetime
import hashlib
import hmac
from urllib.parse import quote

import requests, json

def norm_query(params):
    query = ""
    for key in sorted(params.keys()):
        if type(params[key]) == list:
            for k in params[key]:
                query = (
                        query + quote(key, safe="-_.~") + "=" + quote(k, safe="-_.~") + "&"
                )
        else:
            query = (query + quote(key, safe="-_.~") + "=" + quote(params[key], safe="-_.~") + "&")
    query = query[:-1]
    return query.replace("+", "%20")

def hmac_sha256(key: bytes, content: str):
    return hmac.new(key, content.encode("utf-8"), hashlib.sha256).digest()

def hash_sha256(content: str):
    return hashlib.sha256(content.encode("utf-8")).hexdigest()

class ClientForConsoleApi:
    def __init__(self, ak, sk, host, region):
        self.ak = ak
        self.sk = sk
        self.host = host
        self.region = region
        self.service_code = "vikingdb"
        self.version = "2025-06-09"

    def request(self, method, action, body, query=None, header=None):
        if query is None:
            query = {}
        if header is None:
            header = {}
        credential = {
            "access_key_id": self.ak,
            "secret_access_key": self.sk,
            "service": self.service_code,
            "region": self.region,
        }
        request_param = {
            "body": json.dumps(body),
            "host": self.host,
            "path": "/",
            "method": method,
            "content_type": 'application/json',
            "date": datetime.datetime.utcnow(),
            "query": {"Action": action, "Version": self.version, **query},
        }
        if body is None:
            request_param["body"] = ""
        x_date = request_param["date"].strftime("%Y%m%dT%H%M%SZ")
        short_x_date = x_date[:8]
        x_content_sha256 = hash_sha256(request_param["body"])
        sign_result = {
            "Host": request_param["host"],
            "X-Content-Sha256": x_content_sha256,
            "X-Date": x_date,
            "Content-Type": request_param["content_type"],
        }
        signed_headers_str = ";".join(
            ["content-type", "host", "x-content-sha256", "x-date"]
        )
        canonical_request_str = "\n".join(
            [request_param["method"].upper(),
             request_param["path"],
             norm_query(request_param["query"]),
             "\n".join(
                 [
                     "content-type:" + request_param["content_type"],
                     "host:" + request_param["host"],
                     "x-content-sha256:" + x_content_sha256,
                     "x-date:" + x_date,
                 ]
             ),
             "",
             signed_headers_str,
             x_content_sha256,
             ]
        )

        hashed_canonical_request = hash_sha256(canonical_request_str)
        credential_scope = "/".join([short_x_date, credential["region"], credential["service"], "request"])
        string_to_sign = "\n".join(["HMAC-SHA256", x_date, credential_scope, hashed_canonical_request])

        k_date = hmac_sha256(credential["secret_access_key"].encode("utf-8"), short_x_date)
        k_region = hmac_sha256(k_date, credential["region"])
        k_service = hmac_sha256(k_region, credential["service"])
        k_signing = hmac_sha256(k_service, "request")
        signature = hmac_sha256(k_signing, string_to_sign).hex()

        sign_result["Authorization"] = "HMAC-SHA256 Credential={}, SignedHeaders={}, Signature={}".format(
            credential["access_key_id"] + "/" + credential_scope,
            signed_headers_str,
            signature,
        )
        header = {**header, **sign_result}
        r = requests.request(method=method,
                             url="https://{}{}".format(request_param["host"], request_param["path"]),
                             headers=header,
                             params=request_param["query"],
                             data=request_param["body"],
                             )
        return r.status_code, r.headers, r.json()

if __name__ == '__main__':
    client = ClientForConsoleApi(
        ak = "*",#替换为您的 AK
        sk ="*" ,#替换为您的 SK
        host="vikingdb.cn-beijing.volcengineapi.com", #替换为您所在地区的域名
        region="cn-beijing"
    )
    http_code, _, result_json = client.request(
        method="POST",
        action="GetVikingdbCollection",#action替换为当前操作
        body={
            "CollectionName": "my_collection", #body替换为当前参数
        }
    )
    print("req http status code: ", http_code)
    print("req result: \n", result_json)

支持的域名和 Region

详见：地域和访问域名（Endpoint）

Region 名称	域名
cn-beijing	vikingdb.cn-beijing.volcengineapi.com
cn-shanghai	vikingdb.cn-shanghai.volcengineapi.com
cn-guangzhou	vikingdb.cn-guangzhou.volcengineapi.com

请求公共参数介绍

参数	类型	是否必填	位置	描述
Action	String	是	请求参数 query 中	要执行的操作，例如CreateVikingdbCollection，具体见接口描述。
Version	String	是	请求参数 query 中	API 的版本，固定取值：2025-06-09。

响应体公共参数介绍

正确返回包含 ResponseMetadata 和 Result 两部分。

参数名	一级子参数	类型	说明
ResponseMetadata		Map	响应元数据
	RequestId	String	请求 ID
	Action	String	请求执行的操作，示例：CreateVikingdbCollection。
	Version	String	API 的版本，固定值 2025-06-09。
	Service	String	目标服务的标识码，固定值 vikingdb
	Region	String	服务区域，如 cn-beijing
Result		Map	如果操作没有结果或不需要结果，则返回的 Result = null

响应错误仅返回 ResponseMetadata，其中包含错误信息 Error。

参数名	一级子参数	二级子参数	类型	说明
ResponseMetadata			Map	响应元数据
	RequestId		String	请求 ID
	Action		String	请求执行的操作，示例：CreateVikingdbCollection。
	Version		String	API 的版本，固定值 2025-06-09。
	Service		String	目标服务的标识码，固定值 vikingdb
	Region		String	服务区域，如 cn-beijing
	Error		Map	错误信息
		Code	String	Code 内容为具体的错误码，可根据错误码查询文档解决问题。
		Message	String	Message 描述了错误发生的具体原因，供排查问题参考。

最近更新时间：2026.04.14 17:18:20

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

1. 账号注册与服务开通 #

2. AK/SK 密钥获取 #

3. 签名生成 #

签名是什么？ #