sql-admin-evaluate-azure-migration-assessment

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Evaluate Azure Migration Assessment

评估 Azure 迁移评估

When to Use

使用时机

Use for a general request to run/refresh a migration assessment for an Azure SQL Server instance.
适用于用户笼统地要求为 Azure SQL Server 实例运行或刷新迁移评估的场景。

Required tools

所需工具

  • An authenticated Azure Resource Manager client for the requests in
    references/api-contracts.md
    : Az PowerShell
    Invoke-AzRestMethod
    (needed for the telemetry step, which reads a response header) or Azure CLI
    az rest
    , signed in with
    Connect-AzAccount
    or
    az login
    as an identity with the permissions listed in
    references/arm-resource-identification.md
    .
  • Azure Resource Graph access (
    az graph query
    or
    Search-AzGraph
    ) for resource discovery and the existing-assessment check.
  • A shell or scripting runtime that can decode base64 and gzip for telemetry decoding.
If these are not available, give the user the requests to run and ask for the results.
  • 用于执行
    references/api-contracts.md
    中请求的已认证 Azure Resource Manager 客户端:Az PowerShell
    Invoke-AzRestMethod
    (遥测步骤需要读取响应头,因此必须使用此工具),或 Azure CLI
    az rest
    。需通过
    Connect-AzAccount
    或
    az login
    登录,且所用身份必须具有
    references/arm-resource-identification.md
    中列出的权限。
  • Azure Resource Graph 访问权限(
    az graph query
    或
    Search-AzGraph
    ),用于发现资源和检查现有评估。
  • 能够解码 base64 和 gzip 的 shell 或脚本运行时,用于解码遥测数据。
如果这些工具不可用,请向用户提供需要运行的请求,并要求其返回结果。

Workflow

工作流

Step 1: Resolve the Resource

步骤 1:解析资源

Collect subscription, resource group, and instance name using
references/arm-resource-identification.md
if not in context. Load the ARM request definitions from
references/api-contracts.md
.
When a subscription ID is available, use it directly. For an instance name without a subscription, search all accessible subscriptions with a page size of 1000 and
name =~ '{instanceName}'
; do not ask for a subscription first or add
| top
to the KQL. Continue for one match, ask for multiple matches, and report no match when none is found.
如果上下文中没有订阅、资源组和实例名称,请使用
references/arm-resource-identification.md
收集这些信息。然后从
references/api-contracts.md
加载 ARM 请求定义。
如果已获得订阅 ID,请直接使用。对于未提供订阅的实例名称,请以 1000 为页面大小,使用
name =~ '{instanceName}'
搜索所有可访问的订阅;不要先询问用户订阅信息,也不要在 KQL 中添加
| top
。仅有一个匹配项时继续执行;出现多个匹配项时请用户进一步确认;未找到匹配项时报告无匹配结果。

Step 2: Check Existing Assessment

步骤 2:检查现有评估

Always check for an existing assessment first for a general request such as "run migration assessment".
Use the
sql-admin-get-migration-assessment
skill with the resolved identifiers.
  • Existing data and no explicit refresh request -> render it as
    sql-admin-get-migration-assessment
    describes for existing ARG data, then stop. Use the saved preferred option and matching
    monthlyCostOptions
    entry for the cost; do not label an existing-ARG amount as a fresh default estimate. State that the user can request refresh or rerun to generate a new assessment; do not ask for confirmation.
  • Explicit refresh, rerun, replace, new/fresh, or ignore-existing request -> retain the returned strategy and cost-option settings, then continue to Step 3 without rendering the existing result or asking for confirmation.
  • Enabled with no data -> continue to Step 3.
  • Explicitly disabled -> offer ARM or portal enablement.
The word run by itself is not an explicit refresh request.
对于“运行迁移评估”之类的笼统请求,始终先检查是否存在现有评估。
使用解析出的标识符调用
sql-admin-get-migration-assessment
skill。
  • 存在数据且用户未明确要求刷新 -> 按照
    sql-admin-get-migration-assessment
    针对现有 ARG 数据所描述的方式呈现结果,然后停止。成本应使用已保存的首选选项及与之匹配的
    monthlyCostOptions
    条目;不要将现有的 ARG 金额标记为最新的默认估算。告知用户可以请求 刷新 或 重新运行 以生成新的评估;不要请求确认。
  • 用户明确要求 刷新、重新运行、替换、新建/全新评估 或忽略现有结果 -> 保留返回的策略和成本选项设置,然后继续执行步骤 3,不呈现现有结果,也不请求确认。
  • 已启用但没有数据 -> 继续执行步骤 3。
  • 明确禁用 -> 提供通过 ARM 或启用门户配置的选项。
单独出现 运行 一词并不构成明确的刷新请求。

Step 3: Trigger and Monitor Assessment

步骤 3:触发并监控评估

Retain the accepted trigger response's
backgroundJob.startTime
; use it as the freshness bound only if the actual UTC request time is unavailable. The response's
lastExecutionTime
can belong to a previous assessment and is not the new start.
Record the trigger request time and execute the trigger and job-monitoring contracts from
references/api-contracts.md
.
  • 2xx or 409 -> continue.
  • Other 4xx/5xx -> report the error and stop.
  • InProgress
    -> you MUST continue the defined wait-and-poll loop in the same turn; NEVER ask the user whether to continue polling.
  • Succeeded
    with
    lastExecutionTime
    later than the trigger request time -> continue to Step 4.
  • Succeeded
    with an older
    lastExecutionTime
    -> continue polling.
  • Failed
    -> show
    jobException
    and stop.
  • Still running after the polling window -> show the portal link and stop; the user can return later to refresh.
保留已接受的触发响应中的
backgroundJob.startTime
;仅当无法获取实际的 UTC 请求时间时,才将其用作新鲜度界限。响应中的
lastExecutionTime
可能属于之前的评估,不能作为本次评估的新开始时间。
记录触发请求的时间,并执行
references/api-contracts.md
中的触发和作业监控契约。
  • 返回 2xx 或 409 -> 继续执行。
  • 返回其他 4xx/5xx -> 报告错误并停止。
  • InProgress
    -> 必须在同一轮中继续执行定义的等待和轮询循环;绝不要询问用户是否继续轮询。
  • Succeeded
    且
    lastExecutionTime
    晚于触发请求时间 -> 继续执行步骤 4。
  • Succeeded
    但
    lastExecutionTime
    早于触发请求时间 -> 继续轮询。
  • Failed
    -> 显示
    jobException
    并停止。
  • 轮询窗口结束后仍在运行 -> 显示门户链接并停止;用户可以稍后返回并刷新。

Step 4: Retrieve Telemetry

步骤 4:检索遥测数据

Execute the telemetry retrieval contract from
references/api-contracts.md
and poll the returned signed
Azure-AsyncOperation
URL as defined there.
  • Succeeded
    -> decode the response.
  • Failed
    or
    Canceled
    -> report the error.
  • Timeout -> show the portal link and stop.
执行
references/api-contracts.md
中的遥测检索契约,并按照其中的定义轮询返回的带签名
Azure-AsyncOperation
URL。
  • Succeeded
    -> 解码响应。
  • Failed
    或
    Canceled
    -> 报告错误。
  • 超时 -> 显示门户链接并停止。

Step 5: Confirm Fresh Results

步骤 5:确认结果为最新

Decode the portal's four telemetry report families:
  • Suitability
    /
    Suitability_V2
    .
  • SKURecommendation_AzureSQLVM
    /
    _V2
    .
  • SKURecommendation_AzureSQLMI
    /
    _V2
    .
  • SKURecommendation_AzureSQLDB
    /
    _V2
    .
Keep each Suitability
Databases[]
entry's
Properties.Name
and its own
DatabaseAssessments
together. Never join names and findings by array position or independently sorted names.
For each family, select the report with the newer telemetry
ObservedTimestampUTC
. Use Suitability for readiness and blockers, and the three SKU reports for sizing and recommendation details.
Compare the selected Suitability
EndedOn
with the trigger request time after converting both to UTC. Also require each available selected SKU report's
ObservedTimestampUTC
to be later than the trigger request time. If any selected report is stale, wait 10 seconds and POST a new getTelemetry request, then decode its new operation result, up to three retries. GET polling a completed operation only rereads the same snapshot. If freshness is still unresolved, report pending propagation without showing old sizing or cost as fresh. Use the job only for running, fresh success, and failure state.
Use the selected fresh telemetry reports as the source for readiness, blockers, target SKU, requirements, recommendation details, and available monetary cost fields. Reuse retained cost-option settings only to name the preferred option; never pair a fresh SKU with a pre-trigger cost amount.
解码门户中的四类遥测报告:
  • Suitability
    /
    Suitability_V2
    。
  • SKURecommendation_AzureSQLVM
    /
    _V2
    。
  • SKURecommendation_AzureSQLMI
    /
    _V2
    。
  • SKURecommendation_AzureSQLDB
    /
    _V2
    。
将每个 Suitability
Databases[]
条目的
Properties.Name
与其对应的
DatabaseAssessments
保留在一起。绝不要按数组位置或分别排序后的名称将数据库名称与评估结果关联起来。
对于每一类报告,选择遥测
ObservedTimestampUTC
较新的报告。使用 Suitability 报告确定就绪状态和阻碍项,使用三个 SKU 报告确定规模调整和推荐详情。
将所选 Suitability 报告的
EndedOn
和触发请求时间转换为 UTC 后进行比较。同时,所选的每份可用 SKU 报告的
ObservedTimestampUTC
都必须晚于触发请求时间。如果任何所选报告已过期,请等待 10 秒并 POST 一个新的 getTelemetry 请求,然后解码其新的操作结果,最多重试三次。对已完成操作执行 GET 轮询只会重新读取同一快照。如果仍无法确定结果是否为最新,请报告传播仍在进行中,不要将旧的规模调整或成本显示为最新结果。作业状态仅用于表示正在运行、成功且结果新鲜,或失败状态。
使用所选的最新遥测报告作为就绪状态、阻碍项、目标 SKU、要求、推荐详情和可用货币成本字段的数据来源。保留的成本选项设置只能用于确定首选选项的名称;绝不要将最新的 SKU 与触发前的成本金额配对使用。

Step 6: Render

步骤 6:呈现结果

Use the recommended target and available default cost from the fresh telemetry selected in Step 5. Label that amount as the fresh default estimate and direct the user to the portal report for the current preferred-option and AHB-adjusted cost. This step applies only after Steps 3-5 complete a fresh assessment.
Use
references/assessment-output.md
to render the combined readiness and SKU recommendation. Include the portal report link.
使用步骤 5 中所选的最新遥测数据中的推荐目标和可用默认成本。将该金额标记为最新的默认估算,并引导用户查看门户报告,以获取当前的首选成本选项和经 AHB 调整的成本。仅当步骤 3-5 已完成一次全新评估后,才适用此步骤。
使用
references/assessment-output.md
呈现组合后的就绪状态和 SKU 推荐。包含门户报告链接。

Notes

注意事项

  • Follow the API definitions in
    references/api-contracts.md
    .
  • The telemetry operation URL comes from
    getTelemetry
    .
  • Treat a successful telemetry LRO as report-read completion. Use
    MigrationJobOnDemand
    for assessment-job completion.
  • Use
    EndedOn
    as the generated time.
  • Use only the recommended target and user databases in output.
  • 遵循
    references/api-contracts.md
    中的 API 定义。
  • 遥测操作 URL 来自
    getTelemetry
    。
  • 将成功的遥测 LRO 视为报告读取完成。使用
    MigrationJobOnDemand
    判断评估作业是否完成。
  • 将
    EndedOn
    作为生成时间。
  • 输出中仅包含推荐目标和用户数据库。

References

参考资料

  • references/api-contracts.md
  • references/arm-resource-identification.md
  • references/assessment-output.md
  • references/api-contracts.md
  • references/arm-resource-identification.md
  • references/assessment-output.md