DataWorks：API測試、發布與版本管理

測試開發中的 API

測試開發中的 API 是指在服務開發頁面（即開發環境）中進行測試。在測試之前，您需要先通過嚮導模式或指令碼模式產生 API，或通過註冊已有服務的方式註冊 API。

操作步驟：

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

2. 在左側 API 列表中，雙擊要測試的 API 名稱，進入 API 編輯頁面。

3. 在 API 編輯頁面中，找到並單擊測試按鈕，開啟API測試對話方塊。

4. 在對話方塊左側地區，為每個請求參數填入測試值。

5. 單擊開始測試，觸發 API 呼叫。

查看測試結果：

測試完成後，您可以在對話方塊右側查看以下資訊：

• 請求詳情：展示本次測試的完整請求資訊，包括請求路徑、要求標頭和請求體等內容，方便確認請求構造是否正確。

• 返回內容：展示 API 的響應資料，即實際的查詢結果。您可以對比返回內容與預期結果，確認 API 邏輯是否正確。

• 響應時長：顯示本次 API 請求的端到端響應耗時，供您評估 API 的效能表現。如果響應延遲較大，需要考慮最佳化查詢邏輯或資料來源配置。

如果測試失敗，請仔細查看返回的錯誤提示資訊，根據提示進行相應修改後重新測試。

測試發行的 API

測試發行的 API 是指在服務管理頁面（即生產環境）中進行測試，目的是驗證 API 發布後的實際運行狀態。進行此測試前，您需要先完成 API 的發佈動作。

操作步驟：

1. 在資料服務頁面，單擊頂部導覽列的服務管理。

2. 在左側導覽列中，單擊API測試。

3. 從下拉式清單中選擇需要測試的 API，確認 API 的請求參數值已配置完整。

4. 單擊開始測試，在右側查看請求詳情和返回內容。

注意事項：

• API測試頁面僅提供 API 線上測試功能，不支援通過該頁面更新 API 的正常返回樣本。

• 如果 API 配置了返回結果分頁展示，返回資料是否有序取決於底層資料來源的行為。若需要排序，可在嚮導模式下為 API 配置排序欄位，或在指令碼模式下為 SQL 代碼添加ORDER BY子句。

測試結果的解讀與最佳化建議

一次完整的 API 測試結果由三部分構成，理解各部分含義有助於快速定位問題：

當測試結果完全符合預期後，即可進入下一階段——將 API 發布至 API Gateway。

準備工作

在發布 API 之前，請確保滿足以下條件：

• API Gateway已開通：請前往 API Gateway控制台開通服務。

  重要

  由於 DataWorks 與 API Gateway的網路架構限制，購買 API Gateway執行個體時，實例類型目前僅支援傳統專享執行個體，VPC 融合執行個體暫不支援。

• API 分組已建立：API 發布時會根據其所屬商務程序的關聯分組，將 API 部署到 API Gateway中的對應分組。請確保商務程序已正確關聯 API Gateway分組（可通過右鍵業務流程>修改屬性查看具體的分組名稱）。

發布流程

API 的發布遵循提交 → 審批 → 發布的三步流程：

第一步：提交 API

1. 進入資料服務頁面，在服務開發頁面的 API 列表中，雙擊要發布的 API 名稱，進入 API 編輯頁面。

2. 單擊右上方的提交按鈕。

3. 提交成功後，系統會自動產生一個 API 版本（如 V1、V2 等），您可以在右側彈出的版本面板中查看該版本的狀態資訊。

第二步：申請發布並等待審批

1. 在右側的版本面板中，找到待發布的 API 版本，單擊發布按鈕。

2. 根據介面提示，輸入申請原因並單擊申請權限，提交發布申請。

3. 如果工作空間配置了審批次程序，發布請求需要經過核准中心的審核。審批人可在審批中心>待我審批頁面查看申請詳情並進行審批。

4. 審批通過後，API 在版本面板中的狀態會從待申請變為可發布。

第三步：執行發布

1. 審批通過後，在 API 編輯頁面的右側導覽列中，單擊版本，找到狀態為可發布的 API 版本。

2. 單擊發布按鈕，等待系統提示發布成功。

3. 發布成功後，DataWorks 會根據 API 所屬商務程序的關聯分組，將 API 部署至 API Gateway中的對應分組。

發布後的驗證

發布完成後，您可以通過以下方式驗證和管理 API：

• 在 API Gateway中查看：登入API Gateway控制台，在API 管理 > API清單中查看發行的 API 資訊，並可配置流量控制、存取控制等策略。

• 應用調用：如果 API 供自己的應用程式調用，需要在 API Gateway中建立應用，將 API 授權到應用中，然後通過 AppKey 和 AppSecret 進行加密簽名調用。API Gateway還提供了主流程式設計語言的 SDK，可快速整合 API 至您的應用中。詳情請參見用戶端調用API樣本；SDK 整合請參見SDK下載及使用指南。

• 協議變更：對發行的 API，在服務管理>發佈的API頁簽下，單擊對應 API 的更多>協定變更，修改 API 的訪問協議（如從 HTTP 變更為 HTTPS）。協議變更即時生效，但如果刪除了原有協議，原協議的介面調用將會失敗，請謹慎操作。

上架至阿里雲 API 市場（可選）

阿里雲 API 市場涵蓋多類目，可協助實現資料變現。

資料服務產生和註冊的 API 發布至 API Gateway後，可以一鍵上架至阿里雲 API 市場售賣，協助企業快速實現資料價值變現，形成商業閉環。

前置要求：

• 僅支援企業身份入駐阿里雲 API 市場。

• 上架前需以服務商身份入駐阿里雲雲市場。流程詳見雲市場入駐流程。

操作步驟：

1. 進入阿里雲服務商平台。

2. 在左側導覽列，單擊商品 > 商品管理。

3. 單擊發布商品。

4. 在接入資訊頁面，按照指引配置各項參數（包括商品名稱、定價策略、API 綁定等），完成 API 的上架流程。

查看版本歷史

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

2. 在服務開發頁面的 API 列表中，雙擊要查看的 API 名稱，進入 API 編輯頁面。

3. 單擊頁面右側的版本按鈕，開啟版本面板查看版本資訊、版本詳情等。版本面板中展示了當前 API 的所有歷史版本資訊，包括：

   說明

   每個版本的操作列中提供API詳情連結，單擊可查看該版本的完整配置資訊，包括請求參數、返回參數、資料來源配置等詳細內容。

   欄位	說明
   API ID	當前 API 的唯一識別碼。
   版本	版本號碼，按提交順序遞增（V1、V2、V3……）。
   提交人	提交該版本的操作人員。
   提交日期	該版本的發布時間，精確至秒。
   狀態	發布（當前線上生效的最新版本） 可發布（通過測試並提交的版本） 離線（歷史舊版本）

版本對比

當 API 經過多次迭代修改後，您可能需要對比不同版本之間的差異，以便瞭解具體的變更內容。

操作步驟：

1. 在版本面板中，勾選任意兩個需要對比的版本。

2. 單擊面板底部的對比按鈕。

3. 在彈出的歷史版本對比對話方塊中，查看兩個版本之間的差異。

對比內容說明：

• 嚮導模式 API：對比展示請求參數和返回參數的差異，包括參數名稱、類型、是否必填等屬性的變化。

• 指令碼模式 API：對比展示 SQL 指令碼的文本差異，以高亮方式標註新增、刪除和修改的程式碼。

版本對比功能特別適合在團隊協作情境中使用，協助審核人員快速理解每次變更的具體內容。

版本復原

當新版本出現異常或不符合預期時，您可以將 API 快速復原至之前的某個穩定版本。

操作步驟：

1. 在版本面板中，找到目標歷史版本。

2. 單擊該版本操作列中的復原按鈕。

3. 在彈出的確定要復原目前的版本對話方塊中，單擊確認。

版本管理原則

良好的版本管理習慣能夠顯著降低線上事故的風險：

• 變更記錄：每次提交時，在提交說明中清晰描述本次修改的內容和原因，方便團隊成員通過版本對比瞭解變更上下文。

• 灰階驗證：對於重大變更，建議先在測試環境充分驗證，確認無誤後再發布至生產環境。

• 快速復原：線上發現異常時，優先使用版本復原功能恢複服務，再排查問題根因。版本復原比修改後重新發布更快，能夠最大限度減少業務影響。

• 定期清理：對於長期未使用的 API，建議及時下線並清理，減少管理複雜度和潛在的安全風險。

測試與發布的協作流程

在團隊協作情境中，推薦以下工作流程：

1. 開發人員在服務開發頁面完成 API 的建立和配置。

2. 開發人員在開發環境中執行測試，確認功能正確。

3. 開發人員提交 API，產生新版本並發起發布申請。

4. 審批人在核准中心審核發布申請，可通過版本對比功能查看變更內容。

5. 審批通過後，開發人員執行最終發佈動作。

6. 營運人員在服務管理頁面對發行 API 進行線上測試和監控。

7. 如發現問題，通過版本復原快速恢複，或下線 API 進行修複。

通過遵循這一流程，團隊可以在保證發布品質的同時，實現高效的 API 全生命週期管理。

返回樣本的限制

API 編輯頁面支援設定正常返回樣本，用於在 API 文檔中展示預期的返回資料結構。需要注意以下限制：

• 不自動同步：API 測試頁面的返回結果不會自動更新為 API 的正常返回樣本。您需要在 API 編輯頁面手動編輯或粘貼返回樣本。

• 大小限制：正常返回樣本的內容有最大字元數限制。如果樣本資料過大（例如包含上百條記錄），可能儲存失敗。建議僅保留 2~3 條典型記錄作為樣本。

• 發布後生效：修改正常返回樣本後，需要重新提交並發布 API 才會在 API Gateway文檔中生效。

資料來源表結構變更後的處理

當 API 關聯的資料來源表結構發生變更（如新增欄位、刪除欄位、修改欄位類型）時，發行的 API 不會自動感知這些變更。如果不處理，可能導致以下問題：

操作步驟：

1. 進入 API 編輯頁面，根據表結構變更修改 API 配置。

   1. 嚮導模式：重新選擇表，系統會自動重新整理欄位列表。

   2. 指令碼模式：手動修改 SQL 陳述式中的欄位名或表名。

2. 儲存配置後，重新執行測實驗證。

3. 提交並重新發布 API。