Dataphin：建立API資料來源

核心能力說明

API資料來源核心能力如下，詳細參數配置請參見上文。

不同API認證方式對應的API資料來源配置

以下是支援接入的API認證方式、核心參數及使用說明，包含參數定義、配置規則、使用情境。

簡單來說，Basic Auth、阿里雲AppKey Auth為專屬情境；API Key、Bearer Token為通用情境；OAuth2.0適用於需授權的複雜情境；None適用於公開介面。

• None（無認證）

  • 核心說明

    無需任何認證資訊即可調用API，適用於公開可訪問的介面（如公開查詢、匿名訪問的基礎介面），或介面本身通過IP白名單、商務邏輯做許可權控制的情境。

  • 配置參數

    無需配置任何認證參數，直接調用API即可。

• Basic Auth（基本認證）

  • 核心說明

    基於HTTP基礎認證協議的簡單認證方式，使用者名稱和密碼將通過Base64編碼後置於要求標頭（Authorization: Basic <編碼串>）中傳輸，建議僅在HTTPS協議下使用，避免明文泄露風險。

  • 必選配置參數

    參數名	說明	配置樣本
    使用者名稱	服務端分配的基礎認證使用者名稱（通常為字串，支援英文字母大小寫、數字和特殊字元）。	api_user_01
    密碼	服務端分配的基礎認證密碼，需與使用者名稱配對使用。	e89s76d9@2026

• 阿里雲AppKey Auth（阿里雲專屬認證）

  • 核心說明

    阿里雲開放平台標準認證方式，基於AppKey和AppSecret進行簽名驗證（不同阿里雲產品簽名規則略有差異，通常會對請求參數、時間戳記、非空等進行加密簽名，簽名部分詳情請參見離線整合API輸入及輸出組件對接說明），適用於調用阿里雲各類開放API（如OSS、RDS、簡訊服務等）。

  • 必選配置參數

    參數名	說明	配置樣本
    AppKey	服務端分配的基礎認證使用者名稱（通常為字串，支援英文字母大小寫、數字和特殊字元）。	api_user_01
    AppSecret	服務端分配的基礎認證密碼，需與使用者名稱配對使用。	e89s76d9@2026

• API Key（密鑰認證）

  • 核心說明

    通過自訂的Key-Value索引值對進行認證，支援將密鑰放在請求參數（URL）、要求標頭（Header）或請求體（Body）中傳輸，是通用性極強的認證方式，適配多數自研或第三方API。

  • 必選配置參數

    參數名	說明	配置樣本
    Key	認證密鑰的標識名（由API提供方定義），如api-key、app-key、token-id。	api_key
    Value	與Key配對的認證值，為服務端分配的唯一密鑰，請妥善保管。	789d87s6a987d6s9876d987s6987d
    可選添加至	指定Key-Value的傳輸位置，可選擇： Parameter：拼接在URL參數中，例如https://api.xxx.com?api_key=789d87s6...\。 Header：放在要求標頭中，例如api_key: 789d87s6...。 Body：放在POST請求體中。	Header

• Bearer Token（令牌認證）

  • 核心說明

    基於HTTP Bearer令牌的簡易認證方式，Token直接放在要求標頭（Authorization: Bearer <令牌值>）中傳輸，適用於單次或短期有效令牌認證情境（如臨時存取權杖）。

  • 必選配置參數

    參數名	說明	配置樣本
    Token	服務端頒發的Bearer令牌值，通常為字串（如JWT、隨機字串），需確保令牌在有效期間內。	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

• OAuth2.0（授權碼認證）

  • 核心說明

    工業標準的授權認證協議，需先通過配置擷取Access Token，再攜帶Token調用目標API，適用於需使用者授權、多端訪問的情境（如第三方平台對接、使用者態API調用）。

    以離線整合為例，目前Dataphin調用邏輯為，每次請求目標API前都會擷取Access Token，再攜帶Token調用目標API。

  • 必選配置參數

    	參數名	說明	配置樣本
    基礎配置	Token首碼	拼接在要求標頭中Token的首碼（通常為Bearer，部分平台為Token或OAuth）。	Bearer
    	Access Token路徑	擷取Access Token的介面返回中。Access Token值擷取方式如下，例如返回結果為： { "access_token": "access_token_return", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "d68297697d37d97197d7a0c986f9d77989118912" } 則填寫access_token。	access_token
    Access Token擷取配置	請求方式	擷取Token的HTTP要求方法（支援GET/POST，主流為POST）。	POST
    	Token URL	服務端提供的擷取Access Token的介面地址。	https://oauth.xxx.com/token\
    	用戶端ID	服務端分配的應用唯一標識（Client ID）。	client_123456789
    	用戶端密鑰	服務端分配的應用密鑰（Client Secret），密鑰需保密，請妥善保管。	secret_987654321
    	用戶端認證（非必選）	發送用戶端ID/密鑰的方式，可選擇： 要求標頭：放在Authorization頭中（Basic Auth格式）。 請求體：放在Token請求的Body參數中。	要求標頭
    	擷取Token的其他請求參數（非必選）	擷取Token時需額外攜帶的參數，支援放在Parameter（URL）或Header中。例如，grant_type=client_credentials或scope=read_write。	Parameter：grant_type=client_credentials

介面要求

• 資料讀取介面

  針對資料讀取介面的資料結構，僅支援單層實值型別的JSON對象結構，禁止在單條記錄的欄位值中包含數組（Array）類型，具體規範如下：

  • 支援的標準資料結構（合規）

    單條使用者記錄的所有欄位值需為字串、數字、布爾值等基礎類型，嵌套對象內的欄位值也需遵循此規則（支援多層嵌套對象）。

    //支援讀取分頁資料，介面返回必須包含分頁資訊page_no、page_size
    {
      "code": 200,          
      "msg": "請求成功",     
      "request_id": "req-20260228001", // 唯一請求ID（排查問題用）
      "data": [{
        "user_id": 10001,
        "user_name": "張三",
        "user_phone": "13800138000",
        "user_email": "zhangsan@example.com",
        "user_hobbies": {
          "sports" : "羽毛球、乒乓球",// 支援多層嵌套對象讀取
          "instrument" : "吉他"
        },
        "create_time": "2026-02-28 10:00:00"
      },{
        "user_id": 10002,
        "user_name": "李四",
        "user_phone": "13800138001",
        "user_email": "lisi@example.com",
        "user_hobbies": {
          "sports" : "籃球",
          "instrument" : "鋼琴、二胡"
        },
        "create_time": "2026-02-28 10:00:00"
      }],
      "page_no": 1,     // 當前頁碼，分頁介面必須包含，若非分頁介面則無需該欄位
      "page_size": 10,  // 每頁條數，分頁介面必須包含，若非分頁介面則無需該欄位
      "total": 23,      // 資料總條數，非必須
      "pages": 3,       // 總頁數，非必須
    }

  • 禁止的異常資料結構（不合規）

    單條記錄中任意欄位（含嵌套對象內欄位）的值不得為數組（Array）類型，以下結構不符合對接要求，無法正常解析。

    {
      "code": 200,          
      "msg": "請求成功",     
      "request_id": "req-20260228001", 
      "data": [{
        "user_id": 10001,
        "user_name": "張三",
        "user_phone": "13800138000",
        "user_email": "zhangsan@example.com",
        "user_hobbies": {
          "sports": ["籃球"],          // 欄位值為數組，禁止
          "instrument": ["鋼琴", "二胡"] // 欄位值為數組，禁止
        },
        "create_time": "2026-02-28 10:00:00"
      }]
    }

• 資料寫入介面

  針對資料寫入介面的資料結構，僅支援單層實值型別的JSON對象結構，禁止接收嵌套對象、數群組類型的欄位值，具體規範如下：

  • 支援的標準資料結構（合規）

    單條使用者記錄的所有欄位值需為字串、數字、布爾值等基礎類型，不支援嵌套對象及數組。

    [{
        "user_id": 10001,
        "user_name": "張三",
        "user_phone": "13800138000",
        "user_email": "zhangsan@example.com",
        "create_time": "2026-02-28 10:00:00"
      },{
        "user_id": 10002,
        "user_name": "李四",
        "user_phone": "13800138001",
        "user_email": "lisi@example.com",
        "create_time": "2026-02-28 10:00:00"
    }]

  • 禁止的異常資料結構（不合規）

    單條記錄中任意欄位的值禁止為嵌套對象、數群組類型，以下結構不符合對接要求，無法正常解析。

    [{
        "user_id": 10001,
        "user_name": "張三",
        "user_hobbies": ["籃球", "鋼琴"], // 禁止：數群組類型
        "user_info": {                   // 禁止：嵌套物件類型
          "phone": "13800138001",
          "email": "zhangsan@example.com"
        },
        "create_time": "2026-02-28 10:00:00"
      },{
        "user_id": 10002,
        "user_name": "李四",
        "user_hobbies": ["籃球", "鋼琴"], // 禁止：數群組類型
        "user_info": {                   // 禁止：嵌套物件類型
          "phone": "13800138002",
          "email": "lisi@example.com"
        },
        "create_time": "2026-02-28 10:00:00"
    }]

離線整合API輸入及輸出組件對接說明

離線整合為API資料來源的主要使用情境，在輸入和輸出情境上，支援的能力及要求存在些許不同。API輸入/輸出組件配置詳情請參見：

• 配置API輸入組件

• 配置API輸出組件

一、可支援API簽名認證（整合情境使用）

API 簽名是一種強安全的身份校正機制，API 簽名通過對請求關鍵資訊（如請求參數、時間戳記、隨機數、密鑰）進行雜湊運算產生簽名串，服務端使用相同規則重新計算簽名並比對，防止請求篡改、重放攻擊。它可獨立使用，也可疊加在上述其他認證方式之上，提升介面安全性。若服務端API有簽名要求可參考這部分內容。

必選配置參數

以下參數均用於產生簽名字串。

二、當API用於讀取資料時（API輸入組件）

必要參數

多次（迴圈）請求：分頁迴圈

針對單次請求無法返回全量資料的 API（例如分頁介面、滾動查詢介面），支援自動迴圈調用能力，通過頁碼/位移量迴圈或遊標迴圈兩種模式，持續發起請求直至滿足終止條件，自動彙總全量資料，適配各類批量資料拉取情境。

• 頁碼/位移量迴圈

  適用於標準分頁介面，介面通過頁碼（page)+每頁條數（size)，或位移量（offset)+每頁條數（limit)作為入參，返回指定頁資料的情境（例如page=1&size=100、offset=0&limit=100）。

  參數名	說明	配置樣本（page+size 分頁）	配置樣本（offset+limit 分頁）
  請求參數	選擇迴圈入參的傳輸位置（僅Params/Body）+ 具體迴圈參數名。	位置：Params 參數名：page	位置：Params 參數名：offset
  請求起始值	迴圈參數的初始值。	1（page從1開始）	0（offset從0開始）
  請求步長	每次迴圈後參數的遞增幅度（需與介面每頁條數匹配）。	1（每頁100條，page每次 + 1）	100（每頁100條，offset 每次 + 100）
  終止條件	迴圈停止的判斷規則： 支援返回參數、請求參數、常量、請求次數比較。	規則：返回參數current_page = 常量10 （拉取10頁後終止，此處條件靈活配置）	規則：返回參數has_more = 常量false （無更多資料時終止，此處條件靈活配置）

• 遊標迴圈

  適用於高並發/巨量資料量介面，介面通過上一次請求返回的遊標值（cursor）作為下一次請求入參，避免頁碼分頁的 “資料漏查/重複” 問題（如滾動日誌、即時訂單拉取）。

  參數名	說明	配置樣本
  請求參數	選擇迴圈入參的傳輸位置（Params//Body）+ 具體遊標參數名	位置：Params 參數名：next_cursor
  遊標參數	定義下一次請求的遊標值來源：從本次請求的返回參數中提取（支援 JSON 路徑）	返回參數 + data.next_cursor
  請求起始值	首次請求的遊標初始值（介面約定的 “初始遊標”，如 0，預設為0）	0
  終止條件	迴圈停止的判斷規則： 常用「返回參數遊標值 = 常量（空 / 0）」或「返回資料為空白」	規則：返回參數data.next_cursor = 常量 ``（Null 字元串）

多次（迴圈）請求：參數遍曆迴圈

該模式基於固定的參數值列表逐一遍曆，每次請求將列表中的一個值作為指定入參傳入API，直至列表所有值遍曆完成後終止。適用於批量查詢固定維度資料的情境（例如按城市、部門、產品ID批量拉取資料），支援手動填寫參數列表和API自動擷取參數列表兩種方式。

三、當API用於寫入資料時（API寫入組件）