Configura i profili FHIR

Le guide all'implementazione e i profili FHIR garantiscono che le risorse in un archivio FHIR siano conformi a criteri specifici definiti. Alcuni esempi di guide all'implementazione includono la US Core Implementation Guide 4.0.0 e la Carin Blue Button Implementation Guide.

Questa pagina spiega come definire, configurare e utilizzare le guide all'implementazione e i profili nei datastore FHIR R4 utilizzando la guida all'implementazione US Core 4.0.0.

Panoramica

I profili FHIR sono un insieme di regole aggiuntive definite in base alla specifica FHIR di base che gestiscono il modo in cui i diversi sistemi sanitari elaborano le risorse. Puoi importare e attivare i profili FHIR in un archivio FHIR per assicurarti che tutte le risorse in un archivio FHIR soddisfino criteri specifici per la struttura delle risorse e le informazioni acquisite.

Definizioni della struttura e guide all'implementazione

Puoi importare profili FHIR per il tuo archivio FHIR inserendo una o più definizioni di struttura raggruppate in una o più guide all'implementazione. Utilizza una definizione della struttura per:

• Definisci il vincolo per un campo in una risorsa FHIR.
• Set di valori di riferimento che collegano sistemi di codici e risorse FHIR.

Utilizzi una guida all'implementazione con definizioni di struttura per convalidare le risorse in modo che corrispondano al caso d'uso del software di terze parti.

Ad esempio, supponiamo che il tuo software di terze parti debba rispettare la norma finale sull'interoperabilità e l'accesso dei pazienti dei Centers for Medicare & Medicaid Services (CMS) negli Stati Uniti. Il software di terze parti dovrebbe fornire un'API Patient Access conforme ai profili CARIN. Puoi importare e attivare la guida all'implementazione di CARIN nel tuo datastore FHIR per convalidare le risorse in base ai profili CARIN. L'importazione e l'attivazione delle guide all'implementazione sono descritte nelle sezioni successive di questa pagina.

Dopo aver importato la guida all'implementazione, puoi attivarla nel tuo datastore FHIR per la convalida delle risorse FHIR. Quando una risorsa FHIR viene aggiornata o aggiunta all'archivio, l'API Cloud Healthcare verifica se corrisponde a una definizione di struttura nella guida all'implementazione. Se la risorsa FHIR corrisponde, viene aggiunta all'archivio. Se la risorsa FHIR non è conforme alle definizioni della struttura nella guida all'implementazione, viene restituito un messaggio di errore e la risorsa FHIR viene rifiutata.

Applicazione della convalida dei dati

L'API Cloud Healthcare applica la convalida dei dati quando vengono utilizzati i seguenti metodi:

• projects.locations.datasets.fhirStores.fhir.create
• projects.locations.datasets.fhirStores.fhir.update
• projects.locations.datasets.fhirStores.fhir.patch
• projects.locations.datasets.fhirStores.executeBundle

Flusso di lavoro di convalida del profilo

Il seguente diagramma mostra il flusso di lavoro di convalida per l'aggiunta o l'aggiornamento delle risorse FHIR:

Definisci i profili FHIR

Le sezioni seguenti descrivono come scaricare le definizioni della struttura dal software di terze parti e configurare una guida all'implementazione.

Scaricare le risorse per la convalida del profilo

Per assicurarti che le definizioni della struttura corrispondano alla tua fonte autorevole, devi scaricare le risorse di convalida del profilo, come le definizioni della struttura, le guide all'implementazione o i set di valori, da una fonte esterna, ad esempio il registro delle guide all'implementazione di FHIR.org. Le origini esterne forniscono un pacchetto che contiene tutti i set di valori, i profili, le estensioni, un elenco di pagine e gli URL per ogni guida all'implementazione.

Ad esempio, se il tuo sistema utilizza il profilo paziente US Core, puoi scaricare le definizioni di struttura e la guida all'implementazione utilizzate da US Core.

L'API Cloud Healthcare consente la convalida per il seguente tipo di regole di definizione della struttura:

• slicing, con supporto per i seguenti discriminatori:
  • value
  • pattern
  • profile
• min/max
• type
• fixed
• pattern
• minValue
• maxValue
• maxLength
• binding, ad eccezione delle seguenti regole:
  • ValueSet.compose.include.filter
  • ValueSet.compose.exclude

Configura la guida all'implementazione

Dopo aver scaricato le definizioni della struttura, la guida all'implementazione e il set di valori, devi aggiungere i profili utilizzati dalla guida all'implementazione per convalidare le risorse FHIR.

Per configurare la guida all'implementazione, completa i seguenti passaggi:

1. Apri il file della guida all'implementazione scaricato dal tuo fornitore di software di terze parti.

2. Aggiungi la seguente sezione per includere le definizioni della struttura da convalidare nella guida all'implementazione:

   {
       "resourceType": "ImplementationGuide",
       ...
       "global": [
           {
           "type": "RESOURCE_TYPE",
           "profile": "STRUCTURE_DEFINITION_URL"
           }
       ]
       ...
   }

   Sostituisci quanto segue:

   • RESOURCE_TYPE: definisce il tipo di risorsa a cui si applica la guida all'implementazione.
   • STRUCTURE_DEFINITION_URL: l'URL della definizione della struttura dell'origine del profilo, ad esempio il profilo del paziente principale degli Stati Uniti.

3. Salva il file della guida all'implementazione.

   L'esempio seguente mostra i profili Patient e Organization abilitati per la guida all'implementazione di US Core:

   "global":[
     {
       "type":"Patient",
       "profile":"https://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
     },
     {
       "type":"Organization",
       "profile":"https://hl7.org/fhir/us/core/StructureDefinition/us-core-organization"
     },
     ...
   ]
   

Carica la guida all'implementazione su Cloud Storage

Dopo aver modificato la guida all'implementazione, devi caricare i seguenti file in Cloud Storage:

• Guida all'implementazione
• Definizioni della struttura
• Set di valori

Dopo il caricamento, puoi utilizzare questi file per convalidare le risorse nell'archivio FHIR.

Per caricare la guida all'implementazione in Cloud Storage, completa i seguenti passaggi:

1. Elimina tutti i file della guida all'implementazione che non vengono utilizzati dai profili FHIR nell'API Cloud Healthcare.

   Ad esempio, se implementi la guida all'implementazione principale degli Stati Uniti, puoi eliminare i seguenti file:

   • .DS_Store
   • ig-r4.json
   • openapi/.index.json
   • package.json

2. Per aggiungere la guida all'implementazione, le definizioni della struttura e i set di valori a Cloud Storage, esegui i seguenti comandi:

   gcloud storage cp \
      PATH_TO_IMPLEMENTATION_GUIDE \
      gs://BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY \
      --recursive

   Sostituisci quanto segue:

   • PATH_TO_IMPLEMENTATION_GUIDE: il percorso della guida all'implementazione sul computer locale
   • BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY: il bucket e la directory in cui archiviare la guida all'implementazione in Cloud Storage

Importare la guida all'implementazione

Per utilizzare la guida all'implementazione per convalidare i profili nel tuo datastore FHIR, importala nel datastore FHIR come risorsa FHIR.

Gli esempi riportati di seguito mostrano come importare la guida all'implementazione in un archivio FHIR:

gcloud healthcare fhir-stores import gcs FHIR_STORE_ID \
  --dataset=DATASET_ID \
  --gcs-uri='gs://BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY/*' \
  --content-structure=resource-pretty

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

gcloud healthcare operations describe OPERATION_ID \
  --dataset=DATASET_ID

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'
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

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

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

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"

{
  "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",
  }
}

$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": "RESOURCE_PRETTY",
    "gcsSource": {
      "uri": "gs://BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY/*"
    }
  }' `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:import" | Select-Object -Expand Content

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

$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

{
  "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",
  }
}

Caricare e importare le dipendenze dell'implementazione

Prima di poter attivare la guida all'implementazione, devi assicurarti che tutte le dipendenze della guida siano caricate e importate. Le dipendenze sono definite dal parametro dependsOn nella guida all'implementazione come segue:

"dependsOn":[
  {
    "id":"hl7_fhir_uv_bulkdata",
    "uri":"http://hl7.org/fhir/uv/bulkdata/ImplementationGuide/hl7.fhir.uv.bulkdata",
    "packageId":"hl7.fhir.uv.bulkdata",
    "version":"1.0.1"
  },
  {
    "id":"vsac",
    "uri":"http://fhir.org/packages/us.nlm.vsac/ImplementationGuide/us.nlm.vsac",
    "packageId":"us.nlm.vsac",
    "version":"0.3.0"
  }
]

Per caricare e importare le dipendenze, segui le istruzioni riportate in Caricare la guida all'implementazione in Cloud Storage e Importare la guida all'implementazione.

Attiva la guida all'implementazione

Per utilizzare una risorsa della guida all'implementazione per convalidare i profili, devi abilitare la guida all'implementazione. Se abiliti più di una guida all'implementazione, l'API Cloud Healthcare tenta di convalidare i profili in base a tutte le guide all'implementazione. Una risorsa FHIR deve corrispondere a un solo profilo di qualsiasi guida all'implementazione abilitata.

L'API Cloud Healthcare convalida le guide all'implementazione solo quando le abiliti. Se modifichi una guida all'implementazione e la riattivi, l'API Cloud Healthcare convalida la guida all'implementazione modificata.

Se rimuovi una guida all'implementazione dopo averla attivata, la guida all'implementazione smette di avere effetto.

Gli esempi riportati di seguito mostrano come abilitare la guida all'implementazione per la convalida del profilo in un archivio FHIR esistente:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/fhir+json; charset=utf-8" \
    --data '{
      "validationConfig": {
          "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"],
          "disableProfileValidation": false
      }
    }' "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=validationConfig"

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "validationConfig": {
    "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"]
  }
}

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

Invoke-WebRequest `
  -Method Patch `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body '{
      "validationConfig": {
          "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"]
      }
  }' `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=validationConfig" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "validationConfig": {
    "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"],
  },
}

def enable_implementation_guide(
    project_id,
    location,
    dataset_id,
    fhir_store_id,
    implementation_guide_url,
):
    """
    Patches an existing FHIR store to enable an ImplementationGuide resource
    that exists in 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 dataset's location
    # dataset_id = 'my-dataset'  # replace with your dataset ID
    # fhir_store_id = 'my-fhir-store'  # replace with the FHIR store's ID
    # implementation_guide_url =
    # 'http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core'  #
    # replace with the 'url' property in the ImplementationGuide resource
    fhir_store_parent = "projects/{}/locations/{}/datasets/{}".format(
        project_id, location, dataset_id
    )
    fhir_store_name = f"{fhir_store_parent}/fhirStores/{fhir_store_id}"

    validation_config = {
        "validationConfig": {"enabledImplementationGuides": [implementation_guide_url]}
    }

    request = (
        client.projects()
        .locations()
        .datasets()
        .fhirStores()
        .patch(
            name=fhir_store_name, updateMask="validationConfig", body=validation_config
        )
    )

    response = request.execute()
    print(
        "Enabled ImplementationGuide with URL {} on FHIR store {}".format(
            implementation_guide_url, fhir_store_id
        )
    )

    return response

Utilizza la console Google Cloud per attivare le guide all'implementazione

Quando utilizzi la console Google Cloud per creare o modificare un archivio FHIR, puoi eseguire le seguenti operazioni:

• Seleziona le guide all'implementazione predefinite fornite dall'API Cloud Healthcare
• Importa una guida all'implementazione personalizzata da Cloud Storage nel tuo datastore FHIR

Per importare una guida all'implementazione personalizzata, completa i seguenti passaggi:

1. Scarica le risorse per la convalida del profilo.

2. (Facoltativo) Configura la guida all'implementazione.

   Questo passaggio è necessario per aggiungere manualmente l'array global alla risorsa della guida all'implementazione. Se scegli di saltare questo passaggio, devi aggiungere l'array global quando crei il bundle di transazioni FHIR nel passaggio successivo utilizzando un metodo diverso, ad esempio lo strumento Bundler per le risorse di convalida del profilo FHIR con il flag generate_global_array.

3. Crea un bundle di transazioni FHIR delle risorse di convalida del profilo, che includa la guida all'implementazione, le definizioni della struttura e i value set.

   Puoi creare il bundle di transazioni utilizzando lo strumento Bundler per le risorse di convalida del profilo FHIR.

4. Carica il bundle di convalida del profilo FHIR in una posizione Cloud Storage.

   gcloud storage cp \
      PATH_TO_PROFILE_VALIDATION_BUNDLE \
      gs://BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY \
      --recursive

   Sostituisci quanto segue:

   • PATH_TO_PROFILE_VALIDATION_BUNDLE: il percorso del bundle di convalida del profilo sulla macchina locale
   • BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY: la posizione Cloud Storage in cui deve essere archiviato il bundle

5. Importa la guida all'implementazione personalizzata dalla posizione Cloud Storage quando crei o modifichi l'archivio FHIR.

Convalidare le risorse rispetto a profili specifici

Gli esempi riportati di seguito mostrano come convalidare una risorsa FHIR per un profilo specifico o per tutti i profili definiti per un archivio FHIR. La convalida della risorsa FHIR ti consente di determinare se la risorsa FHIR è conforme a uno o più profili.

Per convalidare una risorsa FHIR, utilizza il metodo fhir.Resource-validate.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data @RESOURCE_FILE \
    'https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/$validate?profile=PROFILE_URL'

{
  "issue": [
    {
      "code": "informational",
      "details": {
        "text": "success"
      },
      "diagnostics": "success",
      "severity": "information"
    }
  ],
  "resourceType": "OperationOutcome"
}

{
    "issue": [
        {
            "code": "processing",
            "diagnostics": "Profile http://hl7.org/fhir/StructureDefinition/AuditEvent, Element 'AuditEvent.agent.requestor': minimum required = 1, but only found 0",
            "location": [
                "AuditEvent.agent"
            ],
            "severity": "error"
        }
    ],
    "resourceType": "OperationOutcome"
}

$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 '@RESOURCE_FILE' `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/$validate?profile=PROFILE_URL" | Select-Object -Expand Content

{
  "issue": [
    {
      "code": "informational",
      "details": {
        "text": "success"
      },
      "diagnostics": "success",
      "severity": "information"
    }
  ],
  "resourceType": "OperationOutcome"
}

{
    "issue": [
        {
            "code": "processing",
            "diagnostics": "Profile http://hl7.org/fhir/StructureDefinition/AuditEvent, Element 'AuditEvent.agent.requestor': minimum required = 1, but only found 0",
            "location": [
                "AuditEvent.agent"
            ],
            "severity": "error"
        }
    ],
    "resourceType": "OperationOutcome"
}

def validate_resource_profile_url(
    project_id, location, dataset_id, fhir_store_id, resource_type, profile_url
):
    """Validates an input FHIR resource's conformance to a profile URL. The
    profile StructureDefinition resource must exist in the FHIR store before
    performing validation against the URL.

    See https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/healthcare/api-client/v1/fhir
    before running the sample."""
    # Imports Python's built-in "os" module
    import os

    # Imports the google.auth.transport.requests transport
    from google.auth.transport import requests

    # Imports a module to allow authentication using a service account
    from google.oauth2 import service_account

    # Gets credentials from the environment.
    credentials = service_account.Credentials.from_service_account_file(
        os.environ["GOOGLE_APPLICATION_CREDENTIALS"]
    )
    scoped_credentials = credentials.with_scopes(
        ["https://www.googleapis.com/auth/cloud-platform"]
    )
    # Creates a requests Session object with the credentials.
    session = requests.AuthorizedSession(scoped_credentials)

    # URL to the Cloud Healthcare API endpoint and version
    base_url = "https://healthcare.googleapis.com/v1"

    # 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
    # resource_type = 'Patient'  # replace with the FHIR resource type
    # profile_url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient'  # replace with the profile URL
    url = f"{base_url}/projects/{project_id}/locations/{location}"

    resource_path = "{}/datasets/{}/fhirStores/{}/fhir/{}".format(
        url, dataset_id, fhir_store_id, resource_type
    )

    resource_path += "/$validate"
    params = {"profile": profile_url}

    # The body shown works with a Patient resource and is not guaranteed
    # to work with other types of FHIR resources. If necessary,
    # supply a new body with data that corresponds to the resource you
    # are validating and supply a new resource_type.
    body = {
        "name": [{"use": "official", "family": "Smith", "given": ["Darcy"]}],
        "gender": "female",
        "birthDate": "1970-01-01",
        "resourceType": "Patient",
    }

    # Sets required application/fhir+json header on the request
    headers = {"Content-Type": "application/fhir+json;charset=utf-8"}

    response = session.post(resource_path, headers=headers, json=body, params=params)
    response.raise_for_status()

    resource = response.json()

    print(json.dumps(resource))

    return resource