全部產品
Search
文件中心

Intelligent Speech Interaction:通過OpenAPI擷取Token

更新時間:Sep 29, 2026

當所用程式設計語言沒有對應的SDK,或需要自行控制相依元件時,可以直接調用OpenAPI擷取Token。本文介紹請求參數、簽名機制和響應格式,並提供Java和Python樣本。

準備訪問憑證

調用介面需要AccessKey ID和AccessKey Secret。將訪問憑證配置到運行環境的 ALIYUN_AK_ID 和 ALIYUN_AK_SECRET 環境變數中,範例程式碼從環境變數讀取憑證。

重要

AccessKey Secret和Token均為敏感資訊,不要寫入公開代碼或日誌。以下樣本會輸出包含Token的響應,整合到應用時應妥善保管。

程式碼範例

以下樣本通過HTTPS GET請求擷取Token。響應中的 Token.Id 為Token值,Token.ExpireTime 為到期時間戳記,單位為秒。

Java

使用JDK 8或更高版本,並添加以下Maven依賴。

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>3.9.1</version>
</dependency>
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.Base64;
import java.util.Map;
import java.util.StringJoiner;
import java.util.TreeMap;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

public class CreateToken {
    private static String encode(String value) throws Exception {
        return URLEncoder.encode(value, "UTF-8")
                .replace("+", "%20").replace("*", "%2A").replace("%7E", "~");
    }

    public static void main(String[] args) throws Exception {
        String accessKeyId = System.getenv("ALIYUN_AK_ID");
        String accessKeySecret = System.getenv("ALIYUN_AK_SECRET");
        if (accessKeyId == null || accessKeyId.isEmpty()
                || accessKeySecret == null || accessKeySecret.isEmpty()) {
            throw new IllegalArgumentException("Set ALIYUN_AK_ID and ALIYUN_AK_SECRET.");
        }

        String endpoint = "https://nlsmeta.ap-southeast-1.aliyuncs.com/";
        Map<String, String> parameters = new TreeMap<>();
        parameters.put("AccessKeyId", accessKeyId);
        parameters.put("Action", "CreateToken");
        parameters.put("Version", "2019-07-17");
        parameters.put("RegionId", "ap-southeast-1");
        parameters.put("Format", "JSON");
        parameters.put("SignatureMethod", "HMAC-SHA1");
        parameters.put("SignatureVersion", "1.0");
        parameters.put("SignatureNonce", UUID.randomUUID().toString());
        parameters.put("Timestamp", Instant.now().truncatedTo(ChronoUnit.SECONDS).toString());

        StringJoiner query = new StringJoiner("&");
        for (Map.Entry<String, String> entry : parameters.entrySet()) {
            query.add(encode(entry.getKey()) + "=" + encode(entry.getValue()));
        }
        String canonicalQuery = query.toString();
        String stringToSign = "GET&" + encode("/") + "&" + encode(canonicalQuery);
        Mac mac = Mac.getInstance("HmacSHA1");
        mac.init(new SecretKeySpec((accessKeySecret + "&").getBytes(StandardCharsets.UTF_8), "HmacSHA1"));
        String signature = Base64.getEncoder().encodeToString(
                mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8)));

        Request request = new Request.Builder()
                .url(endpoint + "?" + canonicalQuery + "&Signature=" + encode(signature))
                .get().build();
        OkHttpClient client = new OkHttpClient();
        try (Response response = client.newCall(request).execute()) {
            String body = response.body() == null ? "" : response.body().string();
            if (!response.isSuccessful()) {
                throw new IllegalStateException("HTTP " + response.code() + ": " + body);
            }
            System.out.println(body);
        }
    }
}

Python

使用Python 3.4或更高版本,安裝Requests庫。樣本使用Python 3.14.7。

pip install requests
import base64
import hashlib
import hmac
import os
import uuid
from datetime import datetime, timezone
from urllib.parse import quote

import requests


def encode(value):
    return quote(value, safe="-_.~")


def create_token():
    access_key_id = os.environ["ALIYUN_AK_ID"]
    access_key_secret = os.environ["ALIYUN_AK_SECRET"]
    endpoint = "https://nlsmeta.ap-southeast-1.aliyuncs.com/"
    parameters = {
        "AccessKeyId": access_key_id,
        "Action": "CreateToken",
        "Version": "2019-07-17",
        "RegionId": "ap-southeast-1",
        "Format": "JSON",
        "SignatureMethod": "HMAC-SHA1",
        "SignatureVersion": "1.0",
        "SignatureNonce": str(uuid.uuid4()),
        "Timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
    }
    canonical_query = "&".join(
        encode(key) + "=" + encode(value)
        for key, value in sorted(parameters.items())
    )
    string_to_sign = "GET&" + encode("/") + "&" + encode(canonical_query)
    signature = base64.b64encode(hmac.new(
        (access_key_secret + "&").encode("utf-8"),
        string_to_sign.encode("utf-8"), hashlib.sha1
    ).digest()).decode("ascii")
    response = requests.get(
        endpoint + "?" + canonical_query + "&Signature=" + encode(signature),
        timeout=20,
    )
    if response.status_code != 200:
        raise RuntimeError("HTTP {}: {}".format(response.status_code, response.text))
    return response.text


if __name__ == "__main__":
    print(create_token())

請求說明

介面支援GET和POST方法,使用阿里雲POP協議進行簽名。HTTP和HTTPS請求的參數相同,建議使用HTTPS。

服務地址

Endpoint:https://nlsmeta.ap-southeast-1.aliyuncs.com/,RegionId:ap-southeast-1,API版本:2019-07-17。

請求參數

名稱

類型

必選

說明

AccessKeyId

String

是

AccessKey ID。

Action

String

是

介面名稱,固定為 CreateToken。

Version

String

是

API版本,固定為 2019-07-17。

Format

String

否

響應格式。設為 JSON 可返回JSON;不設定時返回XML。本文樣本設定為 JSON。

RegionId

String

是

地區ID,固定為 ap-southeast-1。

Timestamp

String

是

請求時間戳記,使用UTC時間,格式為 yyyy-MM-dd'T'HH:mm:ss'Z',例如 2019-04-03T06:15:03Z。實際請求使用目前時間。

SignatureMethod

String

是

簽名演算法,固定為 HMAC-SHA1。

SignatureVersion

String

是

簽名演算法版本,固定為 1.0。

SignatureNonce

String

是

唯一隨機字串,用於防止重放攻擊,每次請求不得重複。可使用UUID,例如 8d1e6a7a-f44e-40d5-aedb-fe4a1c80f434。

Signature

String

是

根據除Signature外的全部請求參數計算得到的簽名,計算方法見下文簽名機制。

要求標頭與參數傳遞

GET請求將參數放在URL查詢字串中;POST請求將參數放在請求體中。

要求標頭

必選

說明

Host

否

服務網域名稱,通常由HTTP用戶端根據Endpoint自動化佈建。

Accept

否

可設定為 application/json,表示用戶端接受JSON響應。未設定時通常為 */*。響應格式通過Format參數指定。

Content-Type

POST必選

POST請求設定為 application/x-www-form-urlencoded。

請求格式如下,<encoded-parameters> 表示URL編碼後的參數字串,包含Signature。POST請求計算簽名時使用 POST,不能直接複用GET簽名。

GET

GET /?<encoded-parameters> HTTP/1.1
Host: <endpoint-host>
Accept: application/json

POST

POST / HTTP/1.1
Host: <endpoint-host>
Accept: application/json
Content-Type: application/x-www-form-urlencoded

<encoded-parameters>

簽名機制

每個請求都必須攜帶簽名。用戶端使用AccessKey Secret計算HMAC-SHA1訊息認證碼;服務端根據請求中的AccessKey ID尋找對應密鑰,並校正簽名,以驗證身份和請求完整性。

構造正常化請求字串

  1. 排除Signature參數,按參數名進行區分大小寫字典排序。

  2. 對參數名和參數值分別進行UTF-8 URL編碼:

    • A-Z、a-z、0-9、-、_、.、~ 不編碼。

    • 其他字元按其UTF-8位元組編碼為 %XY,例如雙引號編碼為 %22。

    • 空格編碼為 %20,不能編碼為加號 +。

  3. 使用 = 串連編碼後的參數名和值,再用 & 串連各參數對。第一個參數前不加 &。

percentEncode(name1)=percentEncode(value1)&percentEncode(name2)=percentEncode(value2)

Java的 URLEncoder 按表單規則編碼,需將編碼結果中的 + 替換為 %20、* 替換為 %2A、%7E 替換為 ~。

構造待簽名字串

將大寫HTTP方法、編碼後的請求路徑 / 和再次編碼的正常化請求字串用 & 串連。

StringToSign = HTTPMethod + "&" + percentEncode("/") + "&" + percentEncode(CanonicalizedQueryString)

計算並添加簽名

  1. 在AccessKey Secret末尾追加 &,作為HMAC-SHA1密鑰。

  2. 使用UTF-8編碼的密鑰和待簽名字串計算HMAC-SHA1,再對結果進行Base64編碼。

  3. 對Base64結果進行URL編碼,以 Signature=<encoded-signature> 的形式加入請求參數。

Signature = Base64(HMAC-SHA1(AccessKeySecret + "&", StringToSign))

簽名校正樣本

以下固定參數用於離線核對簽名實現。AccessKey為虛擬值,Timestamp已到期,不能用於實際擷取Token。

AccessKeyId: my_access_key_id
AccessKeySecret: my_access_key_secret
Action: CreateToken
Format: JSON
SignatureMethod: HMAC-SHA1
SignatureVersion: 1.0
SignatureNonce: b924c8c3-6d03-4c5d-ad36-d984d3116788
Timestamp: 2019-04-18T08:32:31Z
HTTPMethod: GET

正常化請求字串:

AccessKeyId=my_access_key_id&Action=CreateToken&Format=JSON&RegionId=ap-southeast-1&SignatureMethod=HMAC-SHA1&SignatureNonce=b924c8c3-6d03-4c5d-ad36-d984d3116788&SignatureVersion=1.0&Timestamp=2019-04-18T08%3A32%3A31Z&Version=2019-07-17

待簽名字串:

GET&%2F&AccessKeyId%3Dmy_access_key_id%26Action%3DCreateToken%26Format%3DJSON%26RegionId%3Dap-southeast-1%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3Db924c8c3-6d03-4c5d-ad36-d984d3116788%26SignatureVersion%3D1.0%26Timestamp%3D2019-04-18T08%253A32%253A31Z%26Version%3D2019-07-17

Base64簽名:

4TdrOuLHXJU+5C6s927Wkq2h+wc=

URL編碼後的簽名參數:

Signature=4TdrOuLHXJU%2B5C6s927Wkq2h%2Bwc%3D

響應說明

以下說明適用於 Format=JSON。GET和POST方法的響應格式相同。

成功響應

HTTP狀態代碼為200,主要欄位如下。

欄位

類型

說明

Token

Object

包含Token值和到期時間。

Token.Id

String

Token值。

Token.ExpireTime

Long

Token的到期時間,以Unix時間戳記表示,單位為秒;不是有效時間長度。例如1553825814對應UTC時間2019-03-29 02:16:54,Token在該時間之前有效。

響應中的Token欄位樣本如下。

{
  "Token": {
    "Id": "<token>",
    "ExpireTime": 1553825814
  }
}

失敗響應

HTTP狀態代碼為非200,根據Code和Message檢查請求參數。

欄位

類型

說明

RequestId

String

請求ID,可用於排查問題。

Code

String

錯誤碼。

Message

String

錯誤說明。

例如,AccessKey ID不存在時,返回HTTP 404,響應中包含以下欄位。

{
  "RequestId": "<request-id>",
  "Code": "InvalidAccessKeyId.NotFound",
  "Message": "Specified access key is not found."
}

相關文檔