Diffuser les modifications de ressources FHIR dans BigQuery

Cette page explique comment configurer un datastore FHIR pour exporter automatiquement les ressources FHIR vers des tables BigQuery chaque fois qu'une ressource FHIR est créée, mise à jour, corrigée ou supprimée. Ce processus est appelé streaming BigQuery.

Vous pouvez utiliser le streaming BigQuery pour effectuer les opérations suivantes:

  • Synchronisez les données d'un magasin FHIR avec un ensemble de données BigQuery quasiment en temps réel.
  • Effectuez des requêtes complexes sur des données FHIR sans avoir à les exporter vers BigQuery chaque fois que vous souhaitez les analyser.

Pour améliorer les performances des requêtes et réduire les coûts, vous pouvez configurer le streaming BigQuery sur des tables partitionnées. Pour obtenir des instructions, consultez la section Diffuser des ressources FHIR dans des tables partitionnées.

Avant de commencer

Consultez Exporter des ressources FHIR vers BigQuery pour comprendre le fonctionnement du processus d'exportation.

Limites

Si vous importez des ressources FHIR à partir de Cloud Storage, les modifications ne sont pas diffusées dans BigQuery.

Définir des autorisations BigQuery

Pour activer la diffusion BigQuery, vous devez accorder des autorisations supplémentaires au compte de service Agent de service Cloud Healthcare. Pour en savoir plus, consultez la section Autorisations BigQuery pour les datastores FHIR.

Configurer le streaming BigQuery sur un magasin FHIR

Pour activer le streaming BigQuery, configurez l'objet StreamConfigs dans votre magasin FHIR. Dans StreamConfigs, vous pouvez configurer le tableau resourceTypes[] pour contrôler les types de ressources FHIR auxquels le streaming BigQuery s'applique. Si vous ne spécifiez pas resourceTypes[], le streaming BigQuery s'applique à tous les types de ressources FHIR.

Pour en savoir plus sur les autres configurations disponibles dans StreamConfigs, comme BigQueryDestination, consultez Exporter des ressources FHIR.

Les exemples suivants montrent comment activer le streaming BigQuery sur un datastore FHIR existant.

Console

Pour configurer le streaming BigQuery sur un magasin FHIR existant à l'aide de la console Google Cloud, procédez comme suit:

  1. Dans la console Google Cloud, accédez à la page Ensembles de données.

    Accéder à la page "Ensembles de données"

  2. Sélectionnez l'ensemble de données contenant le magasin FHIR que vous souhaitez modifier.

  3. Dans la liste Datastores (Datastores), cliquez sur le magasin FHIR que vous souhaitez modifier.

  4. Dans la section Diffusion BigQuery, procédez comme suit:

    1. Cliquez sur Ajouter une configuration de streaming.
    2. Dans la section Nouvelle configuration de streaming, cliquez sur Parcourir pour sélectionner l'ensemble de données BigQuery dans lequel vous souhaitez diffuser les ressources FHIR modifiées.
    3. Dans le menu déroulant Type de schéma, sélectionnez le schéma de sortie pour la table BigQuery. Les schémas suivants sont disponibles :
      • Analytics. Un schéma basé sur le document SQL sur FHIR. BigQuery n'autorisant que 10 000 colonnes par table, les schémas ne sont pas générés pour les champs Parameters.parameter.resource, Bundle.entry.resource et Bundle.entry.response.outcome.
      • Analytics V2 Un schéma semblable au schéma Analytics, avec les éléments suivants: Le schéma Analytics V2 utilise plus d'espace dans la table de destination que le schéma Analytics.
    4. Sélectionnez un niveau de profondeur dans le curseur Profondeur de la structure récursive pour définir la profondeur de toutes les structures récursives dans le schéma de sortie. Par défaut, la valeur récursive est 2.
    5. Dans la liste Sélectionner des types de ressources FHIR, sélectionnez les types de ressources à diffuser.

  5. Cliquez sur OK pour enregistrer la configuration de streaming.

gcloud

gcloud CLI n'est pas compatible avec cette action. Utilisez plutôt la console Google Cloud, curl, PowerShell ou le langage de votre choix.

REST

Pour configurer le streaming BigQuery sur un magasin FHIR existant, utilisez la méthode projects.locations.datasets.fhirStores.patch.

Les exemples suivants ne spécifient pas le tableau resourceTypes[]. Le streaming BigQuery est donc activé pour tous les types de ressources FHIR.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : emplacement de l'ensemble de données
  • DATASET_ID : ensemble de données parent du magasin FHIR.
  • FHIR_STORE_ID : ID du magasin FHIR.
  • BIGQUERY_DATASET_ID: nom d'un ensemble de données BigQuery existant dans lequel vous diffusez les modifications de ressources FHIR.
  • SCHEMA_TYPE : valeur pour l'énumération SchemaType. Utilisez l'une des valeurs suivantes :
    • ANALYTICS : schéma basé sur le document SQL sur FHIR. BigQuery n'autorisant que 10 000 colonnes par table, les schémas ne sont pas générés pour les champs Parameters.parameter.resource, Bundle.entry.resource et Bundle.entry.response.outcome.
    • ANALYTICS_V2 : schéma semblable à ANALYTICS, avec prise en charge des éléments suivants :

      ANALYTICS_V2 utilise plus d'espace dans la table de destination que ANALYTICS

      .
  • WRITE_DISPOSITION : valeur pour l'énumération WriteDisposition. Utilisez l'une des valeurs suivantes :
    • WRITE_EMPTY : n'exporter les données que si les tables BigQuery de destination sont vides
    • WRITE_TRUNCATE : effacez toutes les données existantes des tables BigQuery avant d'écrire les ressources FHIR.
    • WRITE_APPEND : ajoutez les données aux tables BigQuery de destination.

Corps JSON de la requête :

{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel : 

cat > request.json << 'EOF'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
EOF

Exécutez ensuite la commande suivante pour envoyer votre requête REST : 

curl -X PATCH \
     -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/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel : 

@'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Exécutez ensuite la commande suivante pour envoyer votre requête REST : 

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

Invoke-WebRequest `
    -Method PATCH `
    -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/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs" | Select-Object -Expand Content

API Explorer

Copiez le corps de la requête et ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Collez le corps de la requête dans cet outil, renseignez tous les champs obligatoires, puis cliquez sur Execute (Exécuter).

Vous devriez recevoir une réponse JSON semblable à la suivante.

Si vous avez configuré des champs dans la ressource FhirStore, ils apparaissent également dans la réponse.

Par défaut, lorsque vous diffusez des modifications de ressources FHIR vers BigQuery, une vue est créée pour chaque ressource diffusée. La vue possède les propriétés suivantes :

  • Il porte le même nom que la ressource et la table de la ressource dans l'ensemble de données BigQuery. Par exemple, lorsque vous lisez en streaming une ressource Patient, une table nommée Patient est créée avec une vue nommée Patientview.
  • Il ne contient que la version actuelle de la ressource, et non toutes les versions historiques.

Diffuser des ressources FHIR dans des tables partitionnées

Pour exporter des ressources FHIR vers des tables partitionnées BigQuery, définissez l'énumération TimePartitioning dans le champ lastUpdatedPartitionConfig de votre entrepôt FHIR.

Les tables partitionnées fonctionnent comme les tables partitionnées par unité de temps de BigQuery. Les tables partitionnées comportent une colonne nommée lastUpdated, qui est un double de la colonne meta.lastUpdated générée à partir du champ meta.lastUpdated dans une ressource FHIR. BigQuery utilise la colonne lastUpdated pour partitionner les tables par heure, jour, mois ou année.

Consultez la section Sélectionner le partitionnement quotidien, horaire, mensuel ou annuel pour obtenir des recommandations sur la sélection d'une précision de partitionnement.

Vous ne pouvez pas convertir des tables BigQuery existantes non partitionnées en tables partitionnées. Si vous exportez les modifications des ressources patient vers une table Patients non partitionnée, puis créez ultérieurement un magasin FHIR avec un partitionnement de table qui exporte vers le même ensemble de données BigQuery, l'API Cloud Healthcare continue d'exporter les données vers la table Patients non partitionnée. Pour commencer à utiliser une table partitionnée, supprimez la table Patients existante ou utilisez un autre ensemble de données BigQuery.

Si vous ajoutez un partitionnement à une configuration de magasin FHIR existante, vous pouvez toujours exporter vers des tables non partitionnées existantes. Toutefois, le partitionnement ne s'applique qu'aux nouvelles tables.

Les exemples suivants montrent comment activer la diffusion BigQuery vers des tables partitionnées sur un datastore FHIR existant.

Console

La console Google Cloud et gcloud CLI ne permettent pas d'effectuer cette opération. Utilisez plutôt curl, PowerShell ou le langage de votre choix.

gcloud

La console Google Cloud et gcloud CLI ne permettent pas d'effectuer cette opération. Utilisez plutôt curl, PowerShell ou le langage de votre choix.

REST

Pour configurer le streaming BigQuery vers des tables partitionnées sur un magasin FHIR existant, utilisez la méthode projects.locations.datasets.fhirStores.patch.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : emplacement de l'ensemble de données
  • DATASET_ID : ensemble de données parent du magasin FHIR.
  • FHIR_STORE_ID : ID du magasin FHIR.
  • BIGQUERY_DATASET_ID: nom d'un ensemble de données BigQuery existant dans lequel vous diffusez les modifications de ressources FHIR.
  • SCHEMA_TYPE : valeur pour l'énumération SchemaType. Utilisez l'une des valeurs suivantes :
    • ANALYTICS : schéma basé sur le document SQL sur FHIR. BigQuery n'autorisant que 10 000 colonnes par table, les schémas ne sont pas générés pour les champs Parameters.parameter.resource, Bundle.entry.resource et Bundle.entry.response.outcome.
    • ANALYTICS_V2 : schéma semblable à ANALYTICS, avec prise en charge des éléments suivants :

      ANALYTICS_V2 utilise plus d'espace dans la table de destination que ANALYTICS

      .
  • TIME_PARTITION_TYPE: niveau de précision à utiliser pour partitionner les ressources FHIR exportées. Utilisez l'une des valeurs suivantes :
    • HOUR: partitionner les données par heure
    • DAY: partitionner les données par jour
    • MONTH: partitionner les données par mois
    • YEAR: partitionne les données par année.
  • WRITE_DISPOSITION : valeur pour l'énumération WriteDisposition. Utilisez l'une des valeurs suivantes :
    • WRITE_EMPTY : n'exporter les données que si les tables BigQuery de destination sont vides
    • WRITE_TRUNCATE : effacez toutes les données existantes des tables BigQuery avant d'écrire les ressources FHIR.
    • WRITE_APPEND : ajoutez les données aux tables BigQuery de destination.

Corps JSON de la requête :

{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel : 

cat > request.json << 'EOF'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
EOF

Exécutez ensuite la commande suivante pour envoyer votre requête REST : 

curl -X PATCH \
     -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/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel : 

@'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Exécutez ensuite la commande suivante pour envoyer votre requête REST : 

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

Invoke-WebRequest `
    -Method PATCH `
    -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/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs" | Select-Object -Expand Content

API Explorer

Copiez le corps de la requête et ouvrez la page de référence de la méthode. Le panneau APIs Explorer s'ouvre dans la partie droite de la page. Vous pouvez interagir avec cet outil pour envoyer des requêtes. Collez le corps de la requête dans cet outil, renseignez tous les champs obligatoires, puis cliquez sur Execute (Exécuter).

Vous devriez recevoir une réponse JSON de ce type :

Interroger une table partitionnée

Pour réduire les coûts des requêtes lorsque vous interrogez des tables partitionnées, utilisez la clause WHERE pour filtrer par unités de temps.

Par exemple, supposons que vous définissiez l'énumération PartitionType sur DAY. Pour interroger une table Patients sur les ressources Patient qui ont changé à une date spécifique, exécutez la requête suivante:

SELECT * FROM `PROJECT_ID.BIGQUERY_DATASET.Patients`
  WHERE DATE(lastUpdated) = 'YYYY-MM-DD'

Migrer d'Analytics vers Analytics V2

Vous ne pouvez pas migrer un ensemble de données BigQuery existant du schéma Analytics vers le schéma Analytics V2 à l'aide d'une méthode quelconque, y compris les suivantes:

  • Modifier le type de schéma de la table dans BigQuery.
  • Modification du type de schéma dans une configuration de streaming FHIR existante.

En effet, le mode des colonnes de table BigQuery pour les extensions FHIR dans le schéma Analytics est défini sur NULLABLE, tandis que celui des colonnes du schéma Analytics V2 est défini sur REPEATED. BigQuery ne permet pas de passer d'un mode NULLABLE à un mode REPEATED pour une colonne. Par conséquent, les deux types de schémas sont incompatibles.

Pour migrer le type de schéma des ressources FHIR exportées de Analytics vers Analytics V2, vous devez exporter les ressources FHIR vers un nouvel ensemble de données BigQuery à l'aide d'une nouvelle configuration de streaming avec le type de schéma mis à jour. Pour ce faire, procédez comme suit:

  1. Créez un ensemble de données BigQuery.

  2. Définissez les autorisations pour l'ensemble de données BigQuery.

  3. Ajoutez une configuration de streaming au magasin FHIR avec le type de schéma défini sur Analytics V2.

  4. Remplacez les données existantes en exportant les données FHIR existantes à l'aide des paramètres suivants. Consultez Exporter des ressources FHIR pour savoir comment configurer ces paramètres à l'aide de la console Google Cloud, de la Google Cloud CLI ou de l'API REST. Les paramètres suivants s'appliquent à l'API REST:

Les vues dans BigQuery qui correspondent à certaines ou à toutes les ressources FHIR de l'ensemble de données BigQuery d'origine peuvent être manquantes dans votre nouvel ensemble de données. Pour résoudre ce problème, consultez la section Création de la vue de ressources FHIR manquante.

Résoudre les problèmes liés au streaming FHIR

Si des erreurs se produisent lorsque des modifications de ressources sont envoyées à BigQuery, elles sont consignées dans Cloud Logging. Pour en savoir plus, consultez la section Afficher les journaux d'erreurs dans Cloud Logging.

Impossible de convertir une colonne du mode NULLABLE au mode REPEATED

Cette erreur est due à une extension répétée. Pour résoudre cette erreur, utilisez le type de schéma ANALYTICS_V2. Si vous utilisez déjà ANALYTICS_V2, il est possible qu'il y ait un conflit entre deux extensions ou entre une extension et un autre champ.

Les noms de colonnes sont générés à partir du texte qui suit le dernier caractère / dans les URL d'extension. Si une URL d'extension se termine par une valeur telle que /resource_field name, un conflit peut se produire.

Pour éviter que cette erreur ne se reproduise, n'utilisez pas d'extensions si leurs noms de champ sont identiques à ceux des champs de ressources que vous renseignez.

Création de la vue de ressources FHIR manquante

Si vous exportez de manière groupée une ressource FHIR vers BigQuery avant de la diffuser, BigQuery ne crée pas de vues pour la ressource FHIR.

Par exemple, vous ne verrez peut-être aucune vue pour les ressources Encounter dans la situation suivante :

  1. Configurez le streaming sur un magasin FHIR dans BigQuery, puis utilisez l'API REST pour créer une ressource Patient.

    BigQuery crée une table et une vue pour la ressource Patient.

  2. Exportez des ressources Encounter de manière groupée vers le même ensemble de données BigQuery qu'à l'étape précédente.

    BigQuery crée une table pour les ressources Encounter.

  3. Vous utilisez l'API REST pour créer une ressource Encounter.

    Après cette étape, les vues BigQuery ne sont pas créées pour la ressource Encounter.

Pour résoudre ce problème, utilisez la requête suivante pour créer une vue :

SELECT
    * EXCEPT (_resource_row_id)
FROM (
  SELECT
    ROW_NUMBER() OVER(PARTITION BY id ORDER BY meta.lastUpdated DESC, commitTimestamp DESC) as _resource_row_id,
    *
    FROM `PROJECT_ID.BIGQUERY_DATASET_ID.RESOURCE_TABLE` AS p
) AS p
WHERE
  p._resource_row_id=1
  AND
  NOT EXISTS (
  SELECT
    *
  FROM
    UNNEST(p.meta.tag)
  WHERE
    code = 'DELETE');

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • BIGQUERY_DATASET_ID : ID de l'ensemble de données BigQuery dans lequel vous avez exporté la ressource FHIR de manière groupée
  • RESOURCE_TABLE : nom de la table correspondant à la ressource FHIR pour laquelle vous souhaitez créer des vues

Après avoir créé la vue, vous pouvez continuer à diffuser les modifications vers la ressource FHIR et la vue est mise à jour en conséquence.

Étapes suivantes

Pour obtenir un tutoriel de cas d'utilisation sur la diffusion de modifications de ressources FHIR, consultez la page Diffuser et synchroniser des ressources FHIR avec BigQuery.