本頁面由 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 的要求，藉此查看 LRO 的狀態，這項要求會傳送至發生匯入作業的 FHIR 儲存庫的父項資料集。

除了 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 或會傳回 LRO 的 API 呼叫方法後，您可以在 Google Cloud 主控台中查看 LRO 的詳細資料。

在 Google Cloud 控制台中，前往「Datasets」(資料集) 頁面。

前往「資料集」
按一下包含要查看的 LRO 資料集名稱。
按一下「操作」。
如要在 Cloud Logging 中查看作業的錯誤記錄檔，請按一下「Actions」，然後點選「View details in 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 CLI，方法是執行 gcloud init 或 gcloud auth login，或是使用 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

開啟方法參考頁面。系統會在頁面右側開啟 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 控制台中，前往「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

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

前往「資料集」
按一下包含要查看的 LRO 資料集名稱。
按一下「操作」。
在要取消的 LRO 所在的資料列中，開啟「Actions」清單，然後按一下「Stop Operation」。

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

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

注意：下列指令假設您已透過執行 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

開啟方法參考頁面。系統會在頁面右側開啟 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` 表示引數有問題，無論系統狀態為何，一律使用 `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 問題

管理長時間執行的作業