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

使用時間點復原 (PITR) 復原 HL7v2 訊息

本頁說明如何使用時間點復原 (PITR) 功能，將 HL7v2 儲存庫中的 HL7v2 訊息復原至過去 21 天內某個時間點的狀態。您可以透過 PITR 從非預期的變更中復原，例如誤刪 HL7v2 訊息。

事前準備

PITR 要求會歸類為進階作業要求，並據此計費。使用 PITR 前，請先查看進階作業要求的定價。

復原工作流程

為確保正式版復原作業能順利執行，請先進行模擬測試。模擬執行會輸出一或多個檔案，其中包含要復原的 HL7v2 訊息 ID。請先確認輸出檔案是否正確，再於正式環境中再次執行復原作業。

如要復原特定 HL7v2 訊息，或根據篩選條件復原 HL7v2 訊息，請指定篩選器。

執行模擬測試

這項工作需要的權限

如要執行這項工作，您必須擁有以下權限或以下 Identity and Access Management (IAM) 角色：

權限

healthcare.hl7V2Stores.rollback

角色

Healthcare HL7v2 Store 管理員 (roles/healthcare.hl7V2StoreAdmin)

您可以要求管理員授予這些 Identity and Access Management 角色。如需授予角色的操作說明，請參閱「管理存取權」或「控管 Cloud Healthcare API 資源的存取權」。您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

注意：如果您為本指南建立 Google Cloud 專案，系統會自動授予您專案建立者「擁有者」IAM 角色 (roles/owner)，該角色具備相關權限。您不需要獲得任何其他 IAM 角色。

在正式環境中還原 HL7v2 訊息前，請先執行模擬測試。

下列範例說明如何使用 hl7V2Stores.rollback 方法進行試執行。

REST

復原 HL7v2 訊息。

如要執行模擬測試，請確認 force 欄位為 false。

使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的 Google Cloud 專案 ID
- LOCATION：資料集位置
- DATASET_ID：HL7v2 存放區的父項資料集
- HL7V2_STORE_ID：HL7v2 儲存庫 ID
- RECOVERY_TIMESTAMP：過去 21 天內的復原點。請使用 RFC 3339 格式。指定時間 (精確到秒) 並加入時區，例如 2015-02-07T13:28:17.239+02:00 或 2017-01-01T00:00:00Z。
- CLOUD_STORAGE_BUCKET：輸出檔案寫入的 Cloud Storage 資料夾或 bucket 完整 URI
如要傳送要求，請選擇以下其中一個選項：
curl

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

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：
```
cat > request.json << 'EOF'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}
EOF
```
接著，請執行下列指令來傳送 REST 要求：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:rollback"
PowerShell

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

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：
```
@'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}
'@  | Out-File -FilePath request.json -Encoding utf8
```
接著，請執行下列指令來傳送 REST 要求：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:rollback" | Select-Object -Expand Content
APIs Explorer

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求內文貼到這項工具中，並填妥其他必填欄位，然後按一下「Execute」(執行)。
輸出內容如下所示。回應會包含長時間執行作業 (LRO) 的 ID。如果方法呼叫可能需要額外時間才能完成，系統會傳回長時間執行的作業。請記下 OPERATION_ID 的值。您會在下一個步驟中用到這個值。
回應
```
{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}
```

使用 projects.locations.datasets.operations.get 方法取得長時間執行的作業狀態。

使用任何要求資料之前，請先替換以下項目：

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.hl7v2.Hl7V2Service.RollbackHl7V2Messages",
    "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",
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.hl7v2.RollbackHl7V2MessagesResponse",
    "hl7V2Store": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID"
  }
}

查看模擬測試輸出檔案

每次試運都會輸出一個或多個檔案，內含要復原的 HL7v2 訊息 ID 和類型。檔案會建立在目標 Cloud Storage bucket 的 rollback_messages 資料夾中。子資料夾名稱是 hl7V2Stores.rollback 回應中傳回的 LRO ID。如要查看檔案並確保復原作業正常運作，請參閱「查看物件中繼資料」。

檔案數量與復原的 HL7v2 訊息數量成正比。

檔案名稱採用 trial-NUMBER-of-TOTAL_NUMBER.txt 格式，其中 NUMBER 是檔案編號，TOTAL_NUMBER 是檔案總數。

模擬測試輸出檔案結構定義

模擬復原作業的輸出檔案會使用下表所示的結構定義：

`MESSAGE_ID`	`TIMESTAMP`
HL7v2 訊息 ID。	HL7v2 訊息在 HL7v2 儲存庫中建立或更新的時間。

在正式環境中復原

這項工作需要的權限

如要執行這項工作，您必須擁有以下權限或以下 Identity and Access Management (IAM) 角色：

權限

healthcare.hl7V2Stores.rollback

角色

Healthcare HL7v2 Store 管理員 (roles/healthcare.hl7V2StoreAdmin)

如要將正式版輸出檔案寫入 Cloud Storage，您必須授予 Cloud Healthcare 服務代理程式服務帳戶權限。如需操作說明，請參閱「將輸出檔案寫入 Cloud Storage」。

在正式環境中復原之前，請先進行試運轉，並檢查試運轉輸出檔案，確保正式環境復原作業能如預期執行。

下列範例說明如何使用 hl7V2Stores.rollback 方法，在正式環境中還原 HL7v2 訊息。

REST

復原 HL7v2 訊息。

確認 force 欄位為 true。

使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的 Google Cloud 專案 ID
- LOCATION：資料集位置
- DATASET_ID：HL7v2 存放區的父項資料集
- HL7V2_STORE_ID：HL7v2 儲存庫 ID
- RECOVERY_TIMESTAMP：過去 21 天內的復原點。請使用 RFC 3339 格式。指定時間 (精確到秒) 並加入時區，例如 2015-02-07T13:28:17.239+02:00 或 2017-01-01T00:00:00Z。
- CLOUD_STORAGE_BUCKET：輸出檔案寫入的 Cloud Storage 資料夾或 bucket 完整 URI
如要傳送要求，請選擇以下其中一個選項：
curl

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

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：
```
cat > request.json << 'EOF'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}
EOF
```
接著，請執行下列指令來傳送 REST 要求：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:rollback"
PowerShell

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

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：
```
@'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}
'@  | Out-File -FilePath request.json -Encoding utf8
```
接著，請執行下列指令來傳送 REST 要求：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:rollback" | Select-Object -Expand Content
APIs Explorer

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求內文貼到這項工具中，並填妥其他必填欄位，然後按一下「Execute」(執行)。
輸出內容如下所示。回應會包含長時間執行作業 (LRO) 的 ID。如果方法呼叫可能需要額外時間才能完成，系統會傳回長時間執行的作業。請記下 OPERATION_ID 的值。您會在下一個步驟中用到這個值。
回應
```
{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}
```

使用 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 面板。您可以使用這項工具來傳送要求。完成任何必填欄位，然後按一下「執行」。

輸出內容如下所示。如果回應包含 "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.hl7v2.Hl7V2Service.RollbackHl7V2Messages",
    "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",
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.hl7v2.RollbackHl7V2MessagesResponse",
    "hl7V2Store": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID"
  }
}

查看正式版復原輸出檔案

實際工作環境復原作業會輸出下列檔案。檔案會建立在目標 Cloud Storage 值區的 rollback_messages 資料夾中。子資料夾名稱是 hl7V2Stores.rollback 回應中傳回的 LRO ID。如要查看檔案，請參閱「查看物件中繼資料」一文。

success-NUMBER-of-TOTAL_NUMBER.txt：包含成功復原的 HL7v2 訊息。
fail-NUMBER-of-TOTAL_NUMBER.txt：包含無法復原的 HL7v2 訊息。即使沒有任何失敗，系統仍會產生空白檔案。

在檔案名稱中，NUMBER 是檔案編號，TOTAL_NUMBER 則是檔案總數。

製作輸出檔案結構定義

實際工作環境復原作業的成功和失敗檔案會使用下列結構。錯誤檔案包含額外的「ERROR_MESSAGE」資料欄。

`MESSAGE_ID`	`ERROR_MESSAGE` (僅限錯誤檔案)
HL7v2 訊息 ID。	僅限錯誤檔案。說明 HL7v2 訊息無法復原的原因。

使用篩選器將 HL7v2 儲存庫還原至先前的狀態

如果 HL7v2 儲存庫曾由一或多個長時間執行的作業 (LRO) 修改，您可以在篩選器中指定 LRO ID，將 HL7v2 儲存庫還原至先前的狀態。舉例來說，您可以將 HL7v2 儲存庫還原至先前的狀態，也就是匯入作業匯入 HL7v2 訊息前的狀態。

傳送 hl7V2Stores.rollback 要求時，請在 RollbackHL7MessagesFilteringFields 物件中指定 LRO ID。

如要瞭解如何在 Cloud Healthcare API 資料集中列出及查看 LRO ID，請參閱列出 LRO。

使用時間點復原 (PITR) 復原 HL7v2 訊息 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

復原工作流程

執行模擬測試

這項工作需要的權限

REST

curl

PowerShell

APIs Explorer

回應

curl

PowerShell

APIs Explorer

回應

查看模擬測試輸出檔案

模擬測試輸出檔案結構定義

在正式環境中復原

這項工作需要的權限

REST

curl

PowerShell

APIs Explorer

回應

curl

PowerShell

APIs Explorer

回應

查看正式版復原輸出檔案

製作輸出檔案結構定義

使用篩選器將 HL7v2 儲存庫還原至先前的狀態

使用時間點復原 (PITR) 復原 HL7v2 訊息