文档

自定义服务API

更新时间:

除了使用预置指标API和产品数据API外,您还可以根据业务需要,新建自定义服务API获取数据指标和自定义存储表的数据。本文介绍如何创建自定义服务API。

前提条件

已创建数据源相关的指标和存储表,具体信息,请参见指标概述自定义存储表

操作步骤

  1. 物联网平台控制台实例概览页面,单击目标企业版实例ID或备注名称。

  2. 在左侧导航栏,选择数据服务 > 数据API

  3. 数据API页面,单击自定义服务API页签,然后单击新建API

  4. 新建API配置向导页面,完成API基本信息的配置,然后单击下一步

    参数

    描述

    API名称

    输入API名称。支持中文、英文字母、数字、下划线(_)和短划线(-)。长度不超过30个字符。

    API Path

    输入API路径。作为API资源标识符,实例下具有唯一性。

    调用API时,请求参数中apiPath的值与之对应。

    以正斜线(/)开头,支持英文字母、数字、下划线(_)、正斜线(/),长度不超过128个字符。例如:pk/temperatureMax

    重要

    API发布后,API Path不支持修改。

    API标签

    输入标签内容后,按回车键,生成标签。

    支持中文、英文字母、数字、下划线(_)和短划线(-)。长度不超过30个字符。

    使用标签功能,为API自定义标识,以便灵活管理API。

    重要

    一个API最多可添加5个标签。

    API描述

    输入API的描述,说明API的功能等信息。

    返回类型

    调用API后,返回数据的格式,固定为JSON。

  5. 配置参数并测试页面,完成以下配置。

    类别

    配置项

    说明

    数据来源

    指标

    选择具体指标域数据集

    数据集是指标域的具体对象组织,例如产品域下具体产品,设备域下具体设备。

    指标详细信息,请参见什么是指标

    存储表

    选择通过数据解析或SQL分析任务,输出的自定义存储表。

    更多信息,请参见冷数据存储表

    配置参数

    数据集

    数据来源选择指标,并选择具体指标域数据集后,自动显示所选的数据来源。

    单击预览数据,可跳转至该数据来源的详情页面。

    数据范围

    数据来源选择指标,展示该配置项。

    选择API的数据范围:

    • 衍生指标:基于原始指标、原始定义、衍生定义,经过求和、计算平均数等汇总计算方式得到的数据。

    • 衍生定义:以原始定义为基础,并应用到子实体上的原始定义指标的衍生。

    衍生指标和定义说明,请参见指标类型

    请求参数

    单击添加参数,将所选数据来源的指标,添加到API的请求参数。仅支持系统字段及自定义存储表的主键字段。

    添加的参数需包括绑定字段、参数名、参数类型、操作符、必选、示例值、参数描述。

    重要

    参数类型为数值型时,操作符不支持LIKE

    返回参数

    单击添加参数,将所选数据来源的指标,添加到API的返回参数。

    添加的参数需包括优先级、绑定字段、参数名、参数类型、用于排序、示例值、参数描述。

    选中页面右侧的选择全部参数复选框,API的返回参数会包括所有已定义的表字段。

    说明
    • 用于排序是指对查询获取的数据根据该字段的值进行排序(升序或降序),排序后再返回查询结果。

    • 在返回参数里,一个指标仅能被配置成一个参数。

    排序方式

    选择参数的排列顺序。

    • 升序(默认):参数以升序排列。

    • 降序:参数以降序排列。

    高级设置

    开启返回结果分页

    选择是否开启返回结果分页。

    • 不开启:仅可查看100条以内的返回结果。

    • 开启:可分页查看所有返回结果。开启后,自动增加以下公共参数:

      • pageNum:分页的页码。

      • pageSize:每页显示结果的条数,最大值为100。

    超时报错设置

    调用API的请求超过8000毫秒时,返回超时报错。不支持修改该参数。

    完成上述配置后,在测试API区域内,输入请求参数的测试值后,单击开始测试

    您可在返回示例页签查看返回的示例数据,也可单击请求详情查看发起请求后的具体信息。测试API

  6. 单击发布

    重要
    • 发布API前,需确保该API已通过测试。

    • 仅单击保存的API,显示状态为未上线。

    • 未完成配置的API,可单击对应的编辑,完成配置后发布上线。

    • 仅可删除未上线和已下线的API。

    发布成功页面,单击再次新建,可创建多个自定义API;单击去列表查看,可查看已创建的API。发布成功

后续操作

已创建的自定义服务API可以调用来获取数据。具体操作,请参见管理与使用

调用示例,请参见:

  • 本页导读 (1)
文档反馈