迁移到新的 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 时序见解资源管理器使用内置工具。 导航到要迁移的环境,然后执行以下步骤。 你可以部分完成迁移,并在以后的某个时间回来完成迁移,但不能还原任何更新。

注意

你必须是环境的参与者,才能更新时序模型和已保存的查询。 如果你不是参与者,则只能迁移保存的个人查询。 继续操作之前,请查看环境访问策略和你的访问级别。

  1. 资源管理器会提示你更新时序模型变量和已保存查询所使用的语法。

    提示

    如果你意外关闭了通知,可以在通知面板中找到该通知。

  2. 单击“显示更新”以打开迁移工具。

  3. 单击“下载类型”。 由于迁移将覆盖你的当前类型来更改变量语法,因此你需要保存当前类型的副本。 当完成类型下载时,该工具会发送通知。

    下载类型

  4. 单击“更新变量”。 当完成变量更新时,该工具会发送通知。

    重要

    如果你更新类型,则使用较旧 API 版本 (2018-11-01-preview) 的自定义应用程序需要使用新的 API 版本 (2020-07-31) 才能继续工作。 如果你不确定所使用的 API 版本,请在更新前咨询你的管理员。 你可以关闭迁移工具,在以后回来执行这些步骤。 阅读有关如何迁移自定义应用程序的详细信息。

    更新变量

  5. 单击“更新已保存的查询”。 当保存的查询已更新时,该工具会通知你。

    更新已保存的查询

  6. 单击“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

示例

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"
        }
    }
}