火山引擎向量数据库 VikingDB 支持通过 API 接口进行操作，在使用 API 接口前，需先做好以下准备工作。

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

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

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

签名是什么?

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

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

签名不像ak、sk，每个请求的签名都是独立且临时的，一个签名只能用于一次特定的请求，不能长期固定使用。

签名由什么计算而来?

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

签名生成函数prepare_request的具体代码就在本文第四小节 “4. 签名生成函数（prepare_request）” 中。

如何生成签名，进而操作VikingDB？

在本文第四小节 “4. 多种语言的签名生成函数（prepare request）” 中，我们提供了多种语言的 prepare_request 签名生成代码。此处以 Python 版本为例，演示如何用prepare_request函数生成签名，并创建数据集。

1. 保存函数：保存以下代码，并将代码文件命名为volc_auth.py。这个代码文件是用于生成 API 请求签名的，它会在后续代码中被import导入使用，不是直接运行的代码，也无需改动内容；
2. 安装火山引擎包：终端Terminal中输入 pip install volcengine，安装火山引擎程序包；

# volc_auth.py

import json
import sys

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:
                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",
        "Host": "api-vikingdb.volces.com",
    }
    r.set_headers(mheaders)
    if params:
        r.set_query(params)
    r.set_host("api-vikingdb.volces.com")
    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

3. 运行代码：在与volc_auth.py同一个目录中，用另一个python文件保存下方代码。在代码开头填写您的AK和SK，运行后即操作VikingDB创建了一个名为"your_collection"的数据集。这里，您就完成了一次签名生成并操作VikingDB，下方有更详细的代码运作原理解释；

import requests
from volc_auth import prepare_request 
# 此处就导入了volc_auth.py中的签名生成函数prepare_request

AK = "此处填写您的ak，注意保留双引号"
SK = "此处填写您的sk，注意保留双引号"

DOMAIN = "api-vikingdb.volces.com"

# 创建 Collection
request_params = {
    "collection_name": "your_collection",
    "description": "这是一个用例，展示如何使用prepare_request函数生成签名，并操作VikingDB创建数据集",
    # 声明主键
    "primary_key": "id",
    # 定义声明各个字段
    "fields": [
        {
            "field_name": "id",
            "field_type": "int64",
            "default_val": 0,
        },
        {"field_name": "vector_field", "field_type": "vector", "dim": 64}
        # 其他字段已省略
    ],
}

# 调用 prepare_request 生成请求并完成签名
info_collection_req = prepare_request(
    method="POST",
    path="/api/collection/create",
    ak=AK,
    sk=SK,
    data=request_params,
)
# 完成请求
r = requests.request(
    method=info_collection_req.method,
    url="https://{}{}".format(DOMAIN, info_collection_req.path),
    headers=info_collection_req.headers,
    params=info_collection_req.query,
    data=info_collection_req.body,
)

# 打印请求结果
print(r.text)

4. 代码解释：该代码开头，from volc_auth import prepare_request 就从volc_auth.py中导入了prepare_request 函数，用于生成签名。info_collection_req获取了 prepare_request 函数生成的签名，并用于requests.request的请求（签名就在headers=info_collection_req.headers里面传递了）；
5. 更多操作：使用prepare request生成签名完成更多操作，可参考核心流程。更多语言prepare request函数详见下方。

以下有Python、GO、Java、Node.js这几种语言的签名生成函数，供您参考。

Python 语言 SDK 生成签名

1. 安装火山引擎程序包。

   pip install volcengine

2. 生成签名。

   # volc_auth.py
   
   import json
   import sys
   
   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:
                   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",
           "Host": "api-vikingdb.volces.com",
       }
       r.set_headers(mheaders)
       if params:
           r.set_query(params)
       r.set_host("api-vikingdb.volces.com")
       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
   

GO 语言 SDK 生成签名

1. 安装火山引擎程序包。

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

2. 生成签名。

   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-vikingdb.volces.com",
                   Path:     path,
           }
           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-vikingdb.volces.com")
           credential := base.Credentials{
                   AccessKeyID:     ak,
                   SecretAccessKey: sk,
                   Service:         "air",
                   Region:          "cn-north-1",
           }
           req = credential.Sign(req)
           return req
   }
   
   func main() {
           body := []byte(`{"collection_name":"test_no_vector_collection"}`)
           req := PrepareRequest("GET", "/api/collection/info", testAk, testSk, nil, body)
           fmt.Printf("%+v\n", req)
           // 发送请求
           client := &http.Client{}
           resp, err := client.Do(req)
           if err != nil {
                   fmt.Println("Error sending request:", err)
                   return
           }
           defer resp.Body.Close()
   
           rb, _ := ioutil.ReadAll(resp.Body)
           fmt.Println(string(rb))
   }
   

Java语言 SDK 生成签名

1. 安装火山引擎程序包。

   <dependency>
       <groupId>com.volcengine</groupId>
       <artifactId>volc-sdk-java</artifactId>
       <version>最新版本</version>
   </dependency> 
   

2. 生成签名

   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", host);
       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;
     }
   
     public static void main(String[] args) throws Exception {
       String host = "api-vikingdb.volces.com";
       String path = "/api/collection/info";
       String method = "GET";
       String query = "collection_name = test_collection";
       String body = null;
       String ak = "your_ak_on_volcengine"; // 替换为您的 Access Key
       String sk ="your_sk_on_volcengine"; // 替换为您的 Secret Key
       
       SignableRequest request = prepareRequest(host, path, method, null, body, ak, sk);
       System.out.println(request.getURI());
   
       HttpClient client = HttpClients.createDefault();
       HttpResponse response = client.execute(request);
   
       int statusCode = response.getStatusLine().getStatusCode();
       String content = EntityUtils.toString(response.getEntity());
   
       System.out.println(statusCode);
       System.out.println(content);
     }
   }
   

Node.js语言 SDK 生成签名

1. 安装火山引擎程序包。

pnpm add @volcengine/openapi

2. 生成签名

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

interface Options {
  pathname: string
  method: 'GET' | 'POST'
  body?: string // json 字符串，当且仅当 post 请求
  region: 'cn-beijing' | 'cn-shanghai'
  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
}

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

签名过程说明详情请参考 签名过程Demo，通过源码生成签名详情请参考 签名源码示例，通过 SDK 生成签名详情请参考 SDK概览。