Cloud Storage を使用した HL7v2 メッセージのインポートとエクスポート

このページでは、projects.locations.datasets.hl7V2Stores.import メソッドと projects.locations.datasets.hl7V2Stores.export メソッドを使用して、Cloud Storage との間で HL7v2 メッセージをエクスポートおよびインポートする方法について説明します。

Cloud Storage から HL7v2 メッセージをインポートすると、多くの HL7v2 メッセージを HL7v2 ストアに簡単に一括で読み込むことができます。また、多くの HL7v2 メッセージを一度に Cloud Storage にエクスポートできるため、Cloud Storage に個別に保存する必要がなくなります。

Cloud Storage 権限を設定する

Cloud Storage との間で HL7v2 メッセージをエクスポートおよびインポートする前に、Cloud Healthcare Service Agent のサービス アカウントに追加の権限を付与する必要があります。詳細については、HL7v2 ストアの Cloud Storage 権限をご覧ください。

HL7v2 メッセージのインポート

HL7v2 メッセージをインポートするには、まず、1 つ以上のメッセージを含む Cloud Storage に、改行区切りの JSON（.ndjson）ファイルを 1 つ以上作成する必要があります。このファイルの各行は、base64 でエンコードされた HL7v2 メッセージを含む単一の Message リソースです。Message リソースには、任意のラベルを含めることもできます。

たとえば、次のファイル（messages.ndjson という名前）には、2 つの HL7v2 メッセージが含まれています。2 番目のメッセージでラベルが定義されています。

{"data" :"TVNIfF5+XCZ8QXxTRU5EX0ZBQ0lMSVRZXzF8QXxBfDIwMTgwMTAxMDAwMDAwfHxUWVBFXkF8MjAxODAxMDEwMDAwMDB8VHwwLjB8fHxBQXx8MDB8QVNDSUkNRVZOfEEwMHwyMDE4MDEwMTA0MDAwMA1QSUR8fDE0ATExMV5eXl5NUk58MTExMTExMTFeXl5eTVJOfjExMTExMTExMTFeXl5eT1JHTk1CUg=="}
{"data" :"TVNIfF5+XCZ8QXxTRU5EX0ZBQ0lMSVRZXzJ8QXxBfDIwMTgwMTAxMDAwMDAwfHxUWVBFXkF8MjAxODAxMDEwMDAwMDB8VHwwLjB8fHxBQXx8MDB8QVNDSUkNRVZOfEEwMHwyMDE4MDEwMTA0MDAwMA1QSUR8fDE0ATExMV5eXl5NUk58MTExMTExMTFeXl5eTVJOfjExMTExMTExMTFeXl5eT1JHTk1CUg==","labels":{"foo":"bar"}}

Console

Cloud Storage バケットから HL7v2 メッセージをインポートする手順は次のとおりです。

1. Google Cloud コンソールで、[データセット] ページに移動します。

   [データセット] に移動

2. HL7v2 メッセージのインポート先の HL7v2 ストアを含むデータセットをクリックします。

3. データストアのリストで、HL7v2 ストアの [アクション] リストから [インポート] を選択します。

   [HL7v2 ストアにインポート] ページが表示されます。

4. [プロジェクト] リストで、Cloud Storage プロジェクトを選択します。

5. [ロケーション] リストで、Cloud Storage バケットを選択します。

6. ファイルをインポートする特定の場所を設定するには、次のようにします。

   1. [詳細オプション] を展開します。
   2. [Cloud Storage のパスをオーバーライド] を選択します。

   3. ファイルをインポートする特定のソースを設定するには、[ロケーション] テキスト ボックスでパスを定義します。ワイルドカードを使用して、1 つ以上のディレクトリから複数のファイルをインポートできます。オブジェクトの命名の詳細については、オブジェクトの命名ガイドラインをご覧ください。

      次のワイルドカードがサポートされています。
      • * は、0 個以上の区切り文字でない文字に一致します。たとえば、gs://BUCKET/DIRECTORY/Example*.ndjson は DIRECTORY の Example.ndjson と Example22.ndjson に一致します。
      • ** は 0 個以上の文字（区切り文字を含む）と一致します。パスの末尾で使用する必要があり、パスには他のワイルドカードを使用しないでください。ファイル名の拡張子（.ndjson など）でも使用できます。この場合、指定したディレクトリとそのサブディレクトリに、このファイル名拡張子を持つすべてのファイルをインポートできます。 たとえば、gs://BUCKET/DIRECTORY/**.ndjson では .ndjson というファイル名拡張子を持つすべてのファイルを DIRECTORYとそのサブディレクトリにインポートします。
      • ? は 1 つの文字に一致します。たとえば、gs://BUCKET/DIRECTORY/Example?.ndjson は Example1.ndjson と一致しますが、Example.ndjson や Example01.ndjson とは一致しません。

7. 定義済みのソースから HL7v2 メッセージをインポートするには、[インポート] をクリックします。

8. オペレーションのステータスを追跡するには、[オペレーション] タブをクリックします。オペレーションが完了すると、次の状況が表示されます。
   • [長時間実行オペレーションのステータス] セクションでは、[OK] の見出しの下に、緑色のチェックマークが表示されます。
   • [概要] セクションでは、オペレーション ID と同じ行に緑色のチェックマークと [OK] インジケーターが表示されます。
   エラーが発生した場合は、[アクション] をクリックしてから、[Cloud Logging で詳細を表示] をクリックします。

API

次のサンプルでは、projects.locations.datasets.hl7V2Stores.import メソッドを使用して Cloud Storage から HL7v2 メッセージをインポートする方法を示しています。

インポート オペレーションを呼び出すときは、次の点に注意してください。

• バケット内のファイルの場所は任意であり、次のサンプルで指定されている形式を厳密に遵守する必要はありません。
• Cloud Storage 内の HL7v2 メッセージのロケーションを指定するときは、ワイルドカードを使用して 1 つ以上のディレクトリから複数のファイルをインポートできます。次のワイルドカードがサポートされています。
  • * は、0 個以上の区切り文字でない文字に一致します。たとえば、gs://BUCKET/DIRECTORY/Example*.ndjson は DIRECTORY の Example.ndjson と Example22.ndjson に一致します。
  • ** は 0 個以上の文字（区切り文字を含む）と一致します。パスの末尾で使用する必要があり、パスには他のワイルドカードを使用しないでください。ファイル名の拡張子（.ndjson など）でも使用できます。この場合、指定したディレクトリとそのサブディレクトリに、このファイル名拡張子を持つすべてのファイルをインポートできます。 たとえば、gs://BUCKET/DIRECTORY/**.ndjson では .ndjson というファイル名拡張子を持つすべてのファイルを DIRECTORYとそのサブディレクトリにインポートします。
  • ? は 1 つの文字に一致します。たとえば、gs://BUCKET/DIRECTORY/Example?.ndjson は Example1.ndjson と一致しますが、Example.ndjson や Example01.ndjson とは一致しません。

curl

HL7v2 メッセージを HL7v2 ストアにインポートするには、POST リクエストを行い、次の情報を指定します。

• 親データセットの名前
• HL7v2 ストアの名前。
• Cloud Storage バケット内のオブジェクトの場所。
• アクセス トークン

次のサンプルは、curl を使用した POST リクエストを使用して単一のファイルをインポートする方法を示しています。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'gcsSource': {
        'uri': 'gs://BUCKET/DIRECTORY/HL7V2_MESSAGE_FILE'
      }
    }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:import"

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

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

レスポンスにはオペレーション名が含まれています。オペレーションのステータスを追跡するには、オペレーションの get メソッドを使用します。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

リクエストが成功すると、サーバーはオペレーションのステータスを含む JSON 形式のレスポンスを返します。

{
  "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.ImportMessages",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.hl7v2.ImportMessagesResponse"
  }
}

PowerShell

HL7v2 メッセージを HL7v2 ストアにインポートするには、POST リクエストを行い、次の情報を指定します。

• 親データセットの名前
• HL7v2 ストアの名前。
• Cloud Storage バケット内のオブジェクトの場所。
• アクセス トークン

次のサンプルは、Windows PowerShell を用いた POST リクエストを使用して、単一のファイルをインポートする方法を示しています。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body "{
    'gcsSource': {
      'uri': 'gs://BUCKET/DIRECTORY/HL7V2_MESSAGE_FILE'
    }
  }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:import" | Select-Object -Expand Content

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

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

レスポンスにはオペレーション名が含まれています。オペレーションのステータスを追跡するには、オペレーションの get メソッドを使用します。

$cred = gcloud auth application-default 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

リクエストが成功すると、サーバーはオペレーションのステータスを含む JSON 形式のレスポンスを返します。

{
  "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.ImportMessages",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.hl7v2.ImportMessagesResponse"
  }
}

HL7v2 メッセージのエクスポート

HL7v2 ストアから HL7v2 メッセージをエクスポートすると、HL7v2 ストア内のすべてのメッセージがエクスポートされます。これらのメッセージのうちあるサブセットのみをエクスポートする場合、startTime パラメータと endTime パラメータを定義して、定義された期間内に送信されたメッセージのみを含めることができます。Message リソースの特定の部分だけをエクスポートするには、MessageView を設定します。

メッセージがエクスポートされると、Cloud Healthcare API は HL7v2 メッセージごとにオブジェクトを作成します。各オブジェクトは、各行に Message リソースを含む .ndjson ファイルで構成されています。メッセージは、sendTime（MSH.7）に基づいて昇順でエクスポートされます。

Console

HL7v2 メッセージを Cloud Storage にエクスポートするには、次の手順を実施します。

1. Google Cloud コンソールで、[データセット] ページに移動します。

   データセットに移動します

2. HL7v2 メッセージのエクスポート元の HL7v2 ストアを含むデータセットをクリックします。

3. データストアのリストで、HL7v2 ストアの [アクション] リストから [エクスポート] を選択します。

   [HL7v2 メッセージのエクスポート] ページが表示されます。

4. [プロジェクト] リストで、Cloud Storage プロジェクトを選択します。

5. [ロケーション] リストで、Cloud Storage バケットを選択します。

6. [エクスポート] をクリックして、Cloud Storage の定義された場所に HL7v2 インスタンスをエクスポートします。

7. オペレーションのステータスを追跡するには、[オペレーション] タブをクリックします。オペレーションが完了すると、次の状況が表示されます。
   • [長時間実行オペレーションのステータス] セクションでは、[OK] の見出しの下に、緑色のチェックマークが表示されます。
   • [概要] セクションでは、オペレーション ID と同じ行に緑色のチェックマークと [OK] インジケーターが表示されます。
   エラーが発生した場合は、[アクション] をクリックしてから、[Cloud Logging で詳細を表示] をクリックします。

API

次のサンプルは、projects.locations.datasets.hl7V2Stores.messages.export メソッドを使用して HL7v2 メッセージを Cloud Storage にエクスポートする方法を示しています。

エクスポート オペレーションを呼び出すときは、次の点に注意してください。

• 多数のメッセージがある場合は Cloud Healthcare API により複数の改行区切りの JSON ファイルが作成される可能性があるため、オブジェクトではなく Cloud Storage バケットまたはディレクトリに書き込みます。各 JSON ファイルの各行は HL7v2 メッセージです。
• コマンドに存在しないディレクトリが指定されている場合は、そのディレクトリが作成されます。

curl

HL7v2 メッセージをエクスポートするには、POST リクエストを行い、次の情報を指定します。

• 親データセットの名前
• HL7v2 ストアの名前。
• 宛先の Cloud Storage バケットまたはディレクトリ
• アクセス トークン

次のサンプルは、curl を使用した POST リクエストを示しています。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'gcsDestination': {
        'uriPrefix': 'gs://BUCKET/DIRECTORY'
      }
    }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:export"

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

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

レスポンスにはオペレーション名が含まれています。オペレーションのステータスを追跡するには、オペレーションの get メソッドを使用します。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

リクエストが成功すると、サーバーはオペレーションのステータスを含む JSON 形式のレスポンスを返します。

{
  "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": "CREATE_TIME",
    "endTime": "END_TIME",
    "counter": {
      "success": "RESOURCE_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.hl7v2.ExportMessagesResponse"
  }
}

PowerShell

HL7v2 メッセージをエクスポートするには、POST リクエストを行い、次の情報を指定します。

• 親データセットの名前
• HL7v2 ストアの名前。
• 宛先の Cloud Storage バケットまたはディレクトリ
• アクセス トークン

次のサンプルは、Windows PowerShell を使用した POST リクエストを示しています。

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body "{
    'gcsDestination': {
      'uriPrefix': 'gs://BUCKET/DIRECTORY'
    }
  }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID:export" | Select-Object -Expand Content

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

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

レスポンスにはオペレーション名が含まれています。オペレーションのステータスを追跡するには、オペレーションの get メソッドを使用します。

$cred = gcloud auth application-default 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

リクエストが成功すると、サーバーはオペレーションのステータスを含む JSON 形式のレスポンスを返します。

{
  "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": "CREATE_TIME",
    "endTime": "END_TIME",
    "counter": {
      "success": "RESOURCE_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.hl7v2.ExportMessagesResponse"
  }
}

HL7v2 のインポートおよびエクスポートに関するリクエストのトラブルシューティング

HL7v2 のインポートまたはエクスポート リクエスト中にエラーが発生した場合、エラーは Cloud Logging に記録されます。詳細については、Cloud Logging でのエラーログの表示をご覧ください。

オペレーションでエラーが返された場合は、長時間実行オペレーションのトラブルシューティングをご覧ください。