You need to enable JavaScript to run this app.
导航
API 调用
最近更新时间:2024.06.07 11:43:12首次发布时间:2022.07.26 11:41:18

在数据服务 API 测试发布完成后,可以在 API 的详情页看到 API 的所有信息,包括:API 调用信息,生成接口文档,调用说明,调用地址(需 API 发布后才会生成),路径,请求示例等。
数据服务 API 目前支持以 HTTP 协议的调用方式进行调用。本文将为您介绍调用操作流程。

1 使用前期

  1. 已完成相应的 API 配置开发,并发布 API,详见 API 开发
  2. 系统管理 > 应用管理中,已创建相应的应用,并获取了应用的相关秘钥信息。详见应用管理
  3. 已在系统管理 > 网络配置中,完成 VPC 网络配置或公网配置。详见网络配置

2 操作流程

  1. 登录 DataLeap租户控制台
  2. 概览界面顶部服务窗口,单击数据服务按钮,可快速进入到数据服务 > API 界面。
  3. 在左侧目录树中,单击已发布的 API 名称信息,便会在右侧展现出 API 的配置界面。
  4. 在右侧导航栏处,单击 API 详情按钮,进入查看 API 详情。
    图片
  5. 在 API 详情的调用信息页签,您可查看具体的调用说明:
    • 调用说明栏中,展示了目前 API 所处环境的可调用地址概述信息,您可直接单击复制操作,复制对应环境的调用地址;
    • 请求代码栏中,会展示相关的调用代码示例及说明 。
      图片

2.1 请求参数说明

您可以在调用代码示例中查看调用的请求示例、请求步骤、请求/返回参数等信息。

  1. 步骤1. 复制秘钥:

    1. 首先您需在系统管理 > 应用管理中创建应用;
    2. 在对应的应用列表右侧操作列中,单击进入密钥管理界面;
    3. 单击右上角创建密钥按钮,设置新建应用秘钥信息,单击确定按钮,完成新建。
    4. 在秘钥列表界面,单击操作列中的“复制秘钥”便可复制。
      此处的“应用密钥” 即为调用 API 时需要填入的 DPS_TOKEN,调用的时候将 $DPS_TOKEN 替换为具体的“应用密钥” 信息。
      秘钥相关操作详见应用管理
  2. 步骤2. 进入 API 详情界面,单击授权管理页签,给 API 新增已创建的应用授权。

    1. 授权管理界面,单击新增授权按钮,并完成以下信息配置,完成相应的应用授权操作:
      其中参数名称前带 * 的为必填参数,名称前未带 * 的为可选填参数。

      配置项

      说明

      基本权限

      *应用名称

      下拉选择允许调用 API 的应用名称,对应一个已创建成功的应用信息。
      若您还未创建应用,您可单击新建应用按钮,前往应用管理进行创建。新建操作详见应用管理

      标志符

      应用的唯一标识,在应用管理创建时指定。

      有效期

      设定应用授权有效期限,新的到期时间=当前到期时间+续期天数,续期时会给 API 管理者和应用的申请者发送相应通知。您可下拉选择有效期天数。

      *最大QPS

      设置应用调用 API 的最大 QPS,您可根据实际情况,自定义设置调用 API 时最大的 QPS,当调用的 QPS 达到最大值时,会触发限流。
      若不填或选择不限制,则默认不限流。

      *调用负责人

      下拉选择真正调用当前 API 的应用负责人。

      调用优先级

      下拉选择调用的优先级情况,数字越小,代表等级越高。

      标签

      您可以自定义标签,用于标识某一类授权,以便快速搜索区分。

      • 单击添加按钮,添加标签组信息,下拉选择标签组,及对应的标签信息,支持添加多个标签组。
      • 若没有可选的标签组,您可单击上方创建标签组按钮,进入数据服务 > 系统管理 > 标签管理界面,进行新建标签组操作。详见标签管理
      • 您也可单击操作栏中的删除按钮,将已添加的标签进行删除操作。

      授权描述

      添加授权描述信息,可针对授权场景进行信息补充。

      行列权限

      行级权限

      设置调用的行级权限,您可针对请求参数做限制,比如限制只能访问某个请求参数的某几个值。支持添加多个行权限,各请求参数可以是“”、“”的关系。

      列权限

      列权限针对返回参数做限制,比如限制只能返回某列的参数信息。下拉选择返回参数字段列,支持选择多个。

    2. 授权配置项填写完成后,单击确定按钮,完成应用授权。

  3. 步骤3. 在您的 VPC 内调用 API:
    以下以向导式方式创建的 API 调用示例为例:

    curl -X POST \
      -H 'user:username' \
      -H 'env: $ENV' \
      http://xxx.xx.x.xx:8085/invoker_engine/query_with_params \
      -d '{"ApiID": "17015515xxxx","Option": [{"Id":100,"Val":0,"Val_":"$DPS_TOKEN"}],"Params": {"orderkey":0}}'
    
    1. 参数说明:

      参数

      说明

      user

      API 责任人用户名信息。

      env

      API 发布的环境信息。

      • 测试环境:$PPE
      • 线上环境:$ONLINE

      Url

      获取调用说明栏中的调用 URL。

      ApiID

      在 API 详情页上方,获取 APP ID 信息。

      Params/Sql

      • Params:向导式/脚本式 API 的请求参数示例。
      • Sql:原生 API 中逻辑表的查询 SQL 语句。
    2. Option 参数说明

      id

      含义

      说明

      1

      TIMEOUT

      查询数据库超时时间,单位为毫秒

      2

      DORIS_SETTINGS

      doris 查询 settings,写入 Val_,格式为 string,eg."{"a":1, "b":2}"

      3

      GRAMMAR_TYPE

      无需关注

      4

      TSDB_SETTINGS

      tsdb 配置,写入 Val_

      5

      CH_SETTINGS

      clickhouse settings,写入 Val_,格式为 string,eg."{"a":1, "b":2}"

      6

      ADVANCED_SETTINGS

      高级参数配置:with_total,true 表明可以返回当前 SQL 的查询总数

      100

      AUTH_TOKEN

      token,用于 api 访问鉴权,token 值写入 Val_,您可前往系统管理 > 应用管理 > 秘钥管理 > 应用秘钥界面,进行token 信息获取。操作详见2 管理应用密钥

  4. 步骤4. 如果您想通过公网方式调用 API,请通过系统管理 > 网络配置开通公网 IP:
    公网 IP 操作详见公网配置

    curl -X POST \
      -H 'user:username' \
      -H 'env: $ENV' \
      http://xxx.xx.x.xx/invoker_engine/sql_query \
      -d '{"ApiID": "1701551xxxxx","Option": [{"Id":100,"Val":0,"Val_":"$DPS_TOKEN"}],"Sql": "select * from 完整逻辑表名 limit 10"}'
    

2.2 返回参数说明

因每个场景的 API 返回字段都不同,所以返回参数以具体 API 调试返回的结果为主。下文以一个示例为您介绍返回参数说明。

2.2.1 返回结果示例

{
    "Fields": [
        {
            "Name": "name",
            "Type": 3      // 字符串类型
        },
        {
            "Name": "age",
            "Type": 1     // Int类型
        },
        {
            "Name": "id",
            "Type": 1    // Int类型
        },
        {
            "Name": "date",
            "Type": 4    // 日期类型
        },
        {
            "Name": "salary",
            "Type": 2    // Double,Folat类型
        }
    ],
    "Data": "[[\"2\",3,1,\"2023-12-01 00:00:00\",3333.060000],[\"3\",4,2,\"2023-12-01 00:00:00\",4444.060000]]",
    "TimeCost": 32,
    "DataCnt": 2,
    "ErrorCode": "",
    "RenderedSql": "",
    "BaseResp": {
        "StatusMessage": "",
        "StatusCode": 0,
        "Extra": {
            "time_cost": "32",
            "data_size": "21"
        }
    }
}

返回参数中部分字段说明,返回结果组成如下:

字段名称

字段含义

Fields

返回参数的名称和类型,类型具体说明如下2.2.2 FieldType

Data

返回结果,返回结果的顺序与 Fields 中的字段顺序对应。

TimeCost

本次查询耗时,单位 ms。

DataCnt

本次查询返回结果数量。

ErrorCode

错误码,具体如下2.2.3 QueryErrorType

RenderedSql

已渲染的 sql 语句,目前返回结果中不会展现,您无需关注。

BaseResp

基本信息,包含报错具体内容、错误码耗时等。

2.2.2 FieldType

enum FieldType {
    UNKNOWN = 0   // 未知类型
    BIGINT  = 1   // BIGINT、INT类型
    DOUBLE  = 2   // DOUBLE、FLOAT类型
    STRING  = 3   // 字符串类型
    DATE    = 4   // 日期类型
    MAP     = 5   // MAP类型
    ARRAY   = 6   // 数组类型
    BINARY  = 7   // BINARY类型
}

2.2.3 QueryErrorType

enum QueryErrorType {
    OK                        = 0    // 无错误
    PARSER_ERROR              = 1    // 解析错误
    ILLGEAL_INPUT_ERROR       = 2    // 用户参数错误
    RATE_LIMIT_ERROR          = 3    // query限流错误
    AUTH_ERROR                = 4    // 鉴权错误
    QUERY_TIMEOUT             = 5    // 查询超时
    DS_TIMEOUT                = 6    // 外部数据源超时
    INTERNAL_ERROR            = 7    // 内部错误
    META_ERROR                = 8    // 元数据获取错误
    DS_RATE_LIMIT_ERROR       = 9    // 数据源限流错误
    API_PSM_RATE_LIMIT_ERROR  = 10   // API的PSM粒度限流错误
    ARREARS_ERROR             = 11   // 欠费
    UNKNOWN_ERROR             = 255  // 未知错误
}

若出现调试错误,更多错误码说明可参考常见错误码以及解决方案