您通过 HTTP 请求来调用火山引擎云拨测（Cloud Detect）的 API。

在发送 HTTP 请求前，您需要理解以下内容：

• 请求结构。
• 公共参数。
• 请求鉴权。

请求结构

API 请求的结构包含以下内容：

• API 服务地址。
• 通讯协议。
• 请求方法。
• 请求参数。

API 服务地址

云拨测的服务地址是 cloud-detect.volcengineapi.com。

通讯协议

您可以使用 HTTP 协议或 HTTPS 协议发送请求。推荐您使用 HTTPS 协议，其安全性更高。

请求方法

云拨测的 API 全部使用 POST 请求，您必须在请求头中指定 Content-Type: application/json。

请求参数

请求参数包括公共参数和每个 API 所特有的参数。

公共参数

公共参数是每个 API 请求必须包含的参数。如果一个 API 请求缺失公共参数，请求会失败。以下表格中的公共参数必须包含在查询字符串（query string）中。

请求鉴权的示例代码

每个请求中必须包含鉴权信息。该鉴权信息用以验证请求者的身份。

Golang 示例代码

下面的示例代码演示了如何基于 Golang 实现请求鉴权，并使用生成的签名调用 GetOlapData API。

在运行示例代码之前，您需要 获取您账号的 Access Key ID 和 Secret Access Key。然后，您需要分别将 Access Key ID 和 Secret Access Key 的值传入示例代码中的 AccessKey 常量和 SecretAccessKey 常量。

package main
import (
    "bytes"
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
    "strings"
    "time"
)
const Version = "2023-08-31"
const Service = "cloud_detect"
const Region = "cn-north-1"
const Host = "cloud-detect.volcengineapi.com"
// 传入您的 Access Key ID
const AccessKey = "ak"
// 传入您的 Secret Access Key
const SecretAccessKey = "sk"
// 第一步：准备辅助函数。
// sha256非对称加密
func hmacSHA256(key []byte, content string) []byte {
    mac := hmac.New(sha256.New, key)
    mac.Write([]byte(content))
    return mac.Sum(nil)
}
// sha256 hash算法
func hashSHA256(content []byte) string {
    h := sha256.New()
    h.Write(content)
    return hex.EncodeToString(h.Sum(nil))
}
// 第二步：准备需要用到的结构体定义。
// 签算请求结构体
type RequestParam struct {
    Body      []byte
    Method    string
    Date      time.Time
    Path      string
    Host      string
    QueryList url.Values
}
// 身份证明结构体
type Credentials struct {
    AccessKeyID     string
    SecretAccessKey string
    Service         string
    Region          string
}
// 签算结果结构体
type SignRequest struct {
    XDate          string
    Host           string
    ContentType    string
    XContentSha256 string
    Authorization  string
}
// go http client
var httpClient = &http.Client{
    Timeout: time.Second * 60,
    Transport: &http.Transport{
       MaxIdleConns:    100,
       MaxConnsPerHost: 10,
       IdleConnTimeout: time.Second * 15,
    },
}
// 第三步：创建一个 云拨测 的 API 请求函数。签名计算的过程包含在该函数中。
func requestCloudDetect(method string, header map[string]string, ak string, sk string, action string, body []byte) ([]byte, error) {
    // 第四步：在requestCloudDetect中，创建一个 HTTP 请求实例。
    // 创建 HTTP 请求实例。该实例会在后续用到。
    request, _ := http.NewRequest(method, "https://"+Host+"/", bytes.NewReader(body))
    urlVales := url.Values{}
    urlVales["Action"] = []string{action}
    urlVales["Version"] = []string{Version}
    request.URL.RawQuery = urlVales.Encode()
    for k, v := range header {
       request.Header.Set(k, v)
    }
    // 第五步：创建身份证明。其中的 Service 和 Region 字段是固定的。ak 和 sk 分别代表 AccessKeyID 和 SecretAccessKey。同时需要初始化签名结构体。一些签名计算时需要的属性也在这里处理。
    // 初始化身份证明
    credential := Credentials{
       AccessKeyID:     ak,
       SecretAccessKey: sk,
       Service:         Service,
       Region:          Region,
    }
    // 初始化签名结构体
    requestParam := RequestParam{
       Body:      body,
       Host:      request.Host,
       Path:      "/",
       Method:    request.Method,
       Date:      time.Now().UTC(),
       QueryList: request.URL.Query(),
    }
    // 第六步：接下来开始计算签名。在计算签名前，先准备好用于接收签算结果的 signResult 变量，并设置一些参数。
    // 初始化签名结果的结构体
    xDate := requestParam.Date.Format("20060102T150405Z")
    shortXDate := xDate[:8]
    XContentSha256 := hashSHA256(requestParam.Body)
    contentType := "application/json"
    signResult := SignRequest{
       Host:           requestParam.Host, // 设置Host
       XContentSha256: XContentSha256,    // 加密body
       XDate:          xDate,             // 设置标准化时间
       ContentType:    contentType,       // 设置Content-Type 为 application/json
    }
    // 第七步：计算 Signature 签名。
    signedHeadersStr := strings.Join([]string{"content-type", "host", "x-content-sha256", "x-date"}, ";")
    canonicalRequestStr := strings.Join([]string{
       requestParam.Method,
       requestParam.Path,
       request.URL.RawQuery,
       strings.Join([]string{"content-type:" + contentType, "host:" + requestParam.Host, "x-content-sha256:" + XContentSha256, "x-date:" + xDate}, "\n"),
       "",
       signedHeadersStr,
       XContentSha256,
    }, "\n")
    hashedCanonicalRequest := hashSHA256([]byte(canonicalRequestStr))
    credentialScope := strings.Join([]string{shortXDate, credential.Region, credential.Service, "request"}, "/")
    stringToSign := strings.Join([]string{
       "HMAC-SHA256",
       xDate,
       credentialScope,
       hashedCanonicalRequest,
    }, "\n")
    kDate := hmacSHA256([]byte(credential.SecretAccessKey), shortXDate)
    kRegion := hmacSHA256(kDate, credential.Region)
    kService := hmacSHA256(kRegion, credential.Service)
    kSigning := hmacSHA256(kService, "request")
    signature := hex.EncodeToString(hmacSHA256(kSigning, stringToSign))
    signResult.Authorization = fmt.Sprintf("HMAC-SHA256 Credential=%s, SignedHeaders=%s, Signature=%s", credential.AccessKeyID+"/"+credentialScope, signedHeadersStr, signature)
    // 第八步：将 Signature 签名写入HTTP Header 中，并发送 HTTP 请求。
    // 设置经过签名的5个HTTP Header
    request.Header.Set("Host", signResult.Host)
    request.Header.Set("Content-Type", signResult.ContentType)
    request.Header.Set("X-Date", signResult.XDate)
    request.Header.Set("X-Content-Sha256", signResult.XContentSha256)
    request.Header.Set("Authorization", signResult.Authorization)
    resp, err := httpClient.Do(request)
    if err != nil {
       return nil, err
    }
    body, err = ioutil.ReadAll(resp.Body)
    if err != nil {
       return nil, err
    }
    return body, nil
}
/* main.go */
func main() {
    // 获取即席分析数据
    payload := map[string]interface{}{
       "start_time":  1695020304,
       "end_time":    1695279504,
       "granularity": "hour",
       "filters":     nil,
       "groups": []map[string]interface{}{
          {"key": "timestamp"},
       },
       "measures": []map[string]interface{}{
          {"key": "success.proportion"},
       },
    }
    body, _ := json.Marshal(payload)
    responseBody, err := requestCloudDetect("POST", map[string]string{}, AccessKey, SecretAccessKey, "GetOlapData", body)
    if err != nil {
       fmt.Printf("do request failed: %v", err)
       return
    }
    // 打印输出的结果
    fmt.Println(string(responseBody))
}

请求鉴权算法

您可以使用以下任一方法提供鉴权信息。推荐您使用方法一。

（推荐）方法一：在请求头中包含鉴权信息

您需要在请求头中包含以下参数：

HMAC-SHA256 Credential = {AccessKey}/{ShortDate}/{Region}/{Service}/{Request}, SignedHeaders={SignedHeaders}, Signature={Signature}

方法二：在查询字符串中包含鉴权信息

您需要在查询字符串中包含以下查询参数。

X-Credential

X-Credential 的伪代码结构如下：

{AccessKey}/{ShortDate}/{Region}/{Service}/{Request}

关于 X-Credential伪代码中参数的说明，参见伪代码中参数的说明。

签名计算方式

本章节主要介绍签名是如何计算的。

• 本章节的伪代码中的 HMAC 方法使用的是 HMAC-SHA256 算法。
• 本章节的伪代码中的 HexEncode 方法将字符串转换为十六进制编码格式的字符串。

签名参数 Signature 是基于 kSigning 和 StringToSign 参数计算而来的。Signature 的伪代码如下：

Signature = HexEncode(HMAC(kSigning, StringToSign))

kSigning

kSigning 表示用来计算签名的密钥。要计算 kSigning，您必须先获取您账号的 Access Key ID 和 Secret Access Key，然后使用以下伪代码生成 kSigning。

kSecret = <Your Access Key Secret>
kDate = HMAC(kSecret, ShortDate)
kRegion = HMAC(kDate, Region)
kService = HMAC(kRegion, Service)
kSigning = HMAC(kService, "request")

关于 kSigning 伪代码中参数的说明，参见伪代码中参数的说明。

StringToSign

StringToSign 表示用来计算签名的签名字符串。StringToSign 的伪代码如下：

// Hash 函数使用 SHA256 算法
StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + HexEncode(Hash(CanonicalRequest))

关于 StringToSign 伪代码中 Algorithm 和 RequestDate 参数的说明，参见伪代码中参数的说明。StringToSign 伪代码中其他参数的说明如下。

CredentialScope

CredentialScope 表示凭证范围。CredentialScope 的伪代码如下：

{ShortDate}/{Region}/{Service}/{Request}

关于 CredentialScope 伪代码中参数的说明，参见伪代码中参数的说明。

CanonicalRequest

CanonicalRequest 表示规范的请求。CanonicalRequest 的伪代码如下：

HTTPRequestMethod + '\n' + CanonicalURI + '\n' + CanonicalQueryString + '\n' + CanonicalHeaders + '\n' + SignedHeaders + '\n' + HexEncode(Hash(RequestPayload))

CanonicalRequest 伪代码中参数的说明如下：

• HTTPRequestMethod：表示请求方法。
• CanonicalURI：表示请求的 URI。
• CanonicalQueryString：表示规范的查询字符串。CanonicalQueryString 的值是通过以下规则生成的：
  • 按参数名称对查询参数进行升序排序。
• CanonicalHeaders：表示规范的请求头。CanonicalHeaders 是通过以下步骤生成的：
  • 将参与签名计算的请求头参数的名称转化成小写字母。
  • 在字符级别对这些名称进行升序排序。
  • 以 key-value 的格式拼接这些请求头参数。key 是请求头参数的名称，value 是请求头参数的值。
  • 在每个请求头参数后添加换行符（\n）。
• SignedHeaders：参见伪代码中参数的说明。
• HexEncode(Hash(RequestPayload))：表示一个计算值。该值是通过对请求正文中 payload 的值应用 SHA256 哈希算法计算得到的。

伪代码中参数的说明

以下表格包含了本文中多个伪代码中参数的说明。

请求示例

POST https://cloud-detect.volcengineapi.com?Action=GetOlapData&Version=2023-08-31

Content-Type: application/json
X-Date: 20230116T073702Z
Authorization: HMAC-SHA256 Credential=AKLTMjYxYTZmYWU4ZWYzNGI2NDg8NTUxODE1ZGVhNmIxZmQ/20230116/cn-north-1/cloud_detect/request, SignedHeaders=x-content-sha256;x-date, Signature=5a394ce80456c7cdf989c28bd638807c8ead386eb15dd36e39952f405380aef2
ServiceName: cloud_detect