API 调用

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

1 使用前期

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

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"
        }
    }
}

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

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  // 未知错误
}

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