资产服务使用

点击下载全文：http://events.youkuaiyun.com/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)