全部產品
Search

搜尋本產品

    DataWorks：建立、發布和調用API（雲原生API Gateway）

    文件中心

    DataWorks：建立、發布和調用API（雲原生API Gateway）

    更新時間：May 09, 2026

    本文以一個完整的端到端樣本，指導您如何通過雲原生API Gateway和DataWorks，將MaxCompute中的資料表發布為一個可供公網調用的REST API。

    • 樣本目標：為MaxCompute的user_info表建立一個API。該API允許調用者通過傳入user_id，查詢並返回對應的使用者資訊。

    • 最終效果：您將擁有一個可以通過公網URL（例如 https://api.example.com/v1/user/info?user_id=10001）訪問的API，並能擷取到安全的、經過認證的調用方法。

    說明

    工作原理

    下圖展示了從API調用方到最終資料來源的完整鏈路及各組件的配置位置。

    準備工作

    類別

    準備事項

    說明與操作指引

    帳號與許可權

    阿里雲帳號及相應許可權

    確保您的帳號擁有操作雲原生API Gateway、DataWorks、MaxCompute的許可權。

    DataWorks需具備對應工作空間的開發角色。

    服務開通

    開通所需雲端服務

    開通雲原生API Gateway。

    說明

    資源準備

    Serverless資源群組

    在Serverless資源群組的網路設定中綁定資料服務的專用網路和交換器。

    重要

    記錄該資源群組的Virtual Private Cloud資訊，這將在後續建立API Gateway執行個體時用到。建議網關執行個體和資料服務資源群組使用相同的VPC，簡化網路連通複雜度。

    MaxCompute測試資料

    在您的MaxCompute專案中，執行以下DDL語句建立user_info表：
    CREATE TABLE user_info (user_id BIGINT, user_name STRING, age BIGINT);。







    執行以下DML語句插入測試資料：
    INSERT INTO user_info VALUES (10001, 'Alice', 25), (10002, 'Bob', 30);。







    DataWorks資料來源

    在DataWorks的工作空間管理中，配置一個指向上述MaxCompute專案的資料來源。

    步驟一：在雲原生API Gateway控制台準備基礎資源

    此步驟旨在建立承載API服務的網關執行個體、用於公網訪問的網域名稱以及用於組織API的邏輯單元（REST API）。

    1. 建立網關執行個體

    網關執行個體是處理API請求的引擎。

    1. 登入雲原生API Gateway控制台，在左側導覽列單擊實例。

    2. 在頂部功能表列選擇地區。

      重要

      地區必須與DataWorks工作空間地區完全一致。

    3. 在實例頁面，單擊建立執行個體。

    4. 在購買頁面配置以下參數：

      • 商品類型：支援按量付費或包年包月。測試時可選用隨用隨付。

      • 網關名稱：自訂一個易於識別的名稱，例如 dataservice-prod。

      • 網關規格：測試可選擇單節點規格，但生產環境建議使用多節點網關規格以保證SLA。

      • 網路訪問類型：選擇公網或公網+私網，以便後續通過互連網調用。使用公網訪問類型會產生流量費用。

      • 專用網路：選擇一個VPC。

        重要

        為保證網路連通，此處選擇的VPC強烈建議與準備工作中Serverless資源群組所在的VPC保持一致。如果VPC不一致，您將必須在後續手動建立後端服務。

      • 可用性區域選擇：可選擇自動分配或手動在不同可用性區域和交換器中分配執行個體。

      • 資源組：根據您的資源管理原則選擇。

    5. 單擊立即購買並完成支付。執行個體建立過程約需1～5分鐘，當執行個體狀態變為運行中時，表示建立成功。

    更多詳情，請參見建立網關執行個體。

    2. 添加網域名稱

    說明

    若您只需在VPC專用網路內訪問，無需申請網域名稱。

    網域名稱是API的公網訪問入口。

    1. 在雲原生API Gateway控制台左側導覽列選擇網域名稱，並確保頂部地區與網關執行個體一致。

    2. 單擊添加網域名稱，配置以下資訊：

      • 網域名稱：填寫您自己的網域名稱，例如 api.example.com。在中國地區使用的獨立網域名稱需完成備案。

      • 協議：建議選擇HTTPS以保障資料轉送安全。選擇HTTPS時，需要選擇一個已有的SSL認證。

      • 其他配置：建議開啟強制HTTPS和啟用 HTTP/2，並根據安全要求指定TLS 版本。

    更多詳情，請參見建立網域名稱。

    3. 建立 REST API

    REST API是一個邏輯容器，用於管理一組具有相同Base Path的API。DataWorks中的一個商務程序會與一個REST API綁定。

    說明

    類比於原API Gateway，REST API相當於API分組。

    1. 在雲原生API Gateway控制台左側導覽列單擊API，並確保頂部地區正確。

    2. 單擊創建API，然後在創建API頁面中選擇REST API卡片下的創建。

    3. 在建立REST API面板中配置：

      • API名稱：為您的API集合命名，此名稱要求在當前地區下全域唯一，例如 dataservice-user-api。

      • Base Path：API的基本路徑，作為URL的一部分。例如，配置為 /v1。最終的訪問路徑將是 協議://網域名稱/BasePath/APIPath。

      • 版本管理：按需啟用。

    更多詳情，請參見建立REST API並添加介面。

    步驟二：在DataWorks中建立並配置API

    此步驟將在DataWorks中完成API的邏輯定義、資料來源對接和參數配置。

    1. 建立商務程序

    商務程序用於組織一組相關的API，並將其與API Gateway的REST API進行綁定。

    1. 進入DataWorks控制台，在左側導覽列進入資料服務 > 服務開發。

    2. 單擊左上方的建立表徵圖，選擇新建業務流程。

    3. 在新建業務流程對話方塊中配置：

      • 業務名稱：自訂，在工作空間內唯一，例如 使用者查詢業務。名稱長度限制為4～50字元。

      • 網關類型：選擇雲原生API網關。

      • REST API：從下拉框中選擇您在步驟一中建立的REST API（例如 dataservice-user-api）。如果未出現，可單擊刷新按鈕。

        重要

        商務程序綁定REST API後，不能換綁修改。請您謹慎選擇。

    2. 使用嚮導模式產生API

    1. 在服務開發頁面，將滑鼠移至上方在左上方的建立表徵圖，單擊新建API > 生成API。

    2. 在生成API對話方塊中，選擇嚮導模式並配置API的基本資料：

      • 目標文件夾：選擇上一步建立的業務流程（使用者查詢業務）。

      • API名稱：為具體的API命名，例如 根據使用者ID查詢使用者。

      • APIPath：介面的具體路徑，例如 /user/info。它將與Base Path拼接成完整的URL路徑。API Path必須以/開頭，且長度不超過200字元。

      • 請求方式：選擇GET或者POST。使用GET請求方式時，請求參數僅支援放在QUERY中。

      • 返回類型：選擇JSON。

    3. 單擊建立，進入API的圖形化編輯頁面。

      說明

      指令碼模式建立可參考通過指令碼模式產生API。

    3. 配置API

    在API編輯頁面，通過選擇表 > 選擇參數 > 配置參數的流程，完成API的核心邏輯定義。

    1. 選擇表（資料來源與表）

      在頁面左側的選擇表地區進行配置：

      • 數據源類型：選擇 MaxCompute(ODPS)。

      • 數據源名稱：選擇您在準備工作中已配置好的資料來源。

      • 數據表名稱：選擇 user_info 表。

      • 若使用MaxCompute資料來源，需要配置加速方式以提升效能。

    2. 選擇參數（請求與返回）

      選擇表後，下方的選擇參數地區會列出該表的所有欄位。

      • 配置請求參數：勾選 user_id 欄位，然後單擊並勾選設為請求參數。

      • 配置返回參數：勾選 user_id 和 user_name 欄位，然後單擊並勾選設為返回參數。

    3. 配置請求參數詳情 在頁面右側的請求參數頁簽，為user_id參數配置樣本值（例如 10001），這有助於後續的測試。

      最佳實務：建議將有索引的欄位設為請求參數，以最佳化查詢效能。

    4. 佈建服務資源群組與環境

      在頁面右側的服務資源群組地區進行配置：

      • 資源組類型：必須選擇獨享服務資源群組，並在下拉框中選擇已與當前工作空間綁定的資源群組。

      • 環境配置：

        • 超時時間：雲原生API Gateway等待DataWorks響應的最長時間，例如 3 秒。

        • 單次請求數據條數上限：限制單次API調用返回的最大記錄數，例如 2000條。

    5. 配置安全認證

      在頁面右側的安全認證地區進行配置：當啟動消費者認證之後，可選擇以下三種認證類型之一。

      說明

      DataWorks各工作空間自動在雲原生API Gateway建立一個與工作空間同名的消費者，您無需手動建立。

      配置方式

      說明

      情境適用

      API Key

      用戶端需將憑證按指定方式添加到請求中，網關驗證其合法性與許可權。適用於非敏感操作環境，安全性低於 JWT、AK/SK，需注意憑證管理與保護。

      適合輕量級、快速接入以及對安全性要求一般的情境。

      JWT

      JSON Web Token (JWT) 是一種在用戶端與服務端之間安全傳輸資訊的標準，通過 HMAC、RSA 或 ECDSA 簽名確保資訊可驗證和可信。JWT 認證可在網關中實現身分識別驗證與存取控制。

      適用於分布式系統和單點登入（SSO）情境。

      HMAC

      基於 HMAC 演算法的 AK/SK 簽名認證方式要求用戶端在調用 API 時，使用簽名金鑰組請求內容進行簽名計算，並將簽名一同發送至服務端驗證 。

      適合對資料完整性和防篡改有較高要求的情境。

    6. 儲存API：完成所有配置後，單擊頂部工具列的儲存表徵圖。

    步驟三：測試、提交與發布API

    1. 測試API

    API必須先成功通過測試才能被提交。

    1. 在API編輯頁面，單擊工具列中的API測試按鈕。

    2. 在API測試對話方塊中，為請求參數user_id填入一個存在的樣本值（如 10001），然後單擊開始測試。

    3. 在右側查看返回內容，確認資料是否符合預期。響應時長可用於評估效能。

    4. 若測試失敗，請根據錯誤提示檢查資料來源、表、參數或資源群組配置。

    2. 提交API

    測試通過後，將API提交，產生一個待發布的版本。

    1. 在API編輯頁面，單擊工具列的提交按鈕。

    2. 提交成功後，系統會自動產生一個API版本。您可以在右側的版本管理頁簽中查看。

    3. 如果您的工作空間配置了審批流，API版本狀態將為待申請。您需要單擊申請發布並發起申請，待審批人處理通過後，狀態變為可發布。

      若未配置審批流，版本狀態通常直接為可發布。

    3. 發布API到雲原生API Gateway

    這是將API部署到線上環境的最後一步。

    1. 在API編輯頁面的右側版本頁簽中，找到狀態為可發布的版本，單擊其操作列的發布。

    2. 在將API發佈到雲原生API網關對話方塊中，配置以下三項（均為必填）：

      • 網域名稱：選擇您在步驟一中添加的網域名稱。

        重要

        同一REST API下的所有API 網域名稱一致，此處發布時對網域名稱的修改將影響同一REST API下的所有API 的網域名稱調用。

      • 網關實例：選擇您在步驟一中建立的網關執行個體。

      • 後端服務：

        • 如果網關執行個體VPC與DataWorks資源群組VPC一致，此處選擇預設即可。

        • 如果VPC不一致，此處必須選擇在雲原生網關API建立後端服務。

          建立後端服務

          執行此步驟的前提是：在步驟一中建立網關執行個體時，選擇的VPC與Serverless資源群組的VPC不一致。 如果兩者VPC一致，請跳過此節。

          後端服務的作用是用於請求資料服務，打通兩個不同的VPC。

          1. 在雲原生API Gateway控制台的實例列表中，單擊目標執行個體ID。

          2. 在執行個體詳情頁的左側導覽列中，選擇服務。

          3. 單擊建立服務。如果系統提示，請先在來源頁簽建立一個來源。

          4. 在建立服務時，佈建服務名稱並關聯已建立的來源。

          更多詳情，請參見建立服務。

    發布成功後，API即已上線，可以通過調用地址進行調用。

    步驟四：調用與驗證API

    根據2.3.5步驟中配置的認證方式，使用憑證進行訪問。

    1. 在部署的API版本頁簽中，找到剛發布的版本，點擊右側服務管理進入API管理頁面，查看API的具體資訊。

    2. 在API管理中，點擊API 名稱/API Path下的地址，查看API詳情。

    3. 構造並執行調用

      • 樣本URL：複製API詳情的調用地址。

      • 認證資訊：在服務管理 > API調用 > 雲原生API網關中，查看不同方式的調用認證。

      • 調用方法：使用curl或其他HTTP用戶端，在要求標頭中攜帶AppKey和AppSecret進行調用。

        更多詳情，參考管理消費者。

      Curl調用樣本：

      API Key認證
      # 請將 api.example.com 替換為您的真實網域名稱
curl "https://api.example.com/v1/user/info?user_id=10001" \
 -X GET \
 -H "Content-Type: application/json;  charset=utf-8" \
 -H "Authorization: Bearer <API_KEY>"
      HMAC認證

      詳細調用流程，請參見AK/SK（HMAC）認證。

      # 請將 api.example.com 替換為您的真實網域名稱
curl "https://api.example.com/v1/user/info?user_id=10001" \
 -X GET \
 -H "x-ca-key: Access Key" \
 -H "x-ca-signature: <Base64EncodedSignature>" \
 -H "x-ca-signature-method: HmacSHA256" \
 -H "Date: Wed, 01 Jan 2025 00:00:00 GMT" \
 -H "Accept: application/json" \

    4. 查看預期響應 如果一切正常，您將收到類似以下的JSON響應：

      {
  "data": {
    "user_id": 10001,
    "user_name": "Alice"
  },
  "success": true
}

    API 多版本支援

    雲原生API Gateway支援將同一個API發布到多個不同的網關執行個體。您可以利用此特性將API部署到不同環境（如測試網關和生產網關），或將同一API同時發布到多個網關執行個體以滿足不同業務情境的需求。

    發布API到多個網關執行個體

    在版本面板中，對狀態為可發布的版本單擊發佈，在將API發佈到雲原生API網關對話方塊中選擇不同的網關實例，即可將API發布到對應的網關執行個體。您可以多次執行發佈動作，將同一API發布到不同的網關執行個體。

    說明

    同一個網關執行個體中，發布新版本後舊版本會自動下線。不同網關執行個體的版本互不影響，可以同時處於發布狀態。

    服務管理中的多版本展示

    API發布到多個網關執行個體後，服務管理頁面中的展示會發生以下變化。

    API管理列表

    在服務管理的發佈的API頁簽中，同一個API ID會展示多條記錄，每條記錄對應一個發行的網關執行個體。列表中的網關實例列會顯示每條記錄對應的網關執行個體名稱和網關ID。

    API詳情頁

    單擊API名稱進入API詳情頁後，頁面頂部會展示網關實例下拉選取器。您可以通過切換網關執行個體，查看該API在不同網關執行個體下的詳細資料，包括調用地址、請求參數、返回參數等。