您可调用数据服务下的基础服务API或新建自定义服务API,以获取所需数据,实现服务器与物联网平台的系统级对接。通过数据服务平台,您还可运维和监控API的使用情况。本文介绍数据服务及其使用方法。

背景信息

  • 基础服务API:您可直接调用默认的基础服务API,获取指定的设备数据,例如:任意时间段内每日设备数量相关统计、历史至今设备数量相关统计等。更多信息,请参见查看与使用
  • 自定义服务API:您可根据业务需要,新建自定义服务API。具体操作,请参见新建自定义API

前提条件

已创建数据源相关的指标和数据集,具体信息,请参见指标概述

新建自定义API

  1. 登录物联网平台控制台
  2. 实例概览页面,找到对应的数据型实例,单击实例进入实例详情页面。
  3. 在左侧导航栏,选择数据分析 > 数据服务
  4. API列表,单击自定义服务API,然后单击新建API新建API
  5. 新建API页面,完成API基本信息的配置,然后单击下一步API基本信息
    参数 描述
    API名称 输入API名称。支持中文、英文字母、数字、下划线(_)。长度不超过30个字符。
    API Path 输入API路径。作为API资源标识符,实例下具有唯一性。调用API时,请求参数中apiPath的值与之对应。以正斜线(/)开头,支持英文字母、数字、下划线(_)、正斜线(/),长度不超过128个字符。例如:pk/temperatureMax
    注意 API发布后,不可修改该参数。
    API标签 输入标签内容后,按回车键,生成标签。

    使用标签功能,为API自定义标识,以便灵活管理API。一个API最多可添加5个标签。

    API描述 输入API的描述,说明该API的功能等信息。
    返回类型 调用API后,返回数据的格式,固定为JSON。
  6. 配置参数并测试页面,完成以下配置。
    类别 参数 说明
    数据源 指标域 选择指标域。指标域是指标所属的对象,用于分类管理指标。更多信息,请参见什么是指标
    数据集 选择对应指标域的数据集。数据集是指定指标域下设备数据的集合。更多信息,请参见数据集概述
    配置参数 数据集 完成数据源配置后,自动显示所选的数据集。单击预览数据,可跳转至该数据集的详情页。
    数据范围 选择API的数据范围。
    • 衍生指标:基于原始指标、原始定义、衍生定义,经过加和、平均等汇总计算方式得到的数据。
    • 衍生定义:以原始定义为基础,并应用到子实体上的原始定义指标的衍生。

    更多信息,请参见指标类型

    请求参数 单击添加参数,将所选数据集的指标,添加到API的请求参数。单个指标可配置成多个不同的请求参数。

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

    注意 参数类型为数值型时,操作符不支持LIKE
    返回参数 单击添加参数,将所选数据集的指标,添加到API的返回参数。

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

    注意 单个指标不可配置成多个返回参数。
    排序方式 选择参数的排列顺序。
    • 升序:参数以升序排列。默认排序为升序。
    • 降序:参数以降序排列。
    高级设置 开启返回结果分页 选择是否开启返回结果分页。
    • 不开启:仅可查看200条以内的返回结果。
    • 开启:可分页查看所有返回结果。开启后,自动增加以下公共参数:
      • pageNum:分页的页码。
      • pageSize:每页显示结果的条数,最大值为200。
      • totalNum:返回结果的总页数。仅返回参数中有此参数。
    超时报错设置 调用API的请求超过8000毫秒时,返回超时报错。不支持修改该参数。

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

    您可在返回示例页签查看返回的示例数据,也可单击请求详情查看发起请求后的具体信息。测试API
  7. 单击发布
    注意
    • 发布API前,需确保该API已通过测试。
    • 仅单击保存的API,显示状态为未上线。
    • 未完成配置的API,可单击对应的编辑,完成配置后发布上线。
    • 仅可删除未上线和已下线的API,删除后7天内可提交工单,申请恢复。
    发布成功页面,单击再次新建,可创建多个自定义API;单击去列表查看,可查看已创建的API。发布成功

查看与使用

  1. 在左侧导航栏,选择数据分析 > 数据服务
  2. 数据服务页面的API列表,单击基础服务API自定义服务API页签,找到要查看的API,再单击对应API的查看数据服务页面
  3. 在API详情页的右上角,选择版本号,查看对应版本的API详情。
    • API运维页签,您可查看API的使用情况。
    • 单击API测试,您可测试API。
    • 根据API的详情信息,您可在自己的服务器集成并调用对应API,获取相关数据,以充分利用数据资产。API详情页
      • 如果您使用阿里云提供的SDK,可参考以下语言的调用示例:
      • 如果您不使用阿里云提供的SDK,开发时则需注意以下公共参数。
        名称 类型 是否必传 示例值 描述
        apiPath String pk/temperatureMax API路径。
        iotInstanceId String iot-cn-npk1u****** 实例ID。公共实例不传此参数,企业版实例需传入。
        pageNum Integer 开启分页时必传 10 分页的页码。
        pageSize Integer 开启分页时必传 100 每页显示结果的条数,最大值为200。