將 HL7v2 訊息匯出至 Cloud Storage

本頁說明如何將 HL7v2 訊息從 HL7v2 儲存庫匯出至 Cloud Storage。 您可以將大量 HL7v2 訊息匯出至 Cloud Storage，以進行下游處理。

事前準備

如要瞭解必須授予 Cloud Healthcare Service Agent 服務帳戶的角色，請參閱「從 Cloud Storage 匯出 HL7v2 訊息」。

將 HL7v2 訊息匯出至 Cloud Storage

這項工作需要的權限

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

權限

• 要求 HL7v2 儲存庫上的 healthcare.hl7V2Stores.export

角色

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

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

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

Cloud Healthcare API 會將每則 HL7v2 訊息匯出為 NDJSON .ndjson 檔案中的一行。HL7v2 訊息會依 sendTime 值按時間順序排序。

匯出至 Cloud Storage 值區或資料夾，而非物件，因為如果 HL7v2 訊息數量眾多，Cloud Healthcare API 可能會建立多個 NDJSON 檔案。

如果匯出至不存在的 Cloud Storage 資料夾，系統會建立該資料夾。

控制台

如要將 HL7v2 訊息匯出至 Cloud Storage，請完成下列步驟：

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

   前往「資料集」頁面

2. 按一下包含 HL7v2 儲存庫的資料集，從中匯出 HL7v2 訊息。

3. 在資料儲存庫清單中，從 HL7v2 儲存庫的「動作」清單中選擇「匯出」。

   「Export HL7v2 messages」(匯出 HL7v2 訊息) 頁面隨即顯示。

4. 在「Project」(專案) 清單中，選取 Cloud Storage 專案。

5. 在「Location」(位置) 清單中，選取 Cloud Storage bucket。

6. 按一下「匯出」，將 HL7v2 執行個體匯出至 Cloud Storage 中定義的位置。

7. 如要追蹤作業狀態，請按一下「Operations」(作業) 分頁標籤。作業完成後，會顯示下列指標：
   • 「長時間執行的作業狀態」部分在「OK」標題下方顯示綠色勾號。
   • 「總覽」部分會顯示綠色勾號和「OK」指標，與作業 ID 位於同一列。
   如果發生任何錯誤，請按一下「動作」，然後點選「在 Cloud Logging 中查看詳細資料」。

使用篩選器將 HL7v2 訊息匯出至 Cloud Storage

根據預設，將 HL7v2 訊息匯出至 Cloud Storage 時，系統會匯出 HL7v2 儲存庫中的所有 HL7v2 訊息，以及每個 Message 物件中的所有欄位。

您可以透過下列方式篩選匯出的 HL7v2 訊息：

• 使用篩選器匯出符合篩選條件的部分 HL7v2 訊息。詳情請參閱「使用篩選器匯出部分 HL7v2 訊息」。
• 使用 MessageView 物件選取要匯出的每個 Message 中的欄位。詳情請參閱「依 Message 欄位匯出 HL7v2 訊息」。

使用篩選器匯出部分 HL7v2 訊息

您可以在篩選條件中使用下列欄位：

• startTime
• endTime。

您可以在 filter 欄位中，將下列篩選器參數指定為篩選條件。如要瞭解篩選器語法及建構查詢，請參閱查詢字串。

• message_type：來自 MSH.9.1 欄位。例如：NOT message_type = "ADT"。
• send_date：訊息從 MSH.7 區段傳送的 YYYY-MM-DD 日期，以資料集的時區指定。例如：send_date < "2017-01-02"。
• send_time：傳送訊息時的時間戳記。這個參數來自訊息的 MSH.7 區段。這個參數會使用 RFC 3339 時間格式進行比較。例如：send_time < "2017-01-02T00:00:00-05:00"。
• create_time：訊息在 Cloud Healthcare API 中建立的時間戳記，使用 RFC 3339 時間格式進行比較。 例如：create_time < "2017-01-02T00:00:00-05:00"。
• send_facility：訊息的來源照護中心 (來自 MSH.4 區段)。例如：send_facility = "ABC"。

注意： 使用 startTime 和 endTime 篩選比使用 send_time 指定篩選器更有效率。使用 startTime 和 endTime 欄位建立的篩選器，會定義篩選器套用的 HL7v2 訊息範圍。send_time 篩選器只會套用至傳送時間完全相符的 HL7v2 訊息。

下列範例說明如何指定篩選條件，只匯出 ADT 類型的 HL7v2 訊息。

REST

1. 使用 hl7V2Stores.export 方法匯出 HL7v2 訊息：

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

   • PROJECT_ID：您的 Google Cloud 專案 ID
   • LOCATION：資料集位置
   • DATASET_ID：HL7v2 存放區的父項資料集
   • HL7V2_STORE_ID：HL7v2 儲存庫 ID
   • CLOUD_STORAGE_LOCATION：Cloud Storage bucket 或資料夾的名稱，匯出的 HL7v2 訊息會寫入其中

   JSON 要求主體：

   {
     "gcsDestination": {
       "uriPrefix": "gs://CLOUD_STORAGE_LOCATION"
     },
     "filter": "message_type = \"ADT\""
   }
   

   如要傳送要求，請選擇以下其中一個選項：

   curl

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

   將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

   cat > request.json << 'EOF'
   {
     "gcsDestination": {
       "uriPrefix": "gs://CLOUD_STORAGE_LOCATION"
     },
     "filter": "message_type = \"ADT\""
   }
   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:export"

   PowerShell

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

   將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

   @'
   {
     "gcsDestination": {
       "uriPrefix": "gs://CLOUD_STORAGE_LOCATION"
     },
     "filter": "message_type = \"ADT\""
   }
   '@  | 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:export" | Select-Object -Expand Content

   輸出內容如下所示。回應會包含長時間執行作業 (LRO) 的 ID。如果方法呼叫可能需要額外時間才能完成，系統會傳回長時間執行的作業。請記下 OPERATION_ID 的值。您會在下一個步驟中用到這個值。

   回應

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

2. 使用 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.ExportMessages",
       "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.hl7v2.ExportMessagesResponse",
       
     },
     // 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: ...,
           ...
         }
       ]
     }
   }
   

依 Message 欄位匯出 HL7v2 訊息

在 Cloud Healthcare API 中，HL7v2 訊息會儲存在 Message 資源中。您可以使用 MessageView 列舉，判斷每個匯出的 HL7v2 訊息中包含 Message 資源的哪些欄位。

下列範例說明如何在 MessageView 中使用 BASIC 值，只在匯出的 HL7v2 訊息中加入 name 欄位。

REST

1. 使用 hl7V2Stores.export 方法匯出 HL7v2 訊息：

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

   • PROJECT_ID：您的 Google Cloud 專案 ID
   • LOCATION：資料集位置
   • DATASET_ID：HL7v2 存放區的父項資料集
   • HL7V2_STORE_ID：HL7v2 儲存庫 ID
   • CLOUD_STORAGE_LOCATION：Cloud Storage bucket 或資料夾的名稱，匯出的 HL7v2 訊息會寫入其中

   JSON 要求主體：

   {
     "gcsDestination": {
       "uriPrefix": "gs://CLOUD_STORAGE_LOCATION",
       "messageView": "BASIC"
     }
   }
   

   如要傳送要求，請選擇以下其中一個選項：

   curl

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

   將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

   cat > request.json << 'EOF'
   {
     "gcsDestination": {
       "uriPrefix": "gs://CLOUD_STORAGE_LOCATION",
       "messageView": "BASIC"
     }
   }
   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:export"

   PowerShell

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

   將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

   @'
   {
     "gcsDestination": {
       "uriPrefix": "gs://CLOUD_STORAGE_LOCATION",
       "messageView": "BASIC"
     }
   }
   '@  | 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:export" | Select-Object -Expand Content

   輸出內容如下所示。回應會包含長時間執行作業 (LRO) 的 ID。如果方法呼叫可能需要額外時間才能完成，系統會傳回長時間執行的作業。請記下 OPERATION_ID 的值。您會在下一個步驟中用到這個值。

   回應

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

2. 使用 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.ExportMessages",
       "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.hl7v2.ExportMessagesResponse",
       
     },
     // 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: ...,
           ...
         }
       ]
     }
   }
   

排解 HL7v2 匯出要求問題

如果匯出 HL7v2 訊息時發生錯誤，系統會將錯誤記錄至 Cloud Logging。詳情請參閱「查看 Cloud Logging 中的錯誤記錄檔」。

如果長期執行的作業傳回錯誤，請參閱排解長期執行的作業問題。