创建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 = 常量 ``（空字符串）

多次（循环）请求：参数遍历循环

该模式基于固定的参数值列表逐一遍历，每次请求将列表中的一个值作为指定入参传入API，直至列表所有值遍历完成后终止。适用于批量查询固定维度数据的场景（例如按城市、部门、产品ID批量拉取数据），支持手动填写参数列表和API自动获取参数列表两种方式。

三、当API用于写入数据时（API写入组件）