API简介 | 大装置帮助中心
跳到主要内容

API简介

下载PDF文档
# 概述 OpenAPI是SenseCore对外提供统一规范产品API服务的入口，为机构、服务商以及广大开发者提供统一标准、统一流程的API调用服务。 OpenAPI提供了REST（Representational State Transfer）风格API，支持您通过HTTPS请求调用，它使用统一的接口和标准的 HTTP 方法来进行资源的创建、读取、更新和删除操作。

使用指南​

API使用​

第一步：创建AccessKey​

  1. 登录用户控制台，在头像-下拉菜单中点击 AccessKey 访问秘钥，进入账号中心-AccessKey 访问秘钥页。
  2. 在AccessKey 访问秘钥页中，点击创建访问秘钥，创建一对属于当前账号的访问秘钥。秘钥对由 AccessKey ID 和 AccessKey Secret 组成，每个用户最多支持创建两对密钥对，创建后请注意即时保存 AccessKey Secret 信息。

第二步：查看API文档​

  1. 在顶导航中，点击文档，进入帮助中心。
  2. 在文档中心中，选择并展开需要查看的产品服务名称，点击 API 参考查看相关 API 说明文档。

第三步：依据接口文档实现业务逻辑​

您也可以点击接口文档中的调试接口按钮，进入 API 中心进行相关接口调试。

API调试​

第一步：复制 Bearer 令牌​

  1. 在顶导航-头像下拉菜单中点击账号安全设置。
  2. 点击复制按钮，复制 Bearer 令牌。

第二步：使用 Bearer 令牌进行 API 调试​

  1. 将复制好的 Bearer令牌粘贴到 API 调试页中的 Beaer Token 填写框中。
  2. 开始进行 API 调试。

访问端点​

详情请查看各个产品的OpenAPI说明文档

如何调用API​

请求内容​

请求URI​

请求URI由如下部分组成。

{scheme} :// {Endpoint} / {resource-path} ? {query-string}

尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。

  • scheme：表示用于传输请求的协议，当前所有API均采用HTTPS协议。
  • Endpoint：指定承载REST服务端点的服务器域名或IP，不同服务不同区域的Endpoint不同
  • resource-path：资源路径，也即API访问路径。
  • query-string：查询参数，是可选部分，并不是每个API都有查询参数。查询参数前面需要带一个“？”，形式为“参数名=参数取值”，例如“limit=10”，表示查询不超过10条数据。

请求方法​

HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。

  • GET：请求服务器返回指定资源。
  • PUT：请求服务器更新指定资源。
  • POST：请求服务器新增资源或执行特殊操作。
  • DELETE：请求服务器删除指定资源，如删除对象等。
  • HEAD：请求服务器资源头部。
  • PATCH：请求服务器更新资源的部分内容。当资源不存在的时候，PATCH可能会去创建一个新的资源。

请求消息头​

附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。

请求中需要添加 Date、Host 和 Authorization 公共请求头。

其中，Date 表示请求生成时间，Authorization 表示请求认证信息。Host 表示请求目标域名，通常由 HTTP 客户端根据请求 URL 自动生成。

请求消息体​

请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。

每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。

认证鉴权​

访问凭证​

Access Key（访问密钥）是一种用于身份验证和授权的凭据，用于访问和使用各种服务和API。Access Key 通常由用户在用户控制台-安全中心生成和管理。

Access Key 由两部分组成：Access Key ID（访问密钥标识符）和 Secret Access Key（访问密钥密钥）。Access Key ID 是用于标识访问密钥的唯一标识符，而 Secret Access Key 则是用于对请求进行签名和身份验证的机密密钥。

使用 Access Key 进行身份验证可以提供一定的安全性，因为只有持有正确的 Access Key 才能通过身份验证并获得访问权限。Access Key 通常需要妥善保管，避免泄露给未经授权的人员或应用程序。

在使用某些服务或API时，需要在请求中包含 Access Key 相关的信息，以证明身份并获得授权。具体的使用方法和要求取决于所使用的服务或API的提供商。通常，Access Key 相关的信息需要作为请求的一部分，可以通过请求头、请求参数或请求体的形式进行传递。

请求签名​

平台提供了安全的签名校验方式，API访问中需要生成Http Authorization Header, 只有通过签名校验的请求才能到达业务后端。


 Authorization: hmac accesskey="{accesskey}", algorithm="{algorithm}", headers="{headers}", signature="{signature}"

参数名称类型说明
accesskeystring用户的access key id
algorithmstringhmac-sha256
headersstring参与签名计算的字段，当前为 date host @request-target
signaturestring请求签名

计算签名​

将请求时间、目标主机和请求目标加入待签名字符串：

StringToSign =
    "date: {Date}" + \n +
    "host: {Host}" + \n +
    "@request-target: {lowercase-method} {path-and-query}"
  • Date：使用 HTTP-date 格式的 UTC 时间，例如 Wed, 26 Jul 2023 11:36:03 GMT。
  • Host：请求 URL 中的主机名；如果 URL 显式包含端口，则端口也必须参与签名。
  • lowercase-method：小写 HTTP 方法，例如 get、post。
  • path-and-query：请求路径及原始查询字符串，不包含 scheme 和 Host；没有查询参数时只使用路径。
  • 三行内容使用单个换行符 \n 连接，末尾不追加换行符。

访问示例​


package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "strings"
    "time"
)

func hmacSHA256(secret, message string) string {
    key := []byte(secret)
    h := hmac.New(sha256.New, key)
    h.Write([]byte(message))
    return base64.StdEncoding.EncodeToString(h.Sum(nil))
}

func main() {
    accessKey := "YOUR_ACCESS_KEY_ID"
    secretKey := "YOUR_ACCESS_KEY_SECRET"
    requestURL := "https://iam.sensecoreapi.dev/iam/idp/v1/users:getProfile"
    method := http.MethodGet

    date := time.Now().UTC().Format(http.TimeFormat)
    urlInfo, err := url.Parse(requestURL)
    if err != nil {
        panic(err)
    }
    if urlInfo.Host == "" {
        panic("request URL does not contain a host")
    }

    pathAndQuery := urlInfo.EscapedPath()
    if pathAndQuery == "" {
        pathAndQuery = "/"
    }
    if urlInfo.RawQuery != "" {
        pathAndQuery += "?" + urlInfo.RawQuery
    }

    signedHeaders := "date host @request-target"
    stringToSign := strings.Join([]string{
        "date: " + date,
        "host: " + urlInfo.Host,
        fmt.Sprintf("@request-target: %s %s", strings.ToLower(method), pathAndQuery),
    }, "\n")
    signature := hmacSHA256(secretKey, stringToSign)
    authorization := fmt.Sprintf(
        `hmac accesskey="%s", algorithm="hmac-sha256", headers="%s", signature="%s"`,
        accessKey, signedHeaders, signature,
    )

    req, err := http.NewRequest(method, requestURL, nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Date", date)
    req.Header.Set("X-Date", date)
    req.Header.Set("Authorization", authorization)

    client := &http.Client{Timeout: 30 * time.Second}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    fmt.Printf("status: %s\n%s\n", resp.Status, body)
}