本頁面由 Cloud Translation API 翻譯而成。

管理長時間執行的作業

本頁說明如何管理 Cloud Healthcare API 長時間執行作業 (LRO) 的生命週期。

如果 API 方法可能需要很長時間才能完成，可以向用戶端傳回 Operation。用戶端可以透過輪詢作業，使用 Operation 介面非同步擷取 API 方法的狀態。Cloud Healthcare API 中的 LRO 遵循 Google Cloud LRO 設計模式。

Cloud Healthcare API 會為多種方法建立 LRO，例如 projects.locations.datasets.fhirStores.import。呼叫 projects.locations.datasets.fhirStores.import 時，Cloud Healthcare API 會建立 LRO 來追蹤匯入狀態。LRO 具有專屬 ID，可用於查看 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。

LRO 記錄會在 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 控制台中，前往「Datasets」(資料集) 頁面。

前往「資料集」頁面
按一下要查看 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 已建立 LRO，並提供作業 ID。您也可以列出長時間執行的資料庫作業，以擷取作業 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

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$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

APIs Explorer

開啟方法參考頁面。系統會在頁面右側開啟 APIs 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 控制台中，前往「Datasets」(資料集) 頁面。

前往「資料集」頁面
按一下要查看 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

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$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

APIs Explorer

開啟方法參考頁面。系統會在頁面右側開啟 APIs 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 控制台中，前往「Datasets」(資料集) 頁面。

前往「資料集」頁面
按一下要查看 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

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$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

APIs Explorer

開啟方法參考頁面。系統會在頁面右側開啟 APIs 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

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$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

APIs Explorer

開啟方法參考頁面。系統會在頁面右側開啟 APIs 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`	要求中不含作業的有效驗證憑證。	未修正問題前請勿重試。

管理長時間執行的作業 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

傳回 LRO 的方法

取得 LRO 的詳細資料

控制台

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

回應

REST

curl

PowerShell

APIs Explorer

回應

列出 LRO

控制台

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

回應

REST

curl

PowerShell

APIs Explorer

回應

取消 LRO

控制台

REST

curl

PowerShell

APIs Explorer

回應

curl

PowerShell

APIs Explorer

回應

取消多個 LRO

排解 LRO 問題

管理長時間執行的作業