管理长时间运行的操作

本页面介绍如何管理 Cloud Healthcare API 长时间运行的操作 (LRO) 的生命周期。

如果 API 方法可能需要很长时间才能完成，则可以向客户端返回 Operation。客户端可以通过轮询操作，使用 Operation 接口异步检索 API 方法的状态。Cloud Healthcare API 中的 LRO 遵循 Google Cloud LRO 设计模式。

Cloud Healthcare API 会针对多种方法（例如 projects.locations.datasets.fhirStores.import）创建 LRO。调用 projects.locations.datasets.fhirStores.import 时，Cloud Healthcare API 会创建 LRO 来跟踪导入状态。LRO 具有唯一标识符，可用于查看 LRO 的状态。

LRO 可在数据集级层进行管理。如果您要调用返回 LRO 的方法（如 projects.locations.datasets.fhirStores.import），则可以通过将包含 LRO ID 的请求发送到发生导入的 FHIR 存储区的父数据集，从而查看 LRO 的状态。

除了 REST API 之外，当您调用返回 LRO 的方法中列出的方法时，以下来源也会生成长时间运行的操作：

Google Cloud CLI
Google Cloud 控制台中的 Cloud Healthcare API 页面

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST API 管理 Cloud Healthcare API LRO。

在 LR 完成之后，LRO 的记录会保留大约 30 天，也就是说，在这段时间之后，您将无法再查看或列出 LRO。

返回 LRO 的方法

以下方法会返回 LRO。

意见征求管理方法：

projects.locations.datasets.consentStores.queryAccessibleData

数据集方法：

DICOM 方法：

FHIR 方法：

HL7v2 方法：

获取有关 LRO 的详细信息

以下示例展示了如何获取 LRO 的详细信息。

在获取关于 LRO 的详细信息时，响应中显示的 Cloud Healthcare API 版本与启动 LRO 的方法的 API 版本相同。

控制台

使用 gcloud CLI 或 API 调用方法来返回 LRO 后，您可以在 Google Cloud 控制台中查看有关 LRO 的详细信息。

在 Google Cloud 控制台中，进入数据集页面。

前往“数据集”页面
点击包含要查看的 LRO 的数据集名称。
点击操作。
如需在 Cloud Logging 中查看操作的错误日志，请点击操作，然后点击在 Cloud Logging 中查看详情。如需了解详情，请参阅在 Cloud Logging 中查看错误日志。
如需查看操作的更多详细信息，请点击正在运行的操作 ID。系统会显示长时间运行的操作详情页面。该页面会显示以下信息：
- LRO 的进度
- LRO 的详细信息，例如操作 ID 和调用 LRO 的方法
- 日志条目的一部分

gcloud

假设您在调用 gcloud healthcare dicom-stores deidentify 后收到以下响应：

Request issued for: [DATASET_ID]
Waiting for operation [OPERATION_ID] to complete...

该响应显示，Cloud Healthcare API 创建了一个带有操作 ID 的 LRO。您还可以通过列出长时间运行的数据库操作来检索操作 ID。该命令会持续运行，直到运行完成，然后输出以下内容：

Request issued for: [DATASET_ID]
Waiting for operation [OPERATION_ID] to complete...done
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID

如需获取有关 LRO 的详细信息，请运行 gcloud healthcare operations describe 命令。

在使用下面的命令数据之前，请先进行以下替换：

PROJECT_ID：您的 Google Cloud 项目的 ID
DATASET_ID：数据集 ID
LOCATION：数据集位置
OPERATION_ID：从长时间运行的操作返回的 ID

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud healthcare operations describe OPERATION_ID \
    --project=PROJECT_ID \
    --dataset=DATASET_ID \
    --location=LOCATION

Windows (PowerShell)

gcloud healthcare operations describe OPERATION_ID `
    --project=PROJECT_ID `
    --dataset=DATASET_ID `
    --location=LOCATION

Windows (cmd.exe)

gcloud healthcare operations describe OPERATION_ID ^
    --project=PROJECT_ID ^
    --dataset=DATASET_ID ^
    --location=LOCATION

您应该会收到类似如下所示的响应：

响应

done: true
// If there were any errors, an `error` field displays instead of a `response` field.
// See Troubleshooting long-running operations for a list of response codes.
error: ERROR
  code: ERROR_CODE
  message: DESCRIPTION
metadata:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata'
  apiMethodName: 'google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore'
  counter:
    success: 'SUCCESS_COUNT'
    // If there were any failures, they display in the `failure` field.
    failure: 'FAILURE_COUNT'
  createTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  endTime: 'YYYY-MM-DDTHH:MM:SS+ZZ:ZZ'
  logsUrl: https://console.cloud.google.com/CLOUD_LOGGING_URL
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID
// The `response` field only displays if there were no errors.
response:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary'

REST

假设您在调用 projects.locations.datasets.dicomStores.deidentify 后收到以下响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

响应中的 name 值表明 Cloud Healthcare API 创建了一个名为 projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID 的 LRO。您还可以通过列出 LRO 来检索 LRO 名称。

如需获取 LRO 的状态，请使用 projects.locations.datasets.operations.get 方法。如需轮询 LRO，请重复调用 projects.locations.datasets.operations.get 方法，直到操作完成。在每个轮询请求之间使用退避时间，例如 10 秒。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的 Google Cloud 项目的 ID
DATASET_ID：数据集 ID
LOCATION：数据集位置
OPERATION_ID：从长时间运行的操作返回的 ID

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户帐号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的帐号。

执行以下命令：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

PowerShell

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

API Explorer

打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。填写所有必填字段，然后点击执行。

输出如下所示。如果响应包含 "done": true，则表示长时间运行的操作已完成。

响应

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  // The `response` field only displays if there were no errors.
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary"
  },
  // If there were any errors, an `error` field displays instead of a `response` field.
  // See Troubleshooting long-running operations for a list of response codes.
  "error": {
    "code": ERROR_CODE,
    "message": "DESCRIPTION",
    "details": [
      {
        "@type": "...",
        FIELD1: ...,
        ...
      }
    ]
  }
}

列出 LRO

以下示例展示了如何列出数据集中的 LRO。

控制台

如需在 Google Cloud 控制台中查看数据集内所有 LRO 的列表，请完成以下步骤：

在 Google Cloud 控制台中，进入数据集页面。

前往“数据集”页面
点击包含要查看的 LRO 的数据集名称。
点击操作。

此时将显示数据集中的 LRO 列表及其状态。如需在 Cloud Logging 中查看错误日志，请点击最后一列中的“更多信息”图标，然后点击在 Cloud Logging 中查看详情。如需了解详情，请参阅在 Cloud Logging 中查看错误日志。

gcloud

如要列出数据集中的 LRO，请运行 gcloud healthcare operations list 命令。

在使用下面的命令数据之前，请先进行以下替换：

DATASET_ID：数据集 ID
LOCATION：数据集位置

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Windows (PowerShell)

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Windows (cmd.exe)

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

您应该会收到类似如下所示的响应：

响应

ID             LOCATION     DONE
OPERATION_ID   LOCATION {TRUE|FALSE}
...

REST

如需列出数据集中的 LRO，请使用 projects.locations.datasets.operations.get 方法。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的 Google Cloud 项目的 ID
DATASET_ID：数据集 ID
LOCATION：数据集位置

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations"

PowerShell

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations" | Select-Object -Expand Content

API Explorer

打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。填写所有必填字段，然后点击执行。

您应该收到类似以下内容的 JSON 响应：

响应

{
  "operations": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
        "apiMethodName": "google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore",
        "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
        "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
        "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
        "counter": {
          "success": "SUCCESS_COUNT",
          // If there were any failures, they display in the `failure` field.
          "failure": "FAILURE_COUNT"
        }
      },
      "done": true,
      // The `response` field only displays if there were no errors.
      "response": {
        "@type": "type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary"
      },
      // If there were any errors, an `error` field displays instead of a `response` field.
      // See Troubleshooting long-running operations for a list of response codes.
      "error": {
        "code": ERROR_CODE,
        "message": "DESCRIPTION",
        "details": [
          {
            "@type": "...",
            FIELD1: ...,
            ...
          }
        ]
      }
    },
    ...
  ]
}

取消 LRO

以下示例展示了如何在数据集中取消 LRO。

控制台

如需在 Google Cloud 控制台中取消 LRO，请完成以下步骤：

在 Google Cloud 控制台中，进入数据集页面。

前往“数据集”页面
点击包含要查看的 LRO 的数据集名称。
点击操作。
在要取消的 LRO 所在的行中，打开操作列表，然后点击停止操作。

REST

要取消 LRO，请使用 projects.locations.datasets.operations.cancel 方法。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的 Google Cloud 项目的 ID
DATASET_ID：数据集 ID
LOCATION：数据集位置
OPERATION_ID：从长时间运行的操作返回的 ID

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d "" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID:cancel"

PowerShell

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID:cancel" | Select-Object -Expand Content

API Explorer

打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。填写所有必填字段，然后点击执行。

您应该收到类似以下内容的 JSON 响应：

响应

{}

如需查看取消请求的状态，请使用 projects.locations.datasets.operations.get 方法。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的 Google Cloud 项目的 ID
DATASET_ID：数据集 ID
LOCATION：数据集位置
OPERATION_ID：从长时间运行的操作返回的 ID

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

PowerShell

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

API Explorer

打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。填写所有必填字段，然后点击执行。

您应该收到类似以下内容的 JSON 响应：

响应

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "API_METHOD_NAME",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "cancelRequested": true,
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  "error": {
    "code": 1,
    "message": "Operation cancelled by user. Any progress already completed by the operation will not be reverted."
  }
}

取消多个 LRO

如需取消多个 LRO，请完成以下步骤：

调用 operations.list 方法以获取数据集中操作的名称。
对每个操作调用 operations.cancel 方法。

Google 提供了一个 Python 脚本，可用于取消给定数据集的所有操作。

对 LRO 进行问题排查

当 LRO 失败时，其响应包含规范 Google Cloud 错误代码。下表解释了每个代码的原因以及有关如何处理代码的建议。对于许多错误，建议的操作是使用指数退避算法重试该请求。如需了解如何在 Cloud Healthcare API 中实现指数退避算法，请参阅重试失败的请求。

代码	枚举	说明	建议采取的操作
1	`CANCELLED`	操作已取消（通常是被调用者取消）。	如果需要，请重新运行该操作。
2	`UNKNOWN`	当从另一个地址空间接收到的 `Status` 值属于此地址空间中未知的错误空间时，可能返回此错误。如果 API 错误没有返回足够的信息，该错误可能会转换为此错误。	请使用指数退避算法重试。
3	`INVALID_ARGUMENT`	客户端指定的参数无效。此错误与 `FAILED_PRECONDITION` 不同。无论系统状态如何，`INVALID_ARGUMENT` 都会指出有问题的参数，例如文件名格式错误。	在解决问题之前，请勿重试。
4	`DEADLINE_EXCEEDED`	期限已到，但操作尚未完成。对于更改系统状态的操作，即使操作已成功完成，也可能会返回此错误。例如，服务器的成功响应可能会延迟足够长的时间以使截止期限过期。	请使用指数退避算法重试。
5	`NOT_FOUND`	未找到所请求的某个实体，例如 FHIR 资源。	在解决问题之前，请勿重试。
6	`ALREADY_EXISTS`	客户端尝试创建的实体（例如 DICOM 实例）已存在。	在解决问题之前，请勿重试。
7	`PERMISSION_DENIED`	调用方无权执行指定的操作。此错误代码并不意味着请求有效、请求的实体存在或满足其他前提条件。	在解决问题之前，请勿重试。
8	`RESOURCE_EXHAUSTED`	部分资源（如每个项目的配额）已用尽。如需了解推荐操作，请参阅配额管理最佳实践。	请使用指数退避算法重试。配额可能会随着时间的推移而可用。
9	`FAILED_PRECONDITION`	操作被拒绝，因为系统未处于执行该操作所需的状态。例如，要删除的目录非空，或者 `rmdir` 操作应用于非目录。	在解决问题之前，请勿重试。
10	`ABORTED`	操作已中止，通常是由于序列程序检查失败或事务中止等并发问题。	请使用指数退避算法重试。
11	`OUT_OF_RANGE`	尝试执行的操作已超出有效范围，例如查找或读取操作已超出文件末尾。与 `INVALID_ARGUMENT` 不同，此错误指示的问题可以通过改变系统状态得到修复。	在解决问题之前，请勿重试。
12	`UNIMPLEMENTED`	该操作未实现或 Cloud Healthcare API 不支持/未启用。	请勿重试。
13	`INTERNAL`	内部错误。这表示在底层系统中处理时遇到意外错误。	请使用指数退避算法重试。
14	`UNAVAILABLE`	Cloud Healthcare API 当前不可用。这很可能是一种暂时情况，可以通过退避重试来纠正。请注意，重试执行非幂等操作并非总是安全的。	请使用指数退避算法重试。
15	`DATA_LOSS`	数据丢失或损坏且不可恢复。	请与您的系统管理员联系。如果数据丢失或损坏，系统管理员可能需要联系支持代表。
16	`UNAUTHENTICATED`	请求没有相应操作的有效身份验证凭据。	在解决问题之前，请勿重试。