返回 登录
0

资产服务使用

点击下载全文http://events.csdn.net/chenmin/11-265-15.docx

描述Predix资产服务使用的RESTful API请求方法和参数。
客户端应用程序可以使用资产服务REST API端点访问资产数据。这些端点提供一个JSON接口,您可以将描述您的所有资产的数据提交至该接口。如果要使用这些API,您的应用程序需要发出HTTPS请求并分析响应。您可以使用任何网页开发语言访问API。
请求方法
资产服务支持POST、GET、PUT、PATCH和DELETE请求方法。
方法 描述
POST 创建或更新一组资源。您可以 POST 至一个集合,而不是一个特定资源。一个 POST 请求无法超过50 MB。
如果您打算使用审计历史,您需要将您的审计历史元数据添加到您的请求标头。
GET 检索资源。使用 GET /assets 返回所有域对象。
PUT 创建或更新一个单一资源。您可以将该方法用于个别资源,但是不能用于集合。
PATCH 更新一个资源属性的值。您可以添加、移除、修改和替换一个资源记录的值。您可以将该方法用于个别资源,但是不能用于集合。如果您关心网络效率,可以使用这种方法。
DELETE 移除或删除一个资源。您可以将该方法用于个别资源,但是不能用于集合。
最佳实践 - 添加审计历史元数据标头
如果您为资产每个写操作请求的用户定义元数据添加x-audit-metadata标头,那么以后您可以查询这些值的审计历史。将这个标头包含在您的其他请求标头中:
x-audit-metadata={“userId”:”abc”,”reason”.”xxx”,”evenTimestamp”:”2016-03-25T06:10:36.661+05:30”.eventId”.”new equip2”,”masterEventId”:new asset”,”otherInfo”:”yay”}
请求参数
资产服务支持以下请求参数:
请求参数 描述
fields 检索一个大对象的所选字段或大对象的集合。例如,从一个具有许多属性的资产中检索少量属性,表示在fields子句中的所选属性。参见部分响应请求

filter 使用一个GET请求的filter子句中的图形表达式语言(GEL)筛选结果中呈现的数据。参见图形表达式语言(GEL)句法

pageSize 定义每一页返回的实体的数量(默认值为100)。pageSize的最大值为1000。参见分页请求

以下样本请求使用filter和fields请求参数:
http:///locomotives?filter=type=Diesel-electric&fields=uri,model
在下表中描述请求句法:
请求项 描述
http:/// 从VCAP_SERVICES环境变量中获取的您的资产服务实例的URI。典型的URI类似于:http://predix-asset-rc.grc-apps.svc.ice.ge.com
/locomotives 您的请求的目标端点。
? 分隔端点与请求参数。
filter=type=Diesel-electric 筛选子句包含一个请求所有 locomotives 的GEL查询,所述locomotives的类型为 Diesel-electric。
& 分隔请求参数。
fields=uri,model 仅请求返回uri与model的子句。
参见样本资产服务API请求
图形表达式语言(GEL)句法
了解查询与更新Predix资产存储库所用的图形表达式语言(GEL)及其运算符。
使用一个API请求的filter子句中的图形表达式语言(GEL)运行针对资产服务数据的查询。您可以使用运算符的任意组合或多个相同类型的运算符。
您可以通过一个GEL查询中的filter子句筛选结果中呈现的数据。本部分通过示例列出了多个运算符和表达式,不过您可以使用运算符的任意组合或多个相同类型的运算符。筛选不允许用于POST、PUT、PATCH或DELETE请求。
GEL符号和运算符
构造GEL查询时使用以下句法。
符号 运算符 解释
() 使用括号替代默认的从左到右的运算顺序。然后首先在括号内从左到右求值。然后将单个结果用作一项用于括号外求值。
AND 将冒号”:”读作AND。”&”是一个保留字符,在URL中有特殊含义。
参见EQUALS (=)与AND (:)组合

| OR 将管道符”|”读作OR。
参见EQUALS (=)与OR (|)组合

.. RANGE 将两个句点(..)读作两个数字、两个日期或两个字符串之间的范围。
参见RANGE (..)运算符请求

在键和值中使用点字符
如果您的JSON键值中包括一个点字符,您需要在查询中对点(.)进行转义,以便将查询中点(.)之后的信息传递给服务器。否则,您的查询将被点截断。
uri: “/assets/1”, model.id: “76865”
如果要查询此信息: filter=model.id=76865
如果一个点出现在您的数据值中,无需对该点进行转义。
filter=hqLatLng.lat=47.655492
符号 运算符 解释
. 点 点(.)用于合并内部JSON对象的键。例如:value1.value2
如果一个键中包含一个点,您必须考虑到2种情况。
情况1:键在用户提交的数据中有点。在这种情况下,用户需要在查询时用反斜杠对其进行转义,这样就不会将它解释为GEL句法中的一个控制字符。
JSON示例:{uri: /assets/1, a.b : c}
对”c”的查询看起来就像:filter=a.b=c
情况2:键有一个在合并内部对象时形成的点。在这种情况下,不要对该点字符进行转义。
键在用户提交的数据中有点。在这种情况下,用户需要用反斜杠对其进行转义,这样就不会将它解释为GEL句法中的一个控制字符。
另一方面,如果值包含点字符,不要对其进行转义。
JSON示例:{uri : /assets/1, a:{b:c}}如果要在这种情况下查询”c”,不要对点进行转义。filter=a.b=c
.
RELATE运算
使用前向和后向相关请求查询您的资产模型中所存储对象的关系。有两种遍历关系的方式:
• 前向相关请求使用”>”运算符,在关系方向中遍历。
• 后向相关请求使用”<”运算符,在关系的反方向中遍历。
参见RELATE(”>”和“<”)运算符请求
符号 运算符 解释

FORWARD-RELATE 将大于号”>”读作前向相关。它根据谓语(属性键)选择当前所选的对象中存储的值。新选择是值的设置,而object.predicate==的值包括在当前的选择中。
[token] 带有传递闭包的FORWARD-RELATE 将方括号内的字母”t”以及后面的数字[tn]读作传递闭包令牌。例如,以下查询检索piston资产的所有父资产,在资产层级结构中上移五层:
/asset?filter=name=piston>parent[t5]
< BACKWARD-RELATE 将小于号”<”读作后向相关。如果谓语是另一个REST资源中的属性键,以及当前选择中一个REST资源的URI中的值,那么选择该对象。
例如,以下查询查找具有给定制造商的所有机车:
/locomotive?filter=(name=General Electric Transportation)

评论