您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

迁移到新的 Azure 时序见解第 2 代 API 版本

概述

如果你创建了 Azure 时序见解第 2 代公共预览版环境(在 2020 年 7 月 16 日之前),请按照本文中所述的步骤将你的 TSI 环境更新为使用新的已正式发布的 API 版本。 此更改不会影响任何使用第 1 代版本的 Azure 时序见解的用户。

重要

本文中所述的更新只会升级 TSI 环境所用的 API 版本。 此更改与为第 2 代环境引入的新的 JSON 平展和转义规则无关。

新的 API 版本是 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版本的 Power BI Desktop。 否则,可能会显示 "查询负载版本无效" 错误。

迁移自定义应用程序

如果你的自定义应用程序调用以下 REST 终结点,只需要在 URI 中将 API 版本更新为 2020-07-31 就够了:

对于以下 REST 终结点,你必须在 URI 中将 API 版本更新为 2020-07-31,并确保 tsx 属性的所有实例都使用更新的时序表达式语法

示例

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

后续步骤