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

使用前提 #

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

操作流程 #

1. 登录DataLeap控制台。
2. 在右侧快速入口，单击数据服务按钮，可快速进入到数据服务功能界面。
3. 在左侧目录树中，单击已发布的API名称信息，便会在右侧展现出API的配置界面。
4. 在右侧导航栏处，单击API详情按钮，进入查看API详情。
   
5. 在API详情的调用信息页签，您可查看具体的调用说明：
   • 调用说明栏中，展示了目前API所处环境的可调用地址概述信息，您可直接单击复制按钮操作，复制对应环境的调用地址；
   • 请求代码栏中，会展示相关的调用概述、API说明（包含请求/返回参数、正常响应示例等）、代码调用示例及说明等信息。
     

请求代码说明 #

您可以在请求代码示例中查看调用的请求示例、请求步骤、请求/返回参数等信息。下面为您介绍API调用的操作流程：

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

2. 步骤2. 授权管理
   进入API详情界面，单击授权管理页签，给API新增已创建的应用授权。
   在授权管理界面，单击新增授权按钮，并完成以下信息配置，完成相应的应用授权操作，其中参数名称前带 * 的为必填参数，名称前未带 * 的为可选填参数：
   表 新增授权 说明

   参数	说明
   基本权限
   *应用名称	下拉选择允许调用 API 的应用名称，对应一个已创建成功的应用信息。 若您还未创建应用，您可单击新建应用按钮，前往应用管理进行创建。新建操作详见“应用管理”。
   标志符	应用的唯一标识，在应用管理创建时指定。
   有效期	设定应用授权有效期限，新的到期时间=当前到期时间+续期天数，续期时会给 API 管理者和应用的申请者发送相应通知。您可下拉选择有效期天数。
   应用方	输入应用方名称信息，可用于申请 API、授权或审批时方便明确应用方信息。
   *最大QPS	设置应用调用 API 的最大 QPS，您可根据实际情况，自定义设置调用 API 时最大的 QPS，当调用的 QPS 达到最大值时，会触发限流。 若选择不限制，则默认不限流。
   *调用负责人	下拉选择真正调用当前 API 的应用负责人。
   调用优先级	下拉选择调用的优先级情况，数字越小，代表等级越高。
   标签	您可以自定义标签，用于标识某一类授权，以便快速搜索区分。 单击添加按钮，添加标签组信息，下拉选择标签组，及对应的标签信息，支持添加多个标签组。 若没有可选的标签组，您可单击上方创建标签组按钮，进入数据服务 > 系统管理 > 标签管理界面，进行新建标签组操作。详见“标签管理”。 您也可单击操作栏中的删除按钮，将已添加的标签进行删除操作。
   授权描述	添加授权描述信息，可针对授权场景进行信息补充。
   行列权限
   行级权限	设置调用的行级权限，您可针对请求参数做限制，比如限制只能访问某个请求参数的某几个值。支持添加多个行权限，各请求参数可以是“且”、“或”的关系。 注意 行级权限设置前，您需先添加对应的请求参数，如指标查询式API设置权限前，需先添加所需的维度字段。
   列权限	列权限针对返回参数做限制，比如限制只能返回某列的参数信息。下拉选择返回参数字段列，支持选择多个。

3. 步骤3. 在环境内调用API：
   以下以脚本式方式创建的API调用示例为例：

   curl -X POST \
      -H 'user: username' \
      -H 'Content-Type: application/json' \
      http://exxxxx.datarangers-onpremise.volces.com/invoker_engine/query_with_params \
      -d '{"ApiID": "180xxxxxx64","Option": [{"Id":100,"Val":0,"Val_":"$DPS_TOKEN"}],"Params": {}}'
   

   参数说明：
   表 API调用示例 参数说明

   参数	说明
   user	API 责任人用户名信息。非必填。
   Url	获取调用说明栏中的调用 URL。
   ApiID	输入当前已发布的API ID信息，在API详情中可获取。
   $DPS_TOKEN	替换应用管理中已创建的秘钥信息。
   Params/Sql	Params：向导式/脚本式 API 的请求参数示例。 Sql：原生 API 中逻辑表的查询 SQL 语句。

   如果使用了动态秘钥功能，创建方式详见“管理密钥”。则可以使用如下接口，来动态获取Token信息：

   curl -X POST \
     -H 'user: username' \
     -H 'Content-Type: application/json' \
     http://exxxxxxleap.datarangers-onpremise.volces.com/data_service/api/v2/api_service/token \
     -d '{"AppKey": "you_app_key","AppSecret": "you_app_secret"}'
   

   返回样例如下：

   {
       "code": 0,
       "message": "Success",
       "data": {
           "AppKey": "you_app_key",
           "Token": "token_str"
       },
       "meta": {
           "text": "",
           "redirect": ""
       }
   }
   

   注意

   动态Token有一定有效期且会动态变化，请不要缓存动态Token或者对动态Token有任何假设，每次请求获取即可。
   后续您便可将获取到的动态Token信息，复制到API调用所需的秘钥参数中。

返回参数说明 #

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

返回结果示例

API返回结果示例如下：

{
    "Fields": [
        {
            "Name": "id",
            "Type": 1
        },
        {
            "Name": "group_name",
            "Type": 3
        },
        {
            "Name": "value",
            "Type": 1
        }
    ],
    "Data": "[[1,\"group1\",100],[2,\"group2\",200],[3,\"group3\",300]]",
    "TimeCost": 8,
    "DataCnt": 3,
    "ErrorCode": "",
    "RenderedSql": "",
    "BaseResp": {
        "StatusMessage": "",
        "StatusCode": 0
    }
}

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

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类型
}

QueryErrorType

• ErrorCode常见错误状态码说明：

  状态码	名称	含义
  0	QueryErrorType_OK	查询成功
  1	QueryErrorType_PARSER_ERROR	解析报错
  2	QueryErrorType_ILLGEAL_INPUT_ERROR	非法参数报错
  3	QueryErrorType_RATE_LIMIT_ERROR	限流报错
  4	QueryErrorType_AUTH_ERROR	权限报错
  5	QueryErrorType_QUERY_TIMEOUT	查询超时报错
  6	QueryErrorType_DS_TIMEOUT	数据源超时报错
  7	QueryErrorType_INTERNAL_ERROR	程序内部报错
  8	QueryErrorType_META_ERROR	元信息报错
  9	QueryErrorType_DS_RATE_LIMIT_ERROR	数据源限流报错
  10	QueryErrorType_API_PSM_RATE_LIMIT_ERROR	API的PSM粒度限流错误
  11	QueryErrorType_ARREARS_ERROR	欠费
  255	QueryErrorType_UNKNOWN_ERROR	未知错误

• One Service常见错误码说明

  状态码	含义
  0000	未知查询引擎
  10001	没有权限
  10002	元信息错误
  10003	参数解析错误
  10004	Api的QPS超限额
  10005	解析错误
  10006	执行错误
  10007	未知查询类型
  10008	查询请求错误
  10009	查询引擎不匹配错误
  10010	数据源限流错误
  10011	PSMXAPI限流错误
  10012	令牌无效
  10013	数据权限规则错误
  10014	无数据权限错误
  10016	欠费错误
  10017	压力测试无效错误
  10018	ACL允许IP无访问权限错误
  10019	ACL阻止IP无访问权限错误
  10020	数据源连接错误
  10021	调用引擎内部超时错误
  10022	数据源超时错误
  20001	NoSQL 解析错误
  20002	NoSQL 预处理错误
  20003	NoSQL 规划器错误
  20004	NoSQL 动态索引错误
  20005	NoSQL DAG构建错误
  20006	NoSQL 类型错误
  20007	NoSQL 交换错误
  20008	NoSQL 资源不足错误
  20009	NoSQL 操作符运行错误
  20010	NoSQL 参数错误
  20011	NoSQL 任务停止错误
  20012	NoSQL 索引错误
  20013	NoSQL 任务超时错误
  20014	NoSQL 数据丢失错误
  30001	ClickHouse SQL解析错误
  30008	ClickHouse 鉴权失败
  30010	ClickHouse 数据源限流错误
  30011	ClickHouse 当前SQL限流错误
  30012	ClickHouse 字段验证错误
  30013	ClickHouse 未知表错误
  40001	MySQL SQL 解析错误
  40002	MySQL 未知数据源错误
  40003	MySQL 字段验证错误
  40004	MySQL 查询超时错误
  40006	MySQL 模糊集群错误
  40007	MySQL 未知表错误
  40008	MySQL SQL鉴权错误

接口文档获取 #

数据服务API开发测试并发布后，您可一键获取API接口使用文档，方便调用时进行参考。
进入API详情界面，在调用信息页签中，您可按需在浏览器中直接生成VN版本接口文档、或生成当前线上接口文档；您也可以单击下载VN版本接口文档按钮，将API使用文档下载至本地。您可在接口文档中查看HTTP调用实例、开启分页调用说明、使用Postman调式API说明、使用Java调用API说明等使用信息。

上架API #

数据服务API上架到API集市后，您可通过申请调用API，来解决API开发过程中重复开发、滥用数据等问题，提高API的使用率，最大程度的实现API的复用，减少冗余开发。

1. 进入API详情界面。
2. 若API还没有上架到API集市中时，您可单击API名称右侧的“上架API市场”按钮，并在右侧弹窗中，输入API需上架的相关缘由。
3. 上架理由填写完成后，单击确定按钮，完成API上架。
4. API上架完成后，您可前往API集市中进行查看和统一管理。操作详见“API集市”。