長期執行作業的最佳做法

本頁說明在 Cloud Healthcare API 中執行及管理長時間執行作業 (LROs) 的最佳做法。如要瞭解 Cloud Healthcare API 中的 LRO，請參閱「管理長時間執行的作業」。

LRO 屬性

以下各節適用於「傳回 LRO 的方法」一節中列出的方法。

配額影響

LRO 不會與 Cloud Healthcare API 建立、讀取、更新和刪除 (CRUD) 方法共用配額，這些方法會使用下列類型的配額：

• fhir_read_ops
• fhir_write_ops
• fhir_search_ops
• fhir_store_ops
• dicom_web_ops
• dicom_ops

系統會使用 fhir_store_lro_ops 和 dicom_store_lro_ops 指標計算 LRO 配額。

Cloud Healthcare API 會限制在 Google Cloud 專案中同時執行的 LRO 數量。詳情請參閱「限制 LRO 數量」。

資料處理量

與等效的 CRUD 方法相比，LRO 方法通常可達到更高的資料傳輸量。舉例來說，使用 dicomStores.import 匯入 DICOM 例項通常比使用 dicomStores.storeInstances 個別儲存例項更有效率。

由於存在下列限制，因此同時執行多個 LRO 可能不會增加資料總處理量，尤其是在處理大量資料時：

• 配額限制
• 資源爭用
• 在 LRO 執行期間， Google Cloud 專案傳送至 Cloud Healthcare API 的其他流量

如要提高 LRO 執行時的資料處理量，請考慮以下事項：

• 由於額外負擔，小型匯入和匯出批次的處理量通常較低。
• LRO 的執行和配額消耗量與其他 Cloud Healthcare API 作業分開計算。
• 每個 LRO 都有處理量上限。
• 同一個資源上的並行 LRO 可能會導致鎖定爭用情形。
• Cloud Healthcare API 會限制在 Google Cloud 專案中同時執行的 LRO 數量。詳情請參閱「限制 LRO 數量」。

請根據用途需求規劃 LRO 數量。如果您必須在多個 LRO 中分割大量資料批次，請盡量減少分割數量。

FHIR 參考完整性

fhirStores.import 方法不會考量 disableReferentialIntegrity 設定。這樣一來，您就能匯入具有任意關聯性的資料，而不需要排序或分組，藉此提高資料傳輸量。如果輸入資料含有無效參照，或部分 FHIR 資源無法匯入，FHIR 儲存庫的狀態可能會違反參照完整性。

如要使用 fhirStores.import，用戶端應用程式需要驗證下列項目，確保 FHIR 資源參照有效：

• FHIR 資源資料和格式正確
• 管理匯入期間發生的任何錯誤

如要強制執行參照完整性，請使用 fhir.create 或 fhir.executeBundle，而非 fhirStores.import。詳情請參閱「匯入 FHIR 資料與執行套件」。

Pub/Sub 通知

部分 Cloud Healthcare API 方法會傳送臨床事件的 Pub/Sub 通知，例如建立或刪除醫療資源。如要瞭解傳送 Pub/Sub 通知的方法清單，請參閱「設定 Pub/Sub 通知」。

下列匯入方法不會傳送 Pub/Sub 通知：

• dicomStores.import
• fhirStores.import

如果應用程式的部分內容需要在匯入作業完成時發出通知，請使用其他可列出匯入資料的通知方法。

錯誤處理限制

Cloud Healthcare API 可能不會在 LRO 中記錄所有錯誤，尤其是當 LRO 處理大量資料並產生許多錯誤時。實作一種方法，可分別追蹤 LRO 處理作業和錯誤。詳情請參閱「資源錯誤處理」。

資料和搜尋索引

由於搜尋索引非同步，搜尋結果可能會延遲。如果 LRO 建立或更新 FHIR 資源，可能需要額外時間才能在搜尋結果中顯示變更。

舉例來說，在 FHIR 儲存庫中搜尋 Patient 資源時，可能不會在 FHIR 匯入作業後立即傳回所有結果。

執行順序

LRO 會根據 Google Cloud 資源可用性排程。LRO 的執行和完成順序可能與要求的順序不符。

避免提出小型匯入和匯出要求

本節將說明處理小型資料量時的 LRO 限制。

從匯入和匯出作業傳回的 LRO 可快速處理大量資料並避免負載尖峰，進而擴大資料傳輸量。如要儲存少量資料，請使用「儲存資料的最佳做法」一節中的其他技巧。

LRO 數量限制

Cloud Healthcare API 會限制在 Google Cloud 專案中同時執行的 LRO 數量。限制取決於下列因素：

• LRO 類型。
• 分配給 LRO 的 Google Cloud 資源數量。這取決於輸入資料的大小。

如果執行的 LRO 過多，Cloud Healthcare API 的頻率限制會產生錯誤，並可能降低 LRO 的傳輸量。Cloud Healthcare API 會自動節省 Google Cloud 資源，讓 LRO 數量維持在資源限制範圍內。

LRO 是背景程序，因此如果 LRO 的負載會干擾優先順序較高的程序 (例如 CRUD 作業)，Cloud Healthcare API 可能會降低 LRO 的傳輸量。這樣一來，系統就能確保優先順序較高的程序可供使用。

資源分配和清除額外負擔

LRO 開始時，Cloud Healthcare API 會分配資源。這可能需要幾分鐘的時間，因為 Cloud Healthcare API 必須執行以下操作：

1. 啟動控制器程序。
2. 從工作站集區中分配工作站。
3. 判斷輸入資料的大小。
4. 開始大規模分配工作。

停止及清理 LRO 也可能需要幾分鐘的時間。

由於有額外負擔，處理少量資料的 LRO 可能會將大部分時間用於分配 worker 集區和清理資源。

如果您有許多這類 LRO，可能會遇到較低的資料傳輸量，因為您更有可能達到 Google Cloud專案配額限制。

要求 LRO 配額的限制

在申請更多 LRO 配額之前，請實施配額管理最佳做法。如果您仍需要更多配額，請與Google Cloud 客戶服務團隊聯絡。如要提出要求，請參閱申請額外配額的最佳做法。

如果輸入資料量大，您可能需要額外配額，例如：

• 您匯入的 DICOM 例項大小為數 PB。
• 您要匯入數十億個 FHIR 資源。

LRO 狀態和失敗狀態

啟動 LRO 時，回應會包含專屬 ID。您可以透過輪詢 LRO ID 來查看 LRO 狀態。LRO 完成後，會顯示下列其中一種狀態：

• 已順利完成，未發生錯誤
• 已順利完成，但發生部分錯誤
• 無法完成，但可能在失敗前產生部分輸出內容

以下 JSON 範例說明 LRO 完成時傳回的回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "METADATA_TYPE",
    "apiMethodName": "API_METHOD_NAME",
    "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": 
    
  },
  // 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 和取消 LRO，請參閱「管理長時間執行作業」。

管理 LRO 狀態和失敗狀態

如要管理 LRO 狀態和失敗狀態，請遵循下列最佳做法：

• 輪詢 LRO 以取得狀態，並確認 LRO 何時完成。如要輪詢 LRO，請重複呼叫 projects.locations.datasets.operations.get 方法，直到作業完成為止。請在每次輪詢要求之間使用輪詢，例如每 10 秒就進行輪詢。回應中包含 "done": true 時，表示 LRO 已完成。

• LRO 完成後，請檢查回應中是否包含 error 欄位。如果發生這種情況，請根據下列事項決定是否要重試作業：

  • 錯誤代碼。如需錯誤代碼和建議的處理方式，請參閱「排解 LRO 問題」。
  • 已發生的重試次數。
  • LRO 開始到發生錯誤之間的時間。舉例來說，如果 LRO 通常需要幾小時，但卻花了幾天時間，且未傳回失敗狀態，您可能需要人工介入。如要進一步瞭解何時可能需要人工介入，請參閱「規劃最終錯誤狀態」一文。

  如要瞭解如何重試 LRO，請參閱「排入 LRO 佇列」一文。

• 如果您不重試 LRO，請查看 metadata.counter.failure 欄位，瞭解特定資源是否發生錯誤。您可能可以個別處理這些資源。詳情請參閱「處理資源錯誤」。

處理資源錯誤

LRO 可能會在發生錯誤的情況下完成。LRO 回應中的錯誤會遵循 Google Cloud 錯誤模型。LRO 回應會提供 Cloud Logging 的連結，方便您進一步瞭解相關資訊。

LRO 錯誤詳細資料

Cloud Logging 中的 LRO 錯誤具有以下屬性：

• Cloud Logging 錯誤記錄檔中沒有 LRO ID。使用 operation.id 和 operation.producer 欄位找出 LRO 的狀態和錯誤。舉例來說，從 projects.locations.datasets.fhirStores.import 方法叫用的 LRO 會在 operation.producer 欄位中包含 import_fhir。

  如果有多個 LRO 具有相同的 operation.id 和 operation.producer，請使用 createTime 和 endTime 時間戳記來找出正確的 LRO。

• Cloud Logging 中並未提供所有 LRO 錯誤。metadata.counter.failure 欄位的值可能會超過實際記錄的錯誤數量，原因如下：

  • Cloud Logging 配額限制
  • Cloud Logging 服務可用性
  • LRO 記錄限制

  舉例來說，如果 LRO 匯入 1 千萬個 FHIR 資源，其中 50% 有格式錯誤，則可能只會記錄幾百或幾千個錯誤，因為有速率限制和 Cloud Logging 配額。

  記錄的錯誤數量也會因 LRO 在發生高錯誤率時執行的時間長短而異。如果 LRO 執行速度緩慢，Cloud Logging 可能會顯示更多錯誤，因為這些錯誤會在長時間內分散，且不受速率限制的影響。

重試 LRO 的影響

如果 LRO 遇到錯誤，而用戶端應用程式自動使用相同資料重試該作業，重試可能會導致更多錯誤。

請考慮以下情況：fhirStores.import LRO 因嘗試匯入的部分 FHIR 資源無效，而以錯誤結束。自動重試使用相同資料的匯入作業，可能會產生許多 409 ALREADY_EXISTS 錯誤，因為部分 FHIR 資源已在原始作業中匯入。如果您查詢 LRO 並發現建立作業失敗，請勿自動重試。409 ALREADY_EXISTS 錯誤應由人工審查。

如果重試成功，metadata.counter.failure 欄位就不會包含先前作業的錯誤。這可能會導致錯誤計數不正確，因為重試成功的回應不會包含先前嘗試的錯誤。

重試 LRO

如果您有用來偵測 LRO 錯誤的用戶端處理管道，請勿使用 Cloud Logging。如LRO 錯誤詳細資料所示，LRO 的 Cloud Logging 錯誤記錄不可靠且不完整。請改用下列各節中的技巧。

重試匯入作業

如要偵測匯入失敗的資料，請比較 Cloud Healthcare API 中匯入的資料，與 Cloud Storage 中的來源資料。您可以使用下列方法匯入資料：

• projects.locations.datasets.fhirStores.import
• projects.locations.datasets.dicomStores.import
• projects.locations.datasets.hl7V2Stores.import

使用專屬 ID (例如 FHIR 病患資源的醫療記錄編號 (MRN)) 比較資料。

如要瞭解重試 LRO 的影響，請參閱「重試 LRO 的影響」一文，瞭解重試匯入作業時應採取的步驟。

重新執行匯入作業可能會重新建立先前刪除的資源。請考慮下列情境：

1. 您嘗試匯入 1,000,000 個 FHIR 資源。50,000 個資源因格式設定錯誤而失敗。
2. 您花了好幾天時間修正格式錯誤。在此期間，患者要求您移除其病歷。
3. 如果重新執行匯入作業，可能會重新建立您刪除的病患資料。

重試匯出作業

如要偵測無法匯出至 BigQuery 的資料，請編寫指令碼，比較來源資料中的唯一 ID 與匯出的資料。

您可以使用下列方法將資料匯出至 BigQuery：

• projects.locations.datasets.fhirStores.export
• projects.locations.datasets.dicomStores.export
• projects.locations.datasets.hl7V2Stores.export

排入並管理 LRO

如果您執行的 LRO 會處理大量資料，用於新手上路或定期執行，請實作以下 LRO 排隊技巧：

• 將並行 LRO 限制在 5 等小數字內。您可以根據執行的 LROs 大小和類型調整這項限制。
• 監控 LRO 完成情形。如果發生錯誤，請重新排定 LRO 或在處理管道中個別解決錯誤。

• 盡可能自動解決處理資源錯誤中的錯誤。

  • 瞭解 FHIR 匯入用途，以便決定要忽略 409 ALREADY_EXISTS 錯誤，還是要執行個別的 CRUD 作業來解決錯誤。如LRO 錯誤詳細資料所示，部分 409 ALREADY_EXISTS 錯誤可能不會記錄至 Cloud Logging。如果應用程式需要錯誤記錄，請使用「重試 LRO」一文中的任一技巧。

  • 如要解決少數錯誤，請為遇到錯誤的資料排入較小的 LRO，或執行個別的 CRUD 作業。

  • 如要解決許多錯誤，重新執行 LRO 可能是確保一致性的最簡單選項。如要瞭解針對已刪除的資料重新執行匯入作業的風險，請參閱「重試匯入作業」。

• 自動偵測是否需要人為介入才能解決錯誤。您應該為系統管理員準備工具和作業手冊。處理錯誤的任務可能包括：

  • 重新排定長時間執行作業。
  • 重新排程先前 LRO 中的部分資料。
  • 檢查錯誤，並解決遇到錯誤的個別資料元素。只有在您確定 LRO 中的所有錯誤都已記錄時，才能執行此項工作。

• 決定 LRO 時間表。您可以排定 LRO，避免在許多 CRUD 作業執行時，在尖峰時段執行。詳情請參閱「管理配額，盡量提高資料傳輸量」。

監控及接收快訊

建立並維護監控 LRO 和解決快訊的程序。警報主要是由 LRO 狀態和佇列問題造成。程序應處理下列情況：

• LRO 重試次數超過設定值。
• 需要人為介入才能解決部分錯誤的問題。舉例來說，如果 LRO 失敗，且用戶端無法解決錯誤，可能就需要人工介入。如要進一步瞭解如何解決需要人為介入的問題，請參閱「佇列和管理 LRO」一文。
• 佇列長度超出限制或增長速度過快。
• 不符合政策規定，例如權限問題或設定錯誤。
• 一致性檢查，顯示多個 LRO 中的系統性問題。您可能會有多個去識別化 LRO，這些 LRO 會預期來源資料集和目的地資料集的 FHIR 資源數量相同。如果差異隨著時間增加，可能表示有未處理的資料。
• LRO 配額問題。詳情請參閱「管理配額以盡量提高資料傳輸量」和「配額管理最佳做法」。