迁移到新的 Azure 时序见解第 2 代 API 版本
注意
时序见解服务将于 2024 年 7 月 7 日停用。 请考虑尽快将现有环境迁移到备用解决方案。 有关弃用和迁移的详细信息,请访问我们的文档。
概述
如果你创建了 Azure 时序见解第 2 代公共预览版环境(在 2020 年 7 月 16 日之前),请按照本文中所述的步骤将你的 TSI 环境更新为使用新的已正式发布的 API 版本。 此更改不会影响任何使用第 1 代版本的 Azure 时序见解的用户。
重要
本文中所述的更新只会升级 TSI 环境所用的 API 版本。 此更改与为第 2 代环境引入的新的 JSON 平展和转义规则无关。
新的 API 版本是 2020-07-31
,它使用了更新的2020-07-31
。
用户必须迁移其环境的时序模型变量,已保存的查询、Power BI 查询,以及调用 API 终结点的任何自定义工具。 如果你对迁移流程有任何疑问或问题,请通过 Azure 门户提交支持票证并提及此文档。
重要
API 预览版 2018-11-01-preview
会继续受支持,直到 2020 年 10 月 31日。 请在此日期之前完成此迁移的所有适用步骤,以避免服务中断。
迁移时序模型和已保存的查询
若要帮助用户迁移时序模型变量和已保存的查询,可通过 Azure 时序见解资源管理器使用内置工具。 导航到要迁移的环境,然后执行以下步骤。 你可以部分完成迁移,并在以后的某个时间回来完成迁移,但不能还原任何更新。
注意
你必须是环境的参与者,才能更新时序模型和已保存的查询。 如果你不是参与者,则只能迁移保存的个人查询。 继续操作之前,请查看环境访问策略和你的访问级别。
资源管理器会提示你更新时序模型变量和已保存查询所使用的语法。
如果你意外关闭了通知,可以在通知面板中找到该通知。
单击“显示更新”以打开迁移工具。
单击“下载类型”。 由于迁移将覆盖你的当前类型来更改变量语法,因此你需要保存当前类型的副本。 当完成类型下载时,该工具会发送通知。
单击“更新变量”。 当完成变量更新时,该工具会发送通知。
重要
如果你更新类型,则使用较旧 API 版本 (
2018-11-01-preview
) 的自定义应用程序需要使用新的 API 版本 (2020-07-31
) 才能继续工作。 如果你不确定所使用的 API 版本,请在更新前咨询你的管理员。 你可以关闭迁移工具,在以后回来执行这些步骤。 阅读有关如何迁移自定义应用程序的详细信息。单击“更新已保存的查询”。 当保存的查询已更新时,该工具会通知你。
单击“Done”(完成) 。
通过绘制一些新创建的变量和已保存的查询,查看更新的环境。 如果在绘图时出现任何意外行为,请使用资源管理器中的反馈工具向我们发送反馈。
迁移 Power BI 查询
如果已使用 Power BI 连接器生成查询,则它们会使用预览版 API 和旧的时序表达式语法调用 Azure 时序见解。 在预览版 API 被弃用之前,这些查询可继续成功检索数据。
若要更新查询以使用新的 API 版本和新的时序表达式语法,需要从资源管理器重新生成查询。 详细了解如何使用 Power BI 连接器创建查询。
注意
必须至少使用 2020 年 7 月版的 Power BI Desktop。 否则,可能会看到“查询有效负载版本无效”错误。
迁移自定义应用程序
如果你的自定义应用程序调用以下 REST 终结点,只需要在 URI 中将 API 版本更新为 2020-07-31
就够了:
对于以下 REST 终结点,你必须在 URI 中将 API 版本更新为 2020-07-31
,并确保 tsx
属性的所有实例都使用更新的2020-07-31
。
- 类型 API
- 查询 API
示例
TypesBatchPut
旧的请求正文(由 2018-11-01-preview
使用):
{
"put": [
{
"id": "c1cb7a33-ed9b-4cf1-9958-f3162fed8ee8",
"name": "OutdoorTemperatureSensor",
"description": "This is an outdoor temperature sensor.",
"variables": {
"AverageTemperature": {
"kind": "numeric",
"value": {
"tsx": "$event.[Temperature_Celsius].Double"
},
"filter": {
"tsx": "$event.[Mode].String = 'outdoor'"
},
"aggregation": {
"tsx": "avg($value)"
}
}
}
}
]
}
更新的请求正文(由 2020-07-31
使用):
{
"put": [
{
"id": "c1cb7a33-ed9b-4cf1-9958-f3162fed8ee8",
"name": "OutdoorTemperatureSensor",
"description": "This is an outdoor temperature sensor.",
"variables": {
"AverageTemperature": {
"kind": "numeric",
"value": {
"tsx": "$event['Temperature_Celsius'].Double"
},
"filter": {
"tsx": "$event['Mode'].String = 'outdoor'"
},
"aggregation": {
"tsx": "avg($value)"
}
}
}
}
]
}
另外,filter
还可以是 $event.Mode.String = 'outdoor'
。 value
必须使用括号对特殊字符 (_
) 进行转义。
GetEvents
旧的请求正文(由 2018-11-01-preview
使用):
{
"getEvents": {
"timeSeriesId": [
"006dfc2d-0324-4937-998c-d16f3b4f1952",
"T1"
],
"searchSpan": {
"from": "2016-08-01T00:00:00Z",
"to": "2016-08-01T00:16:50Z"
},
"filter": {
"tsx": "($event.[Value].Double != null) OR ($event.[Status].String = 'Good')"
},
"projectedProperties": [
{
"name": "Temperature",
"type": "Double"
}
]
}
}
更新的请求正文(由 2020-07-31
使用):
{
"getEvents": {
"timeSeriesId": [
"006dfc2d-0324-4937-998c-d16f3b4f1952",
"T1"
],
"searchSpan": {
"from": "2016-08-01T00:00:00Z",
"to": "2016-08-01T00:16:50Z"
},
"filter": {
"tsx": "($event.Value.Double != null) OR ($event.Status.String = 'Good')"
},
"projectedProperties": [
{
"name": "Temperature",
"type": "Double"
}
]
}
}
另外,filter
还可以是 ($event['Value'].Double != null) OR ($event['Status'].String = 'Good')
。
GetSeries
旧的请求正文(由 2018-11-01-preview
使用):
{
"getSeries": {
"timeSeriesId": [
"006dfc2d-0324-4937-998c-d16f3b4f1952"
],
"searchSpan": {
"from": "2016-08-01T00:00:00Z",
"to": "2016-08-01T00:16:50Z"
},
"inlineVariables": {
"pressure": {
"kind": "numeric",
"value": {
"tsx": "$event.[Bar-Pressure-Offset]"
},
"aggregation": {
"tsx": "avg($value)"
}
}
},
"projectedVariables": [
"pressure"
]
}
}
更新的请求正文(由 2020-07-31
使用):
{
"getSeries": {
"timeSeriesId": [
"006dfc2d-0324-4937-998c-d16f3b4f1952"
],
"searchSpan": {
"from": "2016-08-01T00:00:00Z",
"to": "2016-08-01T00:16:50Z"
},
"inlineVariables": {
"pressure": {
"kind": "numeric",
"value": {
"tsx": "$event['Bar-Pressure-Offset']"
},
"aggregation": {
"tsx": "avg($value)"
}
}
},
"projectedVariables": [
"pressure"
]
}
}
另外,value
还可以是 $event['Bar-Pressure-Offset'].Double
。 如果未指定数据类型,则始终假定数据类型为 Double。 必须使用括号表示法对特殊字符 (-
) 进行转义。
AggregateSeries
旧的请求正文(由 2018-11-01-preview
使用):
{
"aggregateSeries": {
"timeSeriesId": [
"006dfc2d-0324-4937-998c-d16f3b4f1952"
],
"searchSpan": {
"from": "2016-08-01T00:00:00Z",
"to": "2016-08-01T00:16:50Z"
},
"interval": "PT1M",
"inlineVariables": {
"MinTemperature": {
"kind": "numeric",
"value": {
"tsx": "coalesce($event.[Temp].Double, toDouble($event.[Temp].Long))"
},
"aggregation": {
"tsx": "min($value)"
}
},
},
"projectedVariables": [
"MinTemperature"
]
}
}
更新的请求正文(由 2020-07-31
使用):
"aggregateSeries": {
"timeSeriesId": [
"006dfc2d-0324-4937-998c-d16f3b4f1952"
],
"searchSpan": {
"from": "2016-08-01T00:00:00Z",
"to": "2016-08-01T00:16:50Z"
},
"interval": "PT1M",
"inlineVariables": {
"MinTemperature": {
"kind": "numeric",
"value": {
"tsx": "coalesce($event.Temp.Double, toDouble($event.Temp.Long))"
},
"aggregation": {
"tsx": "min($value)"
}
},
},
"projectedVariables": [
"MinTemperature"
]
}
}
另外,value
还可以是 coalesce($event['Temp'].Double, toDouble($event['Temp'].Long))
。
可能的错误
InvalidInput
如果看到以下错误,则表明你使用的是新的 API 版本 (2020-07-31
),但 TSX 语法尚未更新。 请查看时序表达式语法和上面的迁移示例。 重新提交 API 请求之前,请确保所有 tsx
属性都已正确更新。
{
"error": {
"code": "InvalidInput",
"message": "Unable to parse 'value' time series expression (TSX) in variable 'Temperature'.",
"target": "projectedVariables.Temperature.value",
"innerError": {
"parseErrorDetails": [
{
"pos": [
0,
5
],
"line": 1,
"msg": "Unsupported Time Series Expression version TSX01 used instead of TSX00.",
"code": "UnsupportedTSXVersionTSX01",
"target": "$event"
}
],
"code": "TsxParseError"
}
}
}