文档中心

向量数据库VikingDB

数据库管理

数据库管理 API 使用说明

调用方式

数据库的管理（创建和管理库，更改库的配置，创建和管理用户等）属于火山控制面 OpenAPI 接口。控制面接口统一通过 TOP 开放网关调用，用于库管理、用户管理等运维操作。
与数据库访问类接口不同，数据库管理接口需使用火山 AK SK 生成签名进行接口鉴权，并使用通用的 & 格式进行路径请求。详情见下方鉴权方式和接口请求公共参数。

控制面接口服务地址（Endpoint）信息：

服务名（service）	服务区域（region）	域名
vikingdb	cn-beijing	`vikingdb.cn-beijing.volcengineapi.com`

鉴权方式

获取火山 AK SK

调用控制面接口前，需获取火山引擎访问密钥（AccessKey），包括：

AK（AccessKeyID）：用于标识用户
SK（AccessKeySecret）：用于验证用户的密钥

获取 AK SK 方法可参考：访问控制-访问密钥，请妥善保管您的 AK/SK，避免泄露。

签名原理

签名是 API 请求中经过计算得到的一串编码字符串，用于身份认证和防止数据被篡改。关于火山 OpenAPI 签名的详细流程，可查看：API 签名调用指南。

签名的计算方式

签名由签名生成函数 prepare_request 基于以下参数计算而来：

参数	含义	说明
method	请求方法	影响签名计算，例如 GET、POST。
path	请求路径	例如 `/api/collection/create`。
ak	Access Key ID	标识 API 调用者。
sk	Access Key Secret	用于 HMAC-SHA256 计算签名（需保密）。
params	查询参数	适用于 GET 请求等。
data	请求体	适用于 POST、PUT 请求。
doseq	查询参数的格式控制	影响 params 的格式。

签名的时效性：与 AK/SK 不同，每个请求的签名都是独立且临时的，一个签名只能用于一次特定的请求，不能长期固定使用。

签名生成函数示例代码

签名生成函数的各语言示例代码见下方说明。
如需了解通过源码生成签名的详情，请参考签名源码示例；如需了解通过 SDK 生成签名的详情，请参考 SDK 概览。

通过 Python SDK 生成签名的示例代码

安装火山引擎程序包。
```
pip install volcengine
```

生成签名。

import json
import sys
import requests

from volcengine.auth.SignerV4 import SignerV4
from volcengine.base.Request import Request
from volcengine.Credentials import Credentials

def prepare_request(method, path, ak, sk, params=None, data=None, doseq=0):
    if params:
        for key in params:
            if (
                type(params[key]) == int
                or type(params[key]) == float
                or type(params[key]) == bool
            ):
                params[key] = str(params[key])
            # elif sys.version_info[0] != 3: # 在 Python 3.x 中，不需要这部分代码
            #     if type(params[key]) == unicode:
            #         params[key] = params[key].encode("utf-8")
            elif type(params[key]) == list:
                if not doseq:
                    params[key] = ",".join(params[key])
    r = Request()
    r.set_shema("https")
    r.set_method(method)
    r.set_connection_timeout(10)
    r.set_socket_timeout(10)
    mheaders = {
        "Accept": "application/json",
        "Content-Type": "application/json",
    }
    r.set_headers(mheaders)
    if params:
        r.set_query(params)
    r.set_path(path)
    if data is not None:
        r.set_body(json.dumps(data))
    # 生成签名
    credentials = Credentials(ak, sk, "air", "cn-north-1")
    SignerV4.sign(r, credentials)
    return r

通过 Java SDK 生成签名的示例代码。

打开火山引擎 SDK for Java 的 README，在获取与安装小节查看火山引擎 SDK for Java 的最新版本号。
安装火山引擎程序包。
请将{latest_ver}替换为火山引擎 SDK for Java 的最新版本号。例如在本文的示例中，该版本号为1.0.256。具体版本号请以您打开的页面为准。
```
<dependency>
    <groupId>com.volcengine</groupId>
    <artifactId>volc-sdk-java</artifactId>
    <version>{latest_ver}</version>
</dependency> 
```

生成签名。

package javaTest;

import java.util.List;

import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.config.RequestConfig;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

import com.volcengine.auth.ISignerV4;
import com.volcengine.auth.impl.SignerV4Impl;
import com.volcengine.model.Credentials;
import com.volcengine.service.SignableRequest;

public class sign {
  public static SignableRequest prepareRequest(String host, String path, String method, List<NameValuePair> params, String body, String ak, String sk) throws Exception {
    SignableRequest request = new SignableRequest();
    request.setMethod(method);
    request.setHeader("Accept", "application/json");
    request.setHeader("Content-Type", "application/json");
    request.setHeader("Host", "api-knowledgebase.mlp.cn-beijing.volces.com");
    request.setEntity(new StringEntity(body, "utf-8"));

    URIBuilder builder = request.getUriBuilder();
    builder.setScheme("https");
    builder.setHost(host);
    builder.setPath(path);
    if (params != null) {
      builder.setParameters(params);
    }

    RequestConfig requestConfig = RequestConfig.custom().setSocketTimeout(5000).setConnectTimeout(2000).build();
    request.setConfig(requestConfig);

    Credentials credentials = new Credentials("cn-north-1", "air");
    credentials.setAccessKeyID(ak);
    credentials.setSecretAccessKey(sk);

    // 签名
    ISignerV4 ISigner = new SignerV4Impl();
    ISigner.sign(request, credentials);

    return request;
  }

以下为通过 Go SDK 生成签名的示例代码。

安装火山引擎程序包。

go get -u github.com/volcengine/volc-sdk-golang

生成签名。

package main

import (
        "bytes"
        "fmt"
        "net/http"
        "net/url"
        "strings"
        "io/ioutil"
        "github.com/volcengine/volc-sdk-golang/base"
)

const (
        testAk = "***"
        testSk = "***"
)

func PrepareRequest(method string, path string, ak string, sk string, query url.Values, body []byte) *http.Request {
        u := url.URL{
                Scheme:   "https",
                Host:     "api-knowledgebase.mlp.cn-beijing.volces.com",
                Path:     "/api/knowledge/collection/search",
        }
        if query != nil {
                u.RawQuery = query.Encode()
        }
        req, _ := http.NewRequest(strings.ToUpper(method), u.String(), bytes.NewReader(body))
        req.Header.Add("Accept", "application/json")
        req.Header.Add("Content-Type", "application/json")
        req.Header.Add("Host", "api-knowledgebase.mlp.cn-beijing.volces.com")
        credential := base.Credentials{
                AccessKeyID:     ak,
                SecretAccessKey: sk,
                Service:         "air",
                Region:          "cn-north-1",
        }
        req = credential.Sign(req)
        return req
}

以下为通过 Node.js SDK 生成签名的示例代码。

安装火山引擎程序包。
```
pnpm add @volcengine/openapi
```

生成签名。
调用函数signer生成请求体 header 后，将生成好的 header 注入到用户请求函数中。

import { Signer } from '@volcengine/openapi';
import type { RequestObj } from '@volcengine/openapi/lib/base/types';

interface Options {
  pathname: string
  method: 'GET' //'GET' ,'POST'
  body?: string // json 字符串，当且仅当 post 请求
  region: 'cn-beijing' 
  params?: Record<string, any> // 当且仅当 get 请求
}

function signer({ pathname, method, body, region, params }: Options) {
  const requestObj: RequestObj = {
   region, 
   headers: {
     Accept: 'application/json',
     'Content-type': 'application/json'
   },
   method,
   body,
   pathname,
   params,
 }

  const signer = new Signer(requestObj, 'air')
    signer.addAuthorization({
      accessKeyId: 'ak', // 替换为用户 ak
      secretKey: 'sk', // 替换为用户 sk
  })
  return requestObj.headers
}

接口请求公共参数

参数	类型	是否必填	位置	描述
Action	String	是	query	要执行的操作，例如 `ListOpenVikingCollectionUser`
Version	String	是	query	API 的版本，固定取值：`2025-06-09`

请求示例：

POST /?Action=<接口名>&Version=2025-06-09 HTTP/1.1
Host: vikingdb.cn-beijing.volcengineapi.com
Content-Type: application/json
Authorization: <火山引擎 AK/SK 签名>

{ /* 请求参数 JSON */ }

响应体公共参数

成功响应

{
    "ResponseMetadata": {
        "RequestId": "<请求 ID>",
        "Action": "<Action 名>",
        "Version": "2025-06-09",
        "Service": "vikingdb",
        "Region": "<区域>"
    },
    "Result": { /* 各接口业务响应体 */ }
}

失败响应

{
    "ResponseMetadata": {
        "RequestId": "...",
        "Action": "...",
        "Version": "...",
        "Service": "...",
        "Region": "...",
        "Error": {
            "Code": "<错误码>",
            "Message": "<错误信息，含 Request ID>"
        }
    },
    "Result": null
}

常见错误码

HTTP 状态	Error.Code	含义 / 触发场景
400	`InvalidParameter`	参数缺失、格式错误、校验不通过
400	`MissingParameter`	必填参数缺失
401	`AuthenticationError`	API Key / 签名缺失或无效
403	`AuthenticationError`	身份校验失败
403	`AccessDenied`	无权限执行该操作
403	`AgentPlanDeductNotEnabled`	账号未开启 AgentPlan 抵扣
404	`ResourceNotExist`	指定库 / 资源不存在
429	`QuotaExceeded`	超出配额 / 限流
500	`InternalError`	服务内部错误

最近更新时间：2026.09.10 22:39:10

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

控制面接口服务地址（Endpoint）信息： #

鉴权方式 #

获取火山 AK SK #

签名原理 #

签名的计算方式 #

签名生成函数示例代码 #

通过 Python SDK 生成签名的示例代码

通过 Java SDK 生成签名的示例代码。

接口请求公共参数 #

响应体公共参数 #

成功响应 #

失败响应 #

常见错误码 #

控制面接口服务地址（Endpoint）信息：

鉴权方式

获取火山 AK SK

签名原理

签名的计算方式

签名生成函数示例代码

接口请求公共参数

响应体公共参数

成功响应

失败响应

常见错误码