Importa ed esporta le risorse FHIR utilizzando Cloud Storage

Questa pagina spiega come esportare e importare le risorse FHIR da e verso Cloud Storage utilizzando i metodi projects.locations.datasets.fhirStores.import e projects.locations.datasets.fhirStores.export.

A seconda del formato dei tuoi dati FHIR, per caricare i dati in un datastore FHIR puoi utilizzare il metodo projects.locations.datasets.fhirStores.import o projects.locations.datasets.fhirStores.fhir.executeBundle. Per istruzioni nella scelta di un metodo, consulta Importazione FHIR.

Impostazione delle autorizzazioni Cloud Storage

Prima di esportare e importare le risorse FHIR in e da Cloud Storage, devi concedere autorizzazioni aggiuntive all'account di servizio dell'agente di servizio Cloud Healthcare. Per ulteriori informazioni, consulta Autorizzazioni Cloud Storage degli archivi FHIR.

Generazione di dati dei pazienti simulati

SyntheaTM è un simulatore per la generazione di dati sulla popolazione di pazienti. Se non utilizzi SyntheaTM per generare dati sulla popolazione di pazienti, vai a Importazione di risorse FHIR o Esportazione di risorse FHIR.

Puoi importare solo i dati nella versione accettata dal datastore FHIR.

Per scaricare e installare SyntheaTM, completa i seguenti passaggi:

  1. Clona il repository di strumenti SyntheaTM da GitHub:

    git clone https://github.com/synthetichealth/synthea.git

  2. Completa la procedura di installazione.

Vai a una delle seguenti sezioni per generare dati per una versione FHIR specifica:

Generazione di dati pazienti simulati per R4

Per impostazione predefinita, i dati SyntheaTM generati utilizzano la rappresentazione JSON FHIR R4 per le risorse. Per generare dati SyntheaTM FHIR R4 e importarli in un datastore FHIR dell'API Cloud Healthcare, completa i seguenti passaggi:

  1. Segui le istruzioni per generare dati sintetici di pazienti. I dati generati vengono inviati a synthea/output/fhir_r4 per FHIR R4.

  2. Copia i dati generati in un bucket Cloud Storage in modo da poterli importare in un datastore FHIR dell'API Cloud Healthcare. Ad esempio, per copiare i dati in una directory denominata synthea-data in un bucket Cloud Storage esistente, esegui il seguente comando gsutil cp dalla directory synthea:

    gsutil -m cp output/fhir_r4/* gs://BUCKET/synthea-data

  3. Segui le istruzioni per importare le risorse FHIR.

Generazione di dati di pazienti simulati per DSTU2 o STU3

Per generare dati SyntheaTM FHIR DSTU2 o STU3 e importarli in un datastore FHIR dell'API Cloud Healthcare, completa i seguenti passaggi:

  1. Dalla directory synthea, utilizza un editor di testo per aprire il file src/main/resources/synthea.properties, quindi apporta le seguenti modifiche, a seconda che tu stia generando dati DSTU2 o STU3.

    Per generare dati FHIR STU3:

    • Imposta tutti i valori *.fhir.export e *.fhir_dstu2.export su false
    • Imposta tutti i valori *.fhir_stu3.export su true

    Per generare dati FHIR DSTU2:

    • Imposta tutti i valori *.fhir.export e *.fhir_stu3.export su false
    • Imposta tutti i valori *.fhir_dstu2.export su true

    Ad esempio, per generare dati FHIR STU3:

    exporter.fhir.export = false
exporter.fhir_stu3.export = true
exporter.fhir_dstu2.export = false

exporter.hospital.fhir.export = false
exporter.hospital.fhir_stu3.export = true
exporter.hospital.fhir_dstu2.export = false

exporter.practitioner.fhir.export = false
exporter.practitioner.fhir_stu3.export = true
exporter.practitioner.fhir_dstu2.export = false

  2. Segui le istruzioni per generare dati sintetici di pazienti. I dati generati vengono inviati a synthea/output/fhir_stu3 per la STU3 FHIR o alla directory synthea/output/fhir_dstu2 per FHIR DSTU2.

  3. Copia i dati generati in un bucket Cloud Storage in modo da poterli importare in un datastore FHIR dell'API Cloud Healthcare. Ad esempio, per copiare i dati in una directory denominata synthea-data in un bucket Cloud Storage esistente, esegui il seguente comando gsutil cp dalla directory synthea:

    gsutil -m cp output/fhir_stu3/* gs://BUCKET/synthea-data

  4. Segui le istruzioni per importare le risorse FHIR.

Importazione delle risorse FHIR

Quando configuri il corpo della richiesta di importazione, imposta ContentStructure su uno dei seguenti valori:

  • CONTENT_STRUCTURE_UNSPECIFIED
  • BUNDLE: il file di origine contiene una o più righe di codice JSON delimitato da una nuova riga (ndjson). Ogni riga è un bundle contenente una o più risorse. Se non specifichi ContentStructure, il valore predefinito sarà BUNDLE.
  • RESOURCE: il file di origine contiene una o più righe di JSON (ndjson) delimitato da nuova riga. Ogni riga è una singola risorsa.
  • BUNDLE_PRETTY: l'intero file di origine è un unico bundle JSON. Il formato JSON può occupare più righe.
  • RESOURCE_PRETTY: l'intero file di origine è una risorsa JSON. Il formato JSON può occupare più righe.

Ad esempio, supponiamo che tu stia importando un file denominato resources.ndjson con i seguenti contenuti:

{"class":{"code":"IMP","display":"inpatient encounter","system":"http://hl7.org/fhir/v3/ActCode"},"id":"6090e773-3e91-40a7-8fce-1e22f6774c29","reason":[{"text":"The patient had an abnormal heart rate. She was concerned about this."}],"resourceType":"Encounter","status":"finished","subject":{"reference":"Patient/2938bb9e-1f16-429e-8d44-9508ab0e4151"}}
{"class":{"code":"IMP","display":"inpatient encounter","system":"http://hl7.org/fhir/v3/ActCode"},"id":"7101f884-4f02-51b8-9gdf-2f33g7885d30","reason":[{"text":"The patient was experiencing recurrent fevers."}],"resourceType":"Encounter","status":"finished","subject":{"reference":"Patient/3049cc0f-2g27-530f-9e55-0619bc1f5262"}}
{"birthDate":"1970-01-01","gender":"female","id":"2938bb9e-1f16-429e-8d44-9508ab0e4151","name":[{"family":"Smith","given":["Darcy"],"use":"official"}],"resourceType":"Patient"}

Il file contiene due risorse Encounter e una risorsa Patient. Ogni risorsa si trova su una riga separata, quindi imposti ContentStructure su RESOURCE.

I dati potrebbero essere importati in modo errato o non importarli affatto se ContentStructure non corrisponde al formato dei dati. Ad esempio, il file di esempio riportato sopra non verrà importato correttamente, a meno che ContentStructure non sia impostato su RESOURCE nella richiesta di importazione.

Gli esempi riportati di seguito mostrano come importare le risorse FHIR da un bucket Cloud Storage.

Console

Per importare le risorse FHIR 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 il datastore FHIR in cui stai importando le risorse FHIR.
  3. Nell'elenco dei datastore, scegli Importa dall'elenco Azioni per il datastore FHIR.

    Viene visualizzata la pagina Importa nel datastore FHIR.
  4. Nell'elenco Progetto, seleziona un progetto Cloud Storage.
  5. Nell'elenco Località, seleziona un bucket Cloud Storage.
  6. Nelle impostazioni di importazione FHIR, seleziona la struttura dei contenuti pertinente.
  7. Fai clic su Importa per importare le risorse FHIR.
  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 a lunga esecuzione ha un segno di spunta verde sotto l'intestazione OK.
    • La sezione Panoramica contiene un segno di spunta verde e un indicatore OK nella stessa riga dell'ID operazione.
    Se si verificano errori, fai clic su Azioni e poi su Visualizza dettagli in Cloud Logging.

gcloud

Per importare le risorse FHIR in un datastore FHIR, utilizza il comando gcloud healthcare fhir-stores import gcs. Specifica le seguenti informazioni:

  • Il nome del set di dati padre
  • Il nome del datastore FHIR
  • La posizione dell'oggetto in un bucket Cloud Storage. La posizione dei file all'interno del bucket è arbitraria e non deve rispettare esattamente il formato specificato nell'esempio seguente. Quando specifichi la posizione delle risorse FHIR 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 zero o più caratteri non separatori. Ad esempio, gs://BUCKET/DIRECTORY/Example*.ndjson corrisponde a Example.ndjson ed Example22.ndjson in DIRECTORY.
    • Utilizza ** per trovare corrispondenze di 0 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 di nome file (come .ndjson), che importa tutti i file con questa estensione nella directory specificata e nelle relative sottodirectory. Ad esempio, gs://BUCKET/DIRECTORY/**.ndjson importa tutti i file con l'estensione .ndjson del nome file in DIRECTORY e nelle relative sottodirectory.
    • Usa ? per la corrispondenza di 1 carattere. Ad esempio, gs://BUCKET/DIRECTORY/Example?.ndjson corrisponde a Example1.ndjson, ma non a Example.ndjson o a Example01.ndjson.

Il seguente esempio mostra il comando gcloud healthcare fhir-stores import gcs.

gcloud healthcare fhir-stores import gcs FHIR_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION \
  --gcs-uri=gs://BUCKET/DIRECTORY/FHIR_RESOURCE_NAME.ndjson

Per specificare la struttura dei file di origine FHIR, utilizza il flag --content-structure.

La riga di comando visualizza l'ID operazione e, al termine dell'operazione, done:

Request issued for: [FHIR_STORE_ID]
Waiting for operation [OPERATION_ID] to complete...done.
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID

Per visualizzare ulteriori dettagli dell'operazione, esegui il comando gcloud healthcare operations describe, fornendo il valore OPERATION_ID dalla risposta:

gcloud healthcare operations describe OPERATION_ID \
  --dataset=DATASET_ID

La risposta include done: true.

done: true
metadata:
'@type': type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata
apiMethodName: google.cloud.healthcare.v1.fhir.FhirService.ImportResources
createTime: 'CREATE_TIME'
endTime: 'END_TIME'
logsUrl: https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL,
counter:
  success: 'SUCCESS_COUNT'
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID
response:
'@type': type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse
fhirStore: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID

API

Per importare le risorse FHIR in un datastore FHIR, utilizza il metodo projects.locations.datasets.fhirStores.import.

  • La posizione dei file all'interno del bucket è arbitraria e non deve rispettare esattamente il formato specificato negli esempi che seguono.
  • Quando specifichi la posizione delle risorse FHIR 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 zero o più caratteri non separatori. Ad esempio, gs://BUCKET/DIRECTORY/Example*.ndjson corrisponde a Example.ndjson ed Example22.ndjson in DIRECTORY.
    • Utilizza ** per trovare corrispondenze di 0 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 di nome file (come .ndjson), che importa tutti i file con questa estensione nella directory specificata e nelle relative sottodirectory. Ad esempio, gs://BUCKET/DIRECTORY/**.ndjson importa tutti i file con l'estensione .ndjson del nome file in DIRECTORY e nelle relative sottodirectory.
    • Usa ? per la corrispondenza di 1 carattere. Ad esempio, gs://BUCKET/DIRECTORY/Example?.ndjson corrisponde a Example1.ndjson, ma non a Example.ndjson o a Example01.ndjson.

curl

Per importare le risorse FHIR in un datastore FHIR, effettua una richiesta POST e specifica le seguenti informazioni:

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

Il seguente esempio mostra come importare un singolo file con 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 "{
      'contentStructure': 'CONTENT_STRUCTURE',
      'gcsSource': {
        'uri': 'gs://BUCKET/DIRECTORY/FHIR_RESOURCE_FILE'
      }
    }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_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.fhir.FhirService.ImportResources",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse",
  }
}

PowerShell

Per importare le risorse FHIR in un datastore FHIR, effettua una richiesta POST e specifica le seguenti informazioni:

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

Il seguente esempio 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 "{
    'contentStructure': 'CONTENT_STRUCTURE',
    'gcsSource': {
      'uri': 'gs://BUCKET/DIRECTORY/FHIR_RESOURCE_FILE'
    }
  }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_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.fhir.FhirService.ImportResources",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse",
  }
}

Go

import (
	"context"
	"fmt"
	"io"
	"time"

	healthcare "google.golang.org/api/healthcare/v1"
)

// importsFHIRResource imports an FHIR resource.
func importFHIRResource(w io.Writer, projectID, location, datasetID, fhirStoreID, gcsURI string) error {
	ctx := context.Background()

	healthcareService, err := healthcare.NewService(ctx)
	if err != nil {
		return fmt.Errorf("healthcare.NewService: %w", err)
	}

	storesService := healthcareService.Projects.Locations.Datasets.FhirStores

	name := fmt.Sprintf("projects/%s/locations/%s/datasets/%s/fhirStores/%s", projectID, location, datasetID, fhirStoreID)
	req := &healthcare.ImportResourcesRequest{
		ContentStructure: "RESOURCE",
		GcsSource: &healthcare.GoogleCloudHealthcareV1FhirGcsSource{
			Uri: gcsURI,
		},
	}

	op, err := storesService.Import(name, req).Do()
	if err != nil {
		return fmt.Errorf("Import: %w", err)
	}

	operationsService := healthcareService.Projects.Locations.Datasets.Operations
	ticker := time.NewTicker(1 * time.Second)
	defer ticker.Stop()
	for {
		select {
		case <-ctx.Done():
			return ctx.Err()
		case <-ticker.C:
			newOp, err := operationsService.Get(op.Name).Do()
			if err != nil {
				return fmt.Errorf("operationsService.Get(%q): %v", op.Name, err)
			}
			if newOp.Done {
				if newOp.Error != nil {
					return fmt.Errorf("import operation %q completed with error: %s", op.Name, newOp.Error.Details)
				}
				return nil
			}
		}
	}
}

Java

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.healthcare.v1.CloudHealthcare;
import com.google.api.services.healthcare.v1.CloudHealthcare.Projects.Locations.Datasets.FhirStores;
import com.google.api.services.healthcare.v1.CloudHealthcareScopes;
import com.google.api.services.healthcare.v1.model.GoogleCloudHealthcareV1FhirGcsSource;
import com.google.api.services.healthcare.v1.model.ImportResourcesRequest;
import com.google.api.services.healthcare.v1.model.Operation;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Collections;

public class FhirStoreImport {
  private static final String FHIR_NAME = "projects/%s/locations/%s/datasets/%s/fhirStores/%s";
  private static final JsonFactory JSON_FACTORY = new GsonFactory();
  private static final NetHttpTransport HTTP_TRANSPORT = new NetHttpTransport();

  public static void fhirStoreImport(String fhirStoreName, String gcsUri) throws IOException {
    // String fhirStoreName =
    //    String.format(
    //        FHIR_NAME, "your-project-id", "your-region-id", "your-dataset-id", "your-fhir-id");
    // String gcsUri = "gs://your-bucket-id/path/to/destination/dir"

    // Initialize the client, which will be used to interact with the service.
    CloudHealthcare client = createClient();

    // Configure where the store should be imported from.
    GoogleCloudHealthcareV1FhirGcsSource gcsSource =
        new GoogleCloudHealthcareV1FhirGcsSource().setUri(gcsUri);
    ImportResourcesRequest importRequest = new ImportResourcesRequest().setGcsSource(gcsSource);

    // Create request and configure any parameters.
    FhirStores.CloudHealthcareImport request =
        client
            .projects()
            .locations()
            .datasets()
            .fhirStores()
            .healthcareImport(fhirStoreName, importRequest);

    // Execute the request, wait for the operation to complete, and process the results.
    try {
      Operation operation = request.execute();
      while (operation.getDone() == null || !operation.getDone()) {
        // Update the status of the operation with another request.
        Thread.sleep(500); // Pause for 500ms between requests.
        operation =
            client
                .projects()
                .locations()
                .datasets()
                .operations()
                .get(operation.getName())
                .execute();
      }
      System.out.println("FHIR store import complete: " + operation.getResponse());
    } catch (Exception ex) {
      System.out.printf("Error during request execution: %s", ex.toString());
      ex.printStackTrace(System.out);
    }
  }

  private static CloudHealthcare createClient() throws IOException {
    // Use Application Default Credentials (ADC) to authenticate the requests
    // For more information see https://cloud.google.com/docs/authentication/production
    GoogleCredentials credential =
        GoogleCredentials.getApplicationDefault()
            .createScoped(Collections.singleton(CloudHealthcareScopes.CLOUD_PLATFORM));

    // Create a HttpRequestInitializer, which will provide a baseline configuration to all requests.
    HttpRequestInitializer requestInitializer =
        request -> {
          new HttpCredentialsAdapter(credential).initialize(request);
          request.setConnectTimeout(60000); // 1 minute connect timeout
          request.setReadTimeout(60000); // 1 minute read timeout
        };

    // Build the client for interacting with the service.
    return new CloudHealthcare.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
        .setApplicationName("your-application-name")
        .build();
  }
}

Node.js

const google = require('@googleapis/healthcare');
const healthcare = google.healthcare({
  version: 'v1',
  auth: new google.auth.GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
  }),
});
const sleep = ms => {
  return new Promise(resolve => setTimeout(resolve, ms));
};

const importFhirResources = async () => {
  // TODO(developer): uncomment these lines before running the sample
  // const cloudRegion = 'us-central1';
  // const projectId = 'adjective-noun-123';
  // const datasetId = 'my-dataset';
  // const fhirStoreId = 'my-fhir-store';
  // const gcsUri = 'my-bucket/my-directory/*.json'
  const name = `projects/${projectId}/locations/${cloudRegion}/datasets/${datasetId}/fhirStores/${fhirStoreId}`;
  const request = {
    name,
    resource: {
      contentStructure: 'RESOURCE',
      gcsSource: {
        uri: `gs://${gcsUri}`,
      },
    },
  };

  const operation =
    await healthcare.projects.locations.datasets.fhirStores.import(request);
  const operationName = operation.data.name;

  const operationRequest = {name: operationName};

  // Wait twenty seconds for the LRO to finish.
  await sleep(20000);

  // Check the LRO's status
  const operationStatus =
    await healthcare.projects.locations.datasets.operations.get(
      operationRequest
    );

  const success = operationStatus.data.metadata.counter.success;

  if (typeof success !== 'undefined') {
    console.log(
      `Import FHIR resources succeeded. ${success} resources imported.`
    );
  } else {
    console.log(
      'Imported FHIR resources failed. Details available in Cloud Logging at the following URL:\n',
      operationStatus.data.metadata.logsUrl
    );
  }
};

importFhirResources();

Python

def import_fhir_resources(project_id, location, dataset_id, fhir_store_id, gcs_uri):
    """Import resources into the FHIR store by copying them from the
    specified source.

    See https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/healthcare/api-client/v1/fhir
    before running the sample."""
    # Imports the Google API Discovery Service.
    from googleapiclient import discovery

    api_version = "v1"
    service_name = "healthcare"
    # Instantiates an authorized API client by discovering the Healthcare API
    # and using GOOGLE_APPLICATION_CREDENTIALS environment variable.
    client = discovery.build(service_name, api_version)

    # TODO(developer): Uncomment these lines and replace with your values.
    # project_id = 'my-project'  # replace with your GCP project ID
    # location = 'us-central1'  # replace with the parent dataset's location
    # dataset_id = 'my-dataset'  # replace with the parent dataset's ID
    # fhir_store_id = 'my-fhir-store'  # replace with the FHIR store ID
    # gcs_uri = 'my-bucket'  # replace with a Cloud Storage bucket
    fhir_store_parent = "projects/{}/locations/{}/datasets/{}".format(
        project_id, location, dataset_id
    )
    fhir_store_name = f"{fhir_store_parent}/fhirStores/{fhir_store_id}"

    body = {
        "contentStructure": "CONTENT_STRUCTURE_UNSPECIFIED",
        "gcsSource": {"uri": f"gs://{gcs_uri}"},
    }

    # Escape "import()" method keyword because "import"
    # is a reserved keyword in Python
    request = (
        client.projects()
        .locations()
        .datasets()
        .fhirStores()
        .import_(name=fhir_store_name, body=body)
    )

    response = request.execute()
    print(f"Imported FHIR resources: {gcs_uri}")

    return response

Esportazione delle risorse FHIR

Gli esempi riportati di seguito mostrano come esportare le risorse FHIR in un bucket Cloud Storage. Quando esporti le risorse FHIR da un datastore FHIR, vengono esportate tutte le risorse nel datastore FHIR.

Durante l'esportazione, l'API Cloud Healthcare crea un file per ogni tipo di risorsa dall'archivio FHIR. Il nome file è composto dall'ID operazione e dal tipo di risorsa separati da un trattino basso. Ogni file è costituito da un JSON delimitato da una nuova riga, dove ogni riga è una risorsa FHIR corrispondente al tipo di risorsa nel nome file. Ad esempio, se esporti più record Patient, il file di output verrà chiamato in modo simile a 1264567891234567_Patient e conterrà una riga per ogni risorsa Patient dal datastore FHIR.

Console

Per esportare le risorse FHIR 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 il datastore FHIR da cui stai esportando le risorse FHIR.
  3. Nell'elenco dei datastore, scegli Esporta dall'elenco Azioni per il datastore FHIR.

    Viene visualizzata la pagina Esporta risorse FHIR.
  4. Seleziona Bucket Google Cloud Storage.
  5. Nell'elenco Progetto, seleziona un progetto Cloud Storage.
  6. Nell'elenco Località, seleziona un bucket Cloud Storage.
  7. Fai clic su Esporta per esportare le risorse FHIR nella località definita in Cloud Storage.
  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 a lunga esecuzione ha un segno di spunta verde sotto l'intestazione OK.
    • La sezione Panoramica contiene un segno di spunta verde e un indicatore OK nella stessa riga dell'ID operazione.
    Se si verificano errori, fai clic su Azioni e poi su Visualizza dettagli in Cloud Logging.

gcloud

Per esportare le risorse FHIR in un bucket Cloud Storage, utilizza il comando gcloud healthcare fhir-stores export gcs. Specifica le seguenti informazioni:

  • Il nome del set di dati padre
  • Il nome del datastore FHIR
  • Il nome del progetto principale
  • La directory o il bucket Cloud Storage di destinazione. Scrivi in una directory o in un bucket Cloud Storage, anziché in un oggetto, poiché l'API Cloud Healthcare crea un oggetto per ogni tipo di risorsa. Ogni oggetto è costituito da un JSON delimitato da nuova riga, dove ogni riga è una risorsa FHIR. Se specifichi una directory che non esiste, viene creata.
  • Un flag facoltativo, --resource-type, che esporta solo tipi di risorse specifici, definiti come elenco separato da virgole di uno o più tipi di risorse FHIR
  • Un flag facoltativo, --since, che esporta solo le risorse aggiornate dopo un intervallo di tempo specifico, definito come YYYY-MM-DDThh:mm:ss.sss+zz:zz

Il seguente esempio mostra il comando gcloud healthcare fhir-stores export gcs.

gcloud healthcare fhir-stores export gcs FHIR_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION \
  --project=PROJECT_ID
  --gcs-uri=gs://BUCKET/DIRECTORY

La riga di comando visualizza l'ID operazione:

Waiting for operation [OPERATION_ID] to complete...done.
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID

Per visualizzare lo stato dell'operazione, esegui il comando gcloud healthcare operations describe, fornendo il valore OPERATION_ID dalla risposta:

gcloud healthcare operations describe OPERATION_ID \
  --dataset=DATASET_ID

Una volta completato il comando, la risposta include done.

metadata:
'@type': type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata
apiMethodName: google.cloud.healthcare.v1.fhir.FhirService.ExportFhirData
createTime: "CREATE_TIME"
endTime: "END_TIME"
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID
response:
'@type': type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ExportResourcesResponse
fhirStore: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID
resourceCount: 'RESOURCE_COUNT'

API

Per esportare le risorse FHIR, utilizza il metodo projects.locations.datasets.fhirStores.export.

  • Scrivi in un bucket o in una directory Cloud Storage, anziché in un oggetto, perché l'API Cloud Healthcare crea un file JSON delimitato da nuova riga per ogni tipo di risorsa. In ogni file JSON, ogni riga è una risorsa FHIR.
  • Se il comando specifica una directory che non esiste, viene creata.

curl

Per esportare le risorse FHIR, effettua una richiesta POST e specifica le seguenti informazioni:

  • Il nome del set di dati padre
  • Il nome del datastore FHIR
  • Il bucket Cloud Storage di destinazione
  • Un token di accesso
  • Un campo facoltativo, _type, che esporta solo tipi di risorse specifici, definiti come elenco separato da virgole di uno o più tipi di risorse FHIR
  • Un campo facoltativo, _since, che esporta solo le risorse aggiornate dopo un periodo di tempo specifico, definito come YYYY-MM-DDThh:mm:ss.sss+zz:zz

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/fhirStores/FHIR_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.fhir.FhirService.ExportResources",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ExportResourcesResponse",
  }
}

PowerShell

Per esportare le risorse FHIR, effettua una richiesta POST e specifica le seguenti informazioni:

  • Il nome del set di dati padre
  • Il nome del datastore FHIR
  • La directory o il bucket Cloud Storage di destinazione. Scrivi in una directory o in un bucket Cloud Storage, anziché in un oggetto, poiché l'API Cloud Healthcare crea un oggetto per ogni tipo di risorsa. Ogni oggetto è costituito da JSON delimitato da nuova riga, dove ogni riga è una risorsa FHIR.
  • Un token di accesso
  • Un campo facoltativo, _type, che esporta solo tipi di risorse specifici, definiti come elenco separato da virgole di uno o più tipi di risorse FHIR
  • Un campo facoltativo, _since, che esporta solo le risorse aggiornate dopo un periodo di tempo specifico, definito come YYYY-MM-DDThh:mm:ss.sss+zz:zz

Il seguente esempio 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/fhirStores/FHIR_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.fhir.FhirService.ExportResources",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ExportResourcesResponse",
  }
}

Go

import (
	"context"
	"fmt"
	"io"
	"time"

	healthcare "google.golang.org/api/healthcare/v1"
)

// exportFHIRResource exports the resources in the FHIR store.
func exportFHIRResource(w io.Writer, projectID, location, datasetID, fhirStoreID, gcsURIPrefix string) error {
	ctx := context.Background()

	healthcareService, err := healthcare.NewService(ctx)
	if err != nil {
		return fmt.Errorf("healthcare.NewService: %w", err)
	}

	storesService := healthcareService.Projects.Locations.Datasets.FhirStores

	name := fmt.Sprintf("projects/%s/locations/%s/datasets/%s/fhirStores/%s", projectID, location, datasetID, fhirStoreID)
	req := &healthcare.ExportResourcesRequest{
		GcsDestination: &healthcare.GoogleCloudHealthcareV1FhirGcsDestination{
			UriPrefix: gcsURIPrefix,
		},
	}

	op, err := storesService.Export(name, req).Do()
	if err != nil {
		return fmt.Errorf("Export: %w", err)
	}

	operationsService := healthcareService.Projects.Locations.Datasets.Operations
	ticker := time.NewTicker(1 * time.Second)
	defer ticker.Stop()
	for {
		select {
		case <-ctx.Done():
			return ctx.Err()
		case <-ticker.C:
			newOp, err := operationsService.Get(op.Name).Do()
			if err != nil {
				return fmt.Errorf("operationsService.Get(%q): %v", op.Name, err)
			}
			if newOp.Done {
				if newOp.Error != nil {
					return fmt.Errorf("export operation %q completed with error: %v", op.Name, newOp.Error)
				}
				return nil
			}
		}
	}
}

Java

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.healthcare.v1.CloudHealthcare;
import com.google.api.services.healthcare.v1.CloudHealthcare.Projects.Locations.Datasets.FhirStores;
import com.google.api.services.healthcare.v1.CloudHealthcareScopes;
import com.google.api.services.healthcare.v1.model.ExportResourcesRequest;
import com.google.api.services.healthcare.v1.model.GoogleCloudHealthcareV1FhirGcsDestination;
import com.google.api.services.healthcare.v1.model.Operation;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Collections;

public class FhirStoreExport {
  private static final String FHIR_NAME = "projects/%s/locations/%s/datasets/%s/fhirStores/%s";
  private static final JsonFactory JSON_FACTORY = new GsonFactory();
  private static final NetHttpTransport HTTP_TRANSPORT = new NetHttpTransport();

  public static void fhirStoreExport(String fhirStoreName, String gcsUri) throws IOException {
    // String fhirStoreName =
    //    String.format(
    //        FHIR_NAME, "your-project-id", "your-region-id", "your-dataset-id", "your-fhir-id");
    // String gcsUri = "gs://your-bucket-id/path/to/destination/dir"

    // Initialize the client, which will be used to interact with the service.
    CloudHealthcare client = createClient();

    // Configure where the store will be exported too.
    GoogleCloudHealthcareV1FhirGcsDestination gcsDestination =
        new GoogleCloudHealthcareV1FhirGcsDestination().setUriPrefix(gcsUri);
    ExportResourcesRequest exportRequest =
        new ExportResourcesRequest().setGcsDestination(gcsDestination);

    // Create request and configure any parameters.
    FhirStores.Export request =
        client.projects().locations().datasets().fhirStores().export(fhirStoreName, exportRequest);

    // Execute the request, wait for the operation to complete, and process the results.
    try {
      Operation operation = request.execute();
      while (operation.getDone() == null || !operation.getDone()) {
        // Update the status of the operation with another request.
        Thread.sleep(500); // Pause for 500ms between requests.
        operation =
            client
                .projects()
                .locations()
                .datasets()
                .operations()
                .get(operation.getName())
                .execute();
      }
      System.out.println("Fhir store export complete." + operation.getResponse());
    } catch (Exception ex) {
      System.out.printf("Error during request execution: %s", ex.toString());
      ex.printStackTrace(System.out);
    }
  }

  private static CloudHealthcare createClient() throws IOException {
    // Use Application Default Credentials (ADC) to authenticate the requests
    // For more information see https://cloud.google.com/docs/authentication/production
    GoogleCredentials credential =
        GoogleCredentials.getApplicationDefault()
            .createScoped(Collections.singleton(CloudHealthcareScopes.CLOUD_PLATFORM));

    // Create a HttpRequestInitializer, which will provide a baseline configuration to all requests.
    HttpRequestInitializer requestInitializer =
        request -> {
          new HttpCredentialsAdapter(credential).initialize(request);
          request.setConnectTimeout(60000); // 1 minute connect timeout
          request.setReadTimeout(60000); // 1 minute read timeout
        };

    // Build the client for interacting with the service.
    return new CloudHealthcare.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
        .setApplicationName("your-application-name")
        .build();
  }
}

Node.js

const google = require('@googleapis/healthcare');
const healthcare = google.healthcare({
  version: 'v1',
  auth: new google.auth.GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
  }),
});
const sleep = ms => {
  return new Promise(resolve => setTimeout(resolve, ms));
};

const exportFhirResourcesGcs = async () => {
  // TODO(developer): uncomment these lines before running the sample
  // const cloudRegion = 'us-central1';
  // const projectId = 'adjective-noun-123';
  // const datasetId = 'my-dataset';
  // const fhirStoreId = 'my-fhir-store';
  // const gcsUri = 'my-bucket/my-directory'
  const name = `projects/${projectId}/locations/${cloudRegion}/datasets/${datasetId}/fhirStores/${fhirStoreId}`;
  const request = {
    name,
    resource: {
      gcsDestination: {
        // The destination location in Cloud Storage for the FHIR resources
        uriPrefix: `gs://${gcsUri}`,
      },
    },
  };

  const operation =
    await healthcare.projects.locations.datasets.fhirStores.export(request);
  const operationName = operation.data.name;

  // Wait ten seconds for the LRO to finish
  await sleep(10000);

  // Check the LRO's status
  const operationStatus =
    await healthcare.projects.locations.datasets.operations.get({
      name: operationName,
    });

  if (typeof operationStatus.data.metadata.counter !== 'undefined') {
    console.log('Exported FHIR resources successfully');
  } else {
    console.log('Export failed');
  }
};

exportFhirResourcesGcs();

Python

def export_fhir_store_gcs(project_id, location, dataset_id, fhir_store_id, gcs_uri):
    """Export resources to a Google Cloud Storage bucket by copying
    them from the FHIR store.

    See https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/healthcare/api-client/v1/fhir
    before running the sample."""
    # Imports the Google API Discovery Service.
    from googleapiclient import discovery

    api_version = "v1"
    service_name = "healthcare"
    # Instantiates an authorized API client by discovering the Healthcare API
    # and using GOOGLE_APPLICATION_CREDENTIALS environment variable.
    client = discovery.build(service_name, api_version)

    # TODO(developer): Uncomment these lines and replace with your values.
    # project_id = 'my-project'  # replace with your GCP project ID
    # location = 'us-central1'  # replace with the parent dataset's location
    # dataset_id = 'my-dataset'  # replace with the parent dataset's ID
    # fhir_store_id = 'my-fhir-store' # replace with the FHIR store ID
    # gcs_uri = 'my-bucket' # replace with a Cloud Storage bucket
    fhir_store_parent = "projects/{}/locations/{}/datasets/{}".format(
        project_id, location, dataset_id
    )
    fhir_store_name = f"{fhir_store_parent}/fhirStores/{fhir_store_id}"

    body = {"gcsDestination": {"uriPrefix": f"gs://{gcs_uri}/fhir_export"}}

    request = (
        client.projects()
        .locations()
        .datasets()
        .fhirStores()
        .export(name=fhir_store_name, body=body)
    )

    response = request.execute()
    print(f"Exported FHIR resources to bucket: gs://{gcs_uri}")

    return response

Risoluzione dei problemi relativi alle richieste di importazione ed esportazione di FHIR

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

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

Passaggi successivi