Importazione ed esportazione di messaggi HL7v2 mediante Cloud Storage

Questa pagina descrive come esportare e importare i messaggi HL7v2 da e verso Cloud Storage utilizzando i metodi projects.locations.datasets.hl7V2Stores.import e projects.locations.datasets.hl7V2Stores.export.

Puoi importare i messaggi HL7v2 da Cloud Storage per semplificare il caricamento in blocco di molti messaggi HL7v2 in un archivio HL7v2. È possibile esportare molti messaggi HL7v2 in Cloud Storage contemporaneamente, invece di doverli archiviare singolarmente in Cloud Storage.

Impostazione delle autorizzazioni Cloud Storage

Prima di esportare e importare messaggi HL7v2 in e da Cloud Storage, devi concedere autorizzazioni aggiuntive all'account di servizio dell'agente di servizio Cloud Healthcare. Per ulteriori informazioni, vedi Autorizzazioni Cloud Storage per gli archivi HL7v2.

Importazione di messaggi HL7v2

Per importare i messaggi HL7v2, devi prima creare uno o più file JSON delimitati da nuova riga (.ndjson) in Cloud Storage contenenti uno o più messaggi. Ogni riga del file è una singola risorsa Message che contiene un messaggio HL7v2 con codifica base64. La risorsa Message può includere anche etichette facoltative.

Ad esempio, il seguente file, denominato messages.ndjson, contiene due messaggi HL7v2. Un'etichetta viene definita nel secondo messaggio.

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

Console

Per importare i messaggi HL7v2 da un bucket Cloud Storage, completa i seguenti passaggi:

  1. Nella console Google Cloud, vai alla pagina Set di dati.

    Vai a Set di dati

  2. Fai clic sul set di dati che contiene l'archivio HL7v2 in cui stai importando i messaggi HL7v2.

  3. Nell'elenco dei datastore, scegli Importa dall'elenco Azioni per l'archivio HL7v2.

    Viene visualizzata la pagina Importa nell'archivio HL7v2.

  4. Nell'elenco Progetto, seleziona un progetto Cloud Storage.

  5. Nell'elenco Località, seleziona un bucket Cloud Storage.

  6. Per impostare una posizione specifica per l'importazione dei file:

    1. Espandi Opzioni avanzate.
    2. Seleziona Override del percorso di Cloud Storage.

    3. Per impostare un'origine specifica per l'importazione dei file, definisci il percorso nella casella di testo Posizione. Puoi utilizzare i caratteri jolly per importare più file da una o più directory. Per ulteriori informazioni sulla denominazione degli oggetti, consulta le linee guida per la denominazione degli oggetti.

      Sono supportati i seguenti caratteri jolly:
      • Utilizza * per trovare una corrispondenza con nessuno o più caratteri non separatori. Ad esempio, gs://BUCKET/DIRECTORY/Example*.ndjson corrisponde a Example.ndjson ed Example22.ndjson in DIRECTORY.
      • Utilizza ** per trovare una corrispondenza con nessuno o più caratteri (inclusi i separatori). Deve essere utilizzato alla fine di un percorso e senza altri caratteri jolly. Può essere utilizzato anche con un'estensione del nome file (ad esempio .ndjson), che importa tutti i file con l'estensione del nome file nella directory specificata e nelle relative sottodirectory. Ad esempio, gs://BUCKET/DIRECTORY/**.ndjson importa tutti i file con l'estensione del nome file .ndjson in DIRECTORY e nelle relative sottodirectory.
      • Usa ? per trovare la corrispondenza di 1 carattere. Ad esempio, gs://BUCKET/DIRECTORY/Example?.ndjson corrisponde a Example1.ndjson, ma non a Example.ndjson o Example01.ndjson.

  7. Fai clic su Importa per importare i messaggi HL7v2 dall'origine definita.

  8. Per monitorare lo stato dell'operazione, fai clic sulla scheda Operazioni. Al termine dell'operazione, vengono visualizzate le seguenti indicazioni:
    • La sezione Stato operazione di lunga durata ha un segno di spunta verde sotto l'intestazione OK.
    • La sezione Panoramica ha un segno di spunta verde e un indicatore OK nella stessa riga dell'ID operazione.
    Se si verificano errori, fai clic su Azioni, quindi su Visualizza dettagli in Cloud Logging.

API

Gli esempi riportati di seguito mostrano come importare i messaggi HL7v2 da Cloud Storage utilizzando il metodo projects.locations.datasets.hl7V2Stores.import.

Quando chiami l'operazione di importazione, tieni presente quanto segue:

  • La posizione del file nel bucket è arbitraria e non deve rispettare esattamente il formato specificato nei seguenti esempi.
  • Quando specifichi la posizione dei messaggi HL7v2 in Cloud Storage, puoi utilizzare i caratteri jolly per importare più file da una o più directory. Sono supportati i seguenti caratteri jolly:
    • Utilizza * per trovare una corrispondenza con nessuno o più caratteri non separatori. Ad esempio, gs://BUCKET/DIRECTORY/Example*.ndjson corrisponde a Example.ndjson ed Example22.ndjson in DIRECTORY.
    • Utilizza ** per trovare una corrispondenza con nessuno o più caratteri (inclusi i separatori). Deve essere utilizzato alla fine di un percorso e senza altri caratteri jolly. Può essere utilizzato anche con un'estensione del nome file (ad esempio .ndjson), che importa tutti i file con l'estensione del nome file nella directory specificata e nelle relative sottodirectory. Ad esempio, gs://BUCKET/DIRECTORY/**.ndjson importa tutti i file con l'estensione del nome file .ndjson in DIRECTORY e nelle relative sottodirectory.
    • Usa ? per trovare la corrispondenza di 1 carattere. Ad esempio, gs://BUCKET/DIRECTORY/Example?.ndjson corrisponde a Example1.ndjson, ma non a Example.ndjson o Example01.ndjson.

curl

Per importare i messaggi HL7v2 in un archivio HL7v2, effettua una richiesta POST e specifica le seguenti informazioni:

  • Il nome del set di dati padre
  • Il nome dell'archivio HL7v2
  • La posizione dell'oggetto in un bucket Cloud Storage
  • Un token di accesso

Il seguente esempio mostra come importare un singolo file utilizzando una richiesta POST mediante curl.

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"

Se la richiesta ha esito positivo, il server restituisce la risposta in formato JSON:

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

La risposta contiene il nome di un'operazione. Per monitorare lo stato dell'operazione, puoi utilizzare il metodo dell'operazione 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"

Se la richiesta ha esito positivo, il server restituisce una risposta con lo stato dell'operazione in formato 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

Per importare i messaggi HL7v2 in un archivio HL7v2, effettua una richiesta POST e specifica le seguenti informazioni:

  • Il nome del set di dati padre
  • Il nome dell'archivio HL7v2
  • La posizione dell'oggetto in un bucket Cloud Storage
  • Un token di accesso

L'esempio seguente mostra come importare un singolo file utilizzando una richiesta POST mediante Windows PowerShell.

$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

Se la richiesta ha esito positivo, il server restituisce la risposta in formato JSON:

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

La risposta contiene il nome di un'operazione. Per monitorare lo stato dell'operazione, puoi utilizzare il metodo dell'operazione 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

Se la richiesta ha esito positivo, il server restituisce una risposta con lo stato dell'operazione in formato 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"
  }
}

Esportazione di messaggi HL7v2

Quando si esportano messaggi HL7v2 da un archivio HL7v2, tutti i messaggi nell'archivio HL7v2 vengono esportati. Per esportare solo un sottoinsieme di questi messaggi, puoi definire i parametri startTime e endTime per includere solo i messaggi inviati entro l'intervallo di tempo definito. Per esportare solo parti specifiche della risorsa Message, imposta MessageView.

Quando i messaggi vengono esportati, l'API Cloud Healthcare crea un oggetto per ogni messaggio HL7v2. Ogni oggetto è costituito da un file .ndjson contenente una risorsa Message su ogni riga. I messaggi vengono esportati in ordine crescente in base al valore sendTime (MSH.7).

Console

Per esportare i messaggi HL7v2 in Cloud Storage, completa questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Set di dati.

    Vai a Set di dati

  2. Fai clic sul set di dati che contiene l'archivio HL7v2 da cui stai esportando i messaggi HL7v2.

  3. Nell'elenco dei datastore, scegli Esporta dall'elenco Azioni per l'archivio HL7v2.

    Viene visualizzata la pagina Esporta i messaggi HL7v2.

  4. Nell'elenco Progetto, seleziona un progetto Cloud Storage.

  5. Nell'elenco Località, seleziona un bucket Cloud Storage.

  6. Fai clic su Esporta per esportare le istanze HL7v2 nella posizione definita in Cloud Storage.

  7. Per monitorare lo stato dell'operazione, fai clic sulla scheda Operazioni. Al termine dell'operazione, vengono visualizzate le seguenti indicazioni:
    • La sezione Stato operazione di lunga durata ha un segno di spunta verde sotto l'intestazione OK.
    • La sezione Panoramica ha un segno di spunta verde e un indicatore OK nella stessa riga dell'ID operazione.
    Se si verificano errori, fai clic su Azioni, quindi su Visualizza dettagli in Cloud Logging.

API

Gli esempi riportati di seguito mostrano come esportare i messaggi HL7v2 in Cloud Storage utilizzando il metodo projects.locations.datasets.hl7V2Stores.messages.export.

Quando chiami l'operazione di esportazione, tieni presente quanto segue:

  • Scrivi in una directory o in un bucket Cloud Storage, anziché in un oggetto, perché l'API Cloud Healthcare potrebbe creare più file JSON delimitati da nuova riga quando ci sono molti messaggi. In ogni file JSON, ogni riga è un messaggio HL7v2.
  • Se il comando specifica una directory che non esiste, la directory viene creata.

curl

Per esportare i messaggi HL7v2, effettua una richiesta POST e specifica le seguenti informazioni:

  • Il nome del set di dati padre
  • Il nome dell'archivio HL7v2
  • Il bucket o la directory Cloud Storage di destinazione
  • Un token di accesso

Il seguente esempio mostra una richiesta POST che utilizza curl.

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"

Se la richiesta ha esito positivo, il server restituisce la risposta in formato JSON:

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

La risposta contiene il nome di un'operazione. Per monitorare lo stato dell'operazione, puoi utilizzare il metodo dell'operazione 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"

Se la richiesta ha esito positivo, il server restituisce una risposta con lo stato dell'operazione in formato 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

Per esportare i messaggi HL7v2, effettua una richiesta POST e specifica le seguenti informazioni:

  • Il nome del set di dati padre
  • Il nome dell'archivio HL7v2
  • Il bucket o la directory Cloud Storage di destinazione
  • Un token di accesso

L'esempio seguente mostra una richiesta POST mediante Windows PowerShell.

$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

Se la richiesta ha esito positivo, il server restituisce la risposta in formato JSON:

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

La risposta contiene il nome di un'operazione. Per monitorare lo stato dell'operazione, puoi utilizzare il metodo dell'operazione 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

Se la richiesta ha esito positivo, il server restituisce una risposta con lo stato dell'operazione in formato 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"
  }
}

Risoluzione dei problemi relativi alle richieste di importazione ed esportazione HL7v2

Se si verificano errori durante una richiesta di importazione o esportazione HL7v2, gli errori vengono registrati in Cloud Logging. Per maggiori informazioni, consulta Visualizzazione dei log degli errori in Cloud Logging.

Se un'operazione restituisce un errore, consulta Risolvere i problemi relativi alle operazioni a lunga esecuzione.