Esportazione di messaggi HL7v2 in Cloud Storage

Questa pagina descrive come esportare i messaggi HL7v2 da un datastore HL7v2 in Cloud Storage. Puoi esportare in blocco i messaggi HL7v2 in Cloud Storage per l'elaborazione a valle.

Prima di iniziare

Consulta Esportare i messaggi HL7v2 da Cloud Storage per conoscere i ruoli che devi concedere all'account di servizio Agente di servizio Cloud Healthcare.

Esportazione di messaggi HL7v2 in Cloud Storage

Per eseguire questa attività, devi disporre delle seguenti autorizzazioni o dei seguenti ruoli Identity and Access Management (IAM):

Autorizzazioni

  • healthcare.hl7V2Stores.export nell'archivio HL7v2 richiesto

Ruoli

Puoi chiedere all'amministratore di concederti questi ruoli di Identity and Access Management. Per istruzioni su come concedere i ruoli, consulta Gestire l'accesso o Controllare l'accesso alle risorse dell'API Cloud Healthcare. Potresti anche riuscire a ottenere le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

L'API Cloud Healthcare esporta ogni messaggio HL7v2 come riga in un file NDJSON .ndjson. I messaggi HL7v2 sono ordinati in ordine cronologico in base al valore sendTime.

Esegui l'esportazione in un bucket o in una cartella Cloud Storage anziché in un oggetto, perché l'API Cloud Healthcare potrebbe creare più file NDJSON quando sono presenti molti messaggi HL7v2.

Se esporti in una cartella Cloud Storage che non esiste, la cartella viene creata.

Console

Per esportare i messaggi HL7v2 in 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 contenente 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 messaggi HL7v2.

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

  5. Nell'elenco Posizione, 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 a lunga esecuzione presenta un segno di spunta verde sotto la voce OK.
    • Nella sezione Panoramica è presente un segno di spunta verde e un indicatore OK nella stessa riga dell'ID operazione.
    In caso di errore, fai clic su Azioni e poi su Visualizza dettagli in Cloud Logging.

Esportare messaggi HL7v2 in Cloud Storage utilizzando i filtri

Per impostazione predefinita, l'esportazione di messaggi HL7v2 in Cloud Storage include tutti i messaggi HL7v2 in un archivio HL7v2 e tutti i campi in ogni oggetto Message.

Puoi filtrare i messaggi HL7v2 esportati come segue:

Esportare un sottoinsieme di messaggi HL7v2 utilizzando un filtro

Nei criteri di filtro puoi utilizzare i seguenti campi:

Puoi specificare i seguenti parametri di filtro come criteri di filtro nel campo filter. Per conoscere la sintassi dei filtri e creare query, consulta Stringhe di query.

  • message_type: dal campo MSH.9.1. Ad esempio, NOT message_type = "ADT".
  • send_date: la data YYYY-MM-DD di invio del messaggio dal segmento MSH.7, specificata nel fuso orario del set di dati. Ad esempio: send_date < "2017-01-02".
  • send_time: il timestamp di invio del messaggio. Questo parametro proviene dal segmento MSH.7 del messaggio. Questo parametro utilizza il formato di data e ora RFC 3339 per i confronti. Ad esempio: send_time < "2017-01-02T00:00:00-05:00".
  • create_time: il timestamp della creazione del messaggio nell'API Cloud Healthcare, utilizzando il formato orario RFC 3339 per i confronti. Ad esempio: create_time < "2017-01-02T00:00:00-05:00".
  • send_facility: il centro di assistenza da cui proviene il messaggio, dal segmento MSH.4. Ad esempio, send_facility = "ABC".

Gli esempi riportati di seguito mostrano come specificare un filtro per esportare solo i messaggi HL7v2 di tipo ADT.

REST

  1. Utilizza il metodo hl7V2Stores.export per esportare i messaggi HL7v2:

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto
    • LOCATION: la posizione del set di dati
    • DATASET_ID: il set di dati principale dell'archivio HL7v2
    • HL7V2_STORE_ID: l'ID dell'archivio HL7v2
    • CLOUD_STORAGE_LOCATION: il nome di un bucket o di una cartella Cloud Storage in cui vengono scritti i messaggi HL7v2 esportati

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, scegli una delle seguenti opzioni:

    curlPowerShell

    Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

    cat > request.json << 'EOF'
{
  "gcsDestination": {
    "uriPrefix": "gs://CLOUD_STORAGE_LOCATION"
  },
  "filter": "message_type = \"ADT\""
}
EOF

    Quindi, esegui il seguente comando per inviare la richiesta 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"

    Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

    @'
{
  "gcsDestination": {
    "uriPrefix": "gs://CLOUD_STORAGE_LOCATION"
  },
  "filter": "message_type = \"ADT\""
}
'@  | Out-File -FilePath request.json -Encoding utf8

    Quindi, esegui il seguente comando per inviare la richiesta 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
     L'output è il seguente. La risposta contiene un identificatore per un'operazione a lunga esecuzione (LRO). Le operazioni che richiedono molto tempo vengono restituite quando le chiamate ai metodi potrebbero richiedere ulteriore tempo per essere completate. Prendi nota del valore di OPERATION_ID. Questo valore ti servirà nel passaggio successivo. 
    {
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

  2. Utilizza il metodo projects.locations.datasets.operations.get per ottenere lo stato dell'operazione a lunga esecuzione.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto
    • DATASET_ID: l'ID set di dati
    • LOCATION: la posizione del set di dati
    • OPERATION_ID: l'ID restituito dall'operazione a lunga esecuzione

    Per inviare la richiesta, scegli una delle seguenti opzioni:

    curlPowerShellExplorer API

    Esegui questo comando: 

    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"

    Esegui questo comando: 

    $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

    Apri la pagina di riferimento del metodo. Il riquadro Esplora API si apre sul lato destro della pagina. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

    L'output è il seguente. Quando la risposta contiene "done": true, l'operazione a lunga esecuzione è terminata. 
    {
  "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: ...,
        ...
      }
    ]
  }
}

Esportare i messaggi HL7v2 in base al campo Message

Nell'API Cloud Healthcare, i messaggi HL7v2 vengono archiviati nelle risorse Message. Puoi utilizzare l'enum MessageView per determinare quali campi della risorsa Message sono inclusi in ogni messaggio HL7v2 esportato.

Gli esempi riportati di seguito mostrano come utilizzare il valore BASIC in MessageView per includere solo il campo name nei messaggi HL7v2 esportati.

REST

  1. Utilizza il metodo hl7V2Stores.export per esportare i messaggi HL7v2:

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto
    • LOCATION: la posizione del set di dati
    • DATASET_ID: il set di dati principale dell'archivio HL7v2
    • HL7V2_STORE_ID: l'ID dell'archivio HL7v2
    • CLOUD_STORAGE_LOCATION: il nome di un bucket o di una cartella Cloud Storage in cui vengono scritti i messaggi HL7v2 esportati

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, scegli una delle seguenti opzioni:

    curlPowerShell

    Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

    cat > request.json << 'EOF'
{
  "gcsDestination": {
    "uriPrefix": "gs://CLOUD_STORAGE_LOCATION",
    "messageView": "BASIC"
  }
}
EOF

    Quindi, esegui il seguente comando per inviare la richiesta 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"

    Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

    @'
{
  "gcsDestination": {
    "uriPrefix": "gs://CLOUD_STORAGE_LOCATION",
    "messageView": "BASIC"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

    Quindi, esegui il seguente comando per inviare la richiesta 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
     L'output è il seguente. La risposta contiene un identificatore per un'operazione a lunga esecuzione (LRO). Le operazioni che richiedono molto tempo vengono restituite quando le chiamate ai metodi potrebbero richiedere ulteriore tempo per essere completate. Prendi nota del valore di OPERATION_ID. Questo valore ti servirà nel passaggio successivo. 
    {
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

  2. Utilizza il metodo projects.locations.datasets.operations.get per ottenere lo stato dell'operazione a lunga esecuzione.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID del tuo Google Cloud progetto
    • DATASET_ID: l'ID set di dati
    • LOCATION: la posizione del set di dati
    • OPERATION_ID: l'ID restituito dall'operazione a lunga esecuzione

    Per inviare la richiesta, scegli una delle seguenti opzioni:

    curlPowerShellExplorer API

    Esegui questo comando: 

    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"

    Esegui questo comando: 

    $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

    Apri la pagina di riferimento del metodo. Il riquadro Esplora API si apre sul lato destro della pagina. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

    L'output è il seguente. Quando la risposta contiene "done": true, l'operazione a lunga esecuzione è terminata. 
    {
  "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: ...,
        ...
      }
    ]
  }
}

Risolvere i problemi relativi alle richieste di esportazione HL7v2

Se si verificano errori durante l'esportazione dei messaggi HL7v2, questi vengono registrati in Cloud Logging. Per ulteriori informazioni, consulta Visualizzazione dei log degli errori in Cloud Logging.

Se un'operazione a lunga esecuzione restituisce un errore, consulta la sezione Risoluzione dei problemi relativi alle operazioni a lunga esecuzione.