DataWorks：調用API

調用前提：三要素缺一不可

在調用任何資料服務 API 之前，您需要確保以下三個條件全部滿足：

三者的關係可以理解為：API 是“門”，App 是“身份證”，授權是“通行證”。只有同時出示合法的身份證和對應的通行證，才能通過這扇門。

建立應用（App 身份）

應用（App）是您調用 API 時的身份憑證載體。每個 App 擁有一組獨立的認證資訊（AppKey、AppSecret、AppCode），相當於該身份的“帳號和密碼”。

自動建立的預設應用

當您在 DataWorks 中首次發布 API 時，系統會自動在 API Gateway中建立一個與工作空間同名的應用（App），並將該工作空間下的所有 API 自動授權給這個預設應用。這意味著：

• 同一工作空間內的成員，可以直接使用預設 App 的憑據調用本空間下的 API，無需額外授權。

• 預設應用的認證資訊可在資料服務控制台的API調用頁面查看。

手動建立應用

如果需要對不同的調用方進行流量隔離或許可權區分，您可以在 API Gateway控制台中手動建立新的應用：

1. 登入API Gateway控制台。

2. 在左側導覽列，選擇應用管理。

3. 單擊建立應用，輸入應用程式名稱和描述。

4. 建立成功後，系統會為該應用產生一組 AppKey、AppSecret 和 AppCode。

授權流程

授權是指將某個 API 的調用許可權授予指定的應用（App）。只有建立了授權關係的 App，才能使用其憑據成功調用對應的 API。

授權給其他帳號

當您需要將 API 開放給其他阿里雲帳號下的工作空間調用時，需要進行跨帳號授權：

1. 登入DataWorks控制台，切換至目標地區後，單擊左側導覽列的資料分析與服務 > 資料服務，在下拉框中選擇對應工作空間後單擊進入資料服務。

2. 進入資料服務頁面，單擊頂部功能表列的服務管理，進入API 管理頁面。

3. 在發佈的API頁簽下，找到目標 API，單擊其後的授權。

4. 在API 授權對話方塊中，配置以下參數：

   

   參數	說明
   API名稱	待授權的 API 名稱，預設不可修改。
   要授權的雲帳號 ID	需要獲得該 API 呼叫許可權的阿里雲帳號 ID。您可以在頁面查看帳號 ID。
   要授權的工作空間	選擇目標阿里雲帳號下的工作空間名稱。
   授權有效期	選擇授權的有效期間限（詳見下文）。

5. 單擊確認，完成授權。

授權有效期間

授權有效期間決定了被授權方可以調用 API 的時間範圍：

查看已授權與被授權的 API

在API 管理頁面，您可以從兩個維度查看授權狀態：

查看獲得授權的 API（我被授權了哪些 API）

單擊獲得授權的API頁簽，查看所有其他帳號授權給您的 API 列表。在此頁面您可以：

• 單擊測試，線上測試獲得授權的 API。詳情請參見測試API。

• 單擊刪除，主動放棄某個 API 的調用授權。

查看授權給他人的 API（我授權了哪些 API 給別人）

單擊授權給他人的API頁簽，查看您授權給其他工作空間的 API 列表。在此頁面您可以：

• 單擊測試，線上測試已授權的 API。

• 單擊授權管理，取消或修改對特定工作空間的授權。

三種授權情境

根據團隊規模和安全管理需求的不同，API 授權的粒度也有所差異。以下三種情境覆蓋了最常見的授權方案。

情境一：同一工作空間，共用一個 App

情境描述：同一個 DataWorks 工作空間下的所有成員，共同使用工作空間預設建立的同一個應用（App）來調用 API。

適用情況：團隊規模較小、成員之間信任度高；不需要區分不同成員的調用流量來源；快速啟動，最簡配置。

工作方式：DataWorks 在 API 發布時自動建立與工作空間同名的 App，並自動將工作空間內的所有 API 授權給該 App。工作空間內的所有成員共用這組 AppKey、AppSecret 和 AppCode。

優勢：零配置，開箱即用。劣勢：無法區分具體是哪個成員發起的調用；如果某個成員的憑據泄露，影響範圍為整個工作空間。

情境二：每個 RAM 使用者使用獨立的 App

情境描述：企業內的每個 RAM 使用者（子帳號），各自在 API Gateway中建立獨立的應用（App），分別獲得 API 的調用授權。

適用情況：需要精確追蹤每個使用者的 API 呼叫行為；需要對不同使用者佈建不同的限流策略；安全合規要求較高，需要做到“一人一憑據”。

工作方式：每個 RAM 使用者登入 API Gateway控制台各自建立自己的 App；API 管理員將 API 分別授權給每個使用者的 App；每個使用者使用自己 App 的憑據調用 API。

優勢：調用行為可追溯到個人，安全隔離性強，憑據泄露影響範圍最小。劣勢：管理開銷較大，每新增一個使用者都需要建立 App 和配置授權。

情境三：多個 RAM 使用者分組，每組共用一個 App

情境描述：將多個 RAM 使用者按業務職能或團隊劃分為若干組，每群組成員共同使用同一個應用（App）來調用 API。

適用情況：團隊規模較大，按部門或專案組劃分；需要區分不同業務線的調用流量，但不需要精確到個人；在管理成本與安全性之間取得平衡。

工作方式：按業務組建立對應數量的 App；API 管理員將 API 授權給各業務組的 App；組內成員共用本組 App 的憑據。

優勢：管理粒度適中，既能區分業務來源又不會產生過多管理開銷。劣勢：組內成員之間無法進一步區分。

情境選型建議

三類憑據辨析：避免混淆

資料服務涉及三類完全不同的認證憑據，用途、來源和使用情境完全不同，請務必區分：

一句話記憶：AccessKey 管“連資料來源”，AppKey 管“調 API”，RAM 管“進控制台”。三者各司其職，互不替代。

混淆一：“API 呼叫報 403，但我有 RAM 管理員權限” — RAM 許可權控制的是 DataWorks 控制台操作許可權，而不是 API 呼叫許可權。API 呼叫許可權由 App 授權控制。即使您是 RAM 管理員，調用 API 時仍然需要一個已被授權的 App 的 AppKey/AppSecret。

混淆二：“資料來源配置的 AccessKey 和 API 呼叫的 AppKey 是同一個嗎？” — 不是。AccessKey 用於資料服務後台串連資料來源；AppKey 用於調用方調用 API。兩者完全獨立。

混淆三：授權頁面的“雲帳號 ID”填什嗎？ — 授權頁面要求填寫的是阿里雲帳號 ID（純數字），而非 RAM 使用者名稱或登入郵箱。擷取方式：登入帳號管理頁面，在安全設定中查看帳號 ID。

認證方式對比

API Gateway支援兩種身份認證方式。資料服務預設會為工作空間下的 API 添加“阿里雲 APP 認證”，調用方可以根據安全需求選擇具體的認證方式。

簡單認證（AppCode）

調用者僅需在 HTTP 要求的 Header 中添加 AppCode 即可完成身份認證，無需進行簽名計算。

請求樣本：

GET /api/v1/users?name=test HTTP/1.1
Host: your-api-endpoint.cn-shanghai.alicloudapi.com
Authorization: APPCODE 3f963a8e1cd7492bbd8a5e2e5e4c****

簽名認證（AppKey + AppSecret）

調用者需要使用 AppSecret 對請求內容進行 HMAC-SHA256 簽名計算，將 AppKey 和簽名值添加到請求 Header 中。API Gateway收到請求後使用相同的 AppSecret 重新計算簽名，對比簽名是否一致來驗證調用者身份。

請求樣本（Header 部分）：

X-Ca-Key: 12345678
X-Ca-Signature: BASE64_ENCODED_SIGNATURE
X-Ca-Timestamp: 1741593600000
X-Ca-Nonce: unique-uuid-string
X-Ca-Signature-Headers: X-Ca-Key,X-Ca-Nonce,X-Ca-Timestamp

兩種方式對比

簽名演算法詳解

簽名認證基於 HMAC-SHA256 演算法，核心流程如下：

簽名流程概覽

1. 構造正常化請求字串（StringToSign）：將 HTTP 方法（GET/POST）、Accept Header、Content-MD5（請求 Body 的 MD5 值）、Content-Type、Date、參與簽名的自訂 Header（X-Ca-*，按字母序排列）以及正常化 URL（路徑 + 排序後的查詢參數）依次拼接。

2. 使用 HMAC-SHA256 計算簽名：Signature = Base64(HMAC-SHA256(AppSecret, StringToSign))

3. 將簽名資訊添加至請求 Header：包括 X-Ca-Key（AppKey）、X-Ca-Signature（簽名值）、X-Ca-Timestamp（毫秒級時間戳記）、X-Ca-Nonce（UUID，防重放）和 X-Ca-Signature-Headers（參與簽名的 Header 列表）。

關鍵注意事項

在實現簽名演算法時，以下細節容易出錯：

• 參數排序：URL 查詢參數和簽名 Header 必須按 Key 的字母序（ASCII 碼序）排列。

• URL 編碼：參數值中的特殊字元（空格、中文等）需要進行 URL 編碼。

• 分行符號：StringToSign 中各行之間使用 \n（LF）分隔，不能使用 \r\n（CRLF）。

• 空值處理：無 Body 時 Content-MD5 為空白字串（不是 null），Accept 等 Header 不存在時也用Null 字元串。

• 時間戳記精度：X-Ca-Timestamp 為毫秒級時間戳記，用戶端與伺服器時間偏差不能超過 15 分鐘。

• Nonce 唯一性：每次請求必鬚生成唯一的 UUID 作為 X-Ca-Nonce，重複使用會觸發重放攻擊攔截。

查看認證憑據

在成功建立應用並獲得授權後，您需要擷取 AppKey、AppSecret 或 AppCode 來進行 API 呼叫。資料服務提供了便捷的憑據查看入口。

通過資料服務控制台查看

1. 登入DataWorks控制台，切換至目標地區後，單擊左側導覽列的資料分析與服務 > 資料服務，在下拉框中選擇對應工作空間後單擊進入資料服務。

2. 在資料服務頁面，單擊頁面頂部功能表列的服務管理。

3. 在左側導覽列，單擊API調用。

4. 在API調用頁面，您可以查看和複製以下認證資訊：AppKey（應用唯一標識）、AppSecret（用於簽名認證，請妥善保管）、AppCode（用於簡單認證）。

通過 API Gateway控制台查看：登入 API Gateway控制台，在應用管理中找到目標應用，進入詳情頁查看 AppKey、AppSecret 和 AppCode。

通過 API Gateway SDK 調用

API Gateway提供了主流程式設計語言的 SDK，協助您快速整合 API 呼叫。SDK 已內建簽名演算法的實現，您無需手動計算簽名，只需提供 AppKey 和 AppSecret 即可。詳情請參見調用 API 文檔和SDK 下載與使用。

支援的 SDK 語言

使用 SDK 的優勢

相比手動構造 HTTP 要求，使用 SDK 調用有以下優勢：

• 自動簽名：SDK 內部實現了 HMAC-SHA256 簽名演算法，開發人員無需關心簽名細節。

• 自動重試：部分 SDK 內建了網路異常重試機制。

• 參數校正：SDK 會在發送請求前進行基本的參數合法性校正。

• 效能最佳化：SDK 通常使用串連池和 HTTP/2 等技術最佳化網路效能。

快速整合樣本（Java）

以下樣本展示如何使用 API Gateway Java SDK 調用資料服務 API：

// 1. 添加 Maven 依賴
// <dependency>
//     <groupId>com.aliyun.api.gateway</groupId>
//     <artifactId>sdk-core-java</artifactId>
//     <version>最新版本</version>
// </dependency>

// 2. 初始化用戶端
HttpClientBuilderParams params = new HttpClientBuilderParams();
params.setAppKey("your_app_key");
params.setAppSecret("your_app_secret");

ApacheHttpClient client = new ApacheHttpClient(params);

// 3. 構造請求
IoTApiRequest request = new IoTApiRequest();
request.setDomain("your-api-endpoint.cn-shanghai.alicloudapi.com");
request.setPath("/api/v1/query");
request.setHttpMethod("GET");
request.putQueryParam("pageSize", "10");
request.putQueryParam("pageNum", "1");

// 4. 發起調用
ApiResponse response = client.execute(request);
System.out.println("Response: " + response.getBody());

快速整合樣本（Python）

# 1. 安裝 SDK
# pip install aliyun-api-gateway-sdk

# 2. 調用 API
from com.alibaba.cloudapi.sdk.client import DefaultClient
from com.alibaba.cloudapi.sdk.model import HttpClientBuilderParams

params = HttpClientBuilderParams()
params.app_key = "your_app_key"
params.app_secret = "your_app_secret"
params.host = "your-api-endpoint.cn-shanghai.alicloudapi.com"

client = DefaultClient(params)
response = client.get(
    path="/api/v1/query",
    query_params={"pageSize": "10", "pageNum": "1"},
    headers={"Accept": "application/json"}
)

print(f"Status: {response.status_code}")
print(f"Body: {response.content}")

完整調用流程總結

從 API 發布到成功調用的完整流程：API 開發人員開發並測試 API、發布 API 至 API Gateway（自動建立預設 App 和授權）；如需跨帳號共用則手動授權給目標帳號。API 呼叫者建立 App（或使用預設 App）、擷取認證憑據（AppKey/AppSecret/AppCode）、選擇認證方式（簡單認證使用 AppCode，簽名認證使用 AppKey+AppSecret），最後通過 SDK 或 HTTP 調用 API。API Gateway驗證身份後，資料服務執行查詢並返回結果。

相關文檔

• 發布API：瞭解如何將 API 發布至 API Gateway。

• 授權API：瞭解授權操作及授權給他人的 API 管理。

• 測試API：在服務管理頁面對發行或已授權的 API 進行測試。