Récupérer des ressources FHIR avec la récupération à un moment précis (PITR)

Cette page explique comment utiliser la récupération à un moment précis (PITR) pour restaurer des ressources FHIR dans un magasin FHIR à un état datant des 21 derniers jours. Vous pouvez utiliser la récupération PITR pour annuler des modifications indésirables, comme la suppression accidentelle de ressources FHIR.

Avant de commencer

Les demandes de récupération à un instant donné sont classées comme des demandes d'opérations avancées et sont facturées en conséquence. Avant d'utiliser la récupération PITR, consultez la tarification des requêtes d'opération avancée.

PITR et historique des versions des ressources FHIR

La récupération PITR ne dépend pas de l'historique des versions des ressources FHIR. Vous pouvez toujours utiliser la récupération à un moment précis si le champ disableResourceVersioning d'un magasin FHIR est défini sur true ou si les versions historiques d'une ressource FHIR ont été supprimées.

Workflow de récupération

Pour vous assurer qu'une récupération de production s'exécute comme prévu, effectuez d'abord une simulation. L'exécution à blanc génère un ou plusieurs fichiers contenant les ID et les types de ressources FHIR à récupérer. Vérifiez l'exactitude des fichiers de sortie avant de relancer la récupération en production.

Pour récupérer des ressources spécifiques ou des ressources selon un critère de filtrage, spécifiez un filtre.

Effectuer une simulation

Avant de récupérer des ressources FHIR en production, effectuez un dry run.

Les exemples suivants montrent comment effectuer un test à blanc à l'aide de la méthode fhirStores.rollback.

REST

  1. Récupérez les ressources FHIR.

    Pour effectuer une simulation, assurez-vous que le champ force est défini sur false.

    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.
    • RECOVERY_TIMESTAMP : point de récupération au cours des 21 derniers jours. Utilisez le format RFC 3339. Spécifiez l'heure à la seconde près et incluez un fuseau horaire, par exemple 2015-02-07T13:28:17.239+02:00 ou 2017-01-01T00:00:00Z.
    • CLOUD_STORAGE_BUCKET : URI complet d'un dossier ou d'un bucket Cloud Storage dans lequel les fichiers de sortie sont écrits.

    Corps JSON de la requête :

    {
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}

    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'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}
EOF

    Exécutez ensuite la commande suivante pour envoyer votre requête 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/fhirStores/FHIR_STORE_ID:rollback"

    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 : 

    @'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}
'@  | 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 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/fhirStores/FHIR_STORE_ID:rollback" | Select-Object -Expand Content

    Explorateur d'API

    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).

    Le résultat est le suivant. La réponse contient un identifiant pour une opération de longue durée (LRO). Les opérations de longue durée sont renvoyées lorsque les appels de méthode peuvent prendre davantage de temps. Notez la valeur de OPERATION_ID. Vous en aurez besoin à l'étape suivante.

  2. Utilisez la méthode projects.locations.datasets.operations.get pour obtenir l'état de l'opération de longue durée.

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

    • PROJECT_ID : ID de votre projet Google Cloud
    • DATASET_ID : ID de l'ensemble de données
    • LOCATION : emplacement de l'ensemble de données
    • OPERATION_ID : ID renvoyé par l'opération de longue durée

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

    curl

    Exécutez la commande suivante :

    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"

    PowerShell

    Exécutez la commande suivante :

    $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

    Explorateur d'API

    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. Renseignez tous les champs obligatoires, puis cliquez sur Execute (Exécuter).

    Le résultat est le suivant. Lorsque la réponse contient "done": true, l'opération de longue durée est terminée.

Afficher les fichiers de sortie de la simulation

Chaque simulation génère un ou plusieurs fichiers contenant les ID et les types de ressources FHIR à récupérer. Les fichiers sont créés dans un sous-dossier du dossier rollback_resources du bucket Cloud Storage de destination. Le nom du sous-dossier correspond à l'ID LRO renvoyé dans la réponse fhirStores.rollback. Pour afficher les fichiers et vous assurer que la récupération fonctionne comme prévu, consultez Afficher les métadonnées d'objets.

Le nombre de fichiers est proportionnel au nombre de ressources FHIR récupérées.

Les noms de fichiers utilisent le format trial-NUMBER-of-TOTAL_NUMBER.txt, où NUMBER est le numéro du fichier et TOTAL_NUMBER le nombre total de fichiers.

Schéma du fichier de sortie de la simulation

Les fichiers de sortie d'une récupération à blanc utilisent le schéma indiqué dans le tableau suivant :

RESOURCE_TYPE RESOURCE_ID TIMESTAMP
Type de ressource FHIR. ID de la ressource FHIR. Heure à laquelle la ressource FHIR a été créée ou mise à jour dans le magasin FHIR.

Récupérer en production

Avant de procéder à la récupération en production, effectuez un test à blanc et inspectez les fichiers de sortie du test à blanc pour vous assurer que la récupération en production se déroule comme prévu.

Les exemples suivants montrent comment restaurer des ressources FHIR en production à l'aide de la méthode fhirStores.rollback.

REST

  1. Récupérez les ressources FHIR.

    Assurez-vous que le champ force est défini sur true.

    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.
    • RECOVERY_TIMESTAMP : point de récupération au cours des 21 derniers jours. Utilisez le format RFC 3339. Spécifiez l'heure à la seconde près et incluez un fuseau horaire, par exemple 2015-02-07T13:28:17.239+02:00 ou 2017-01-01T00:00:00Z.
    • CLOUD_STORAGE_BUCKET : URI complet d'un dossier ou d'un bucket Cloud Storage dans lequel les fichiers de sortie sont écrits.

    Corps JSON de la requête :

    {
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}

    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'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}
EOF

    Exécutez ensuite la commande suivante pour envoyer votre requête 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/fhirStores/FHIR_STORE_ID:rollback"

    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 : 

    @'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}
'@  | 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 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/fhirStores/FHIR_STORE_ID:rollback" | Select-Object -Expand Content

    Explorateur d'API

    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).

    Le résultat est le suivant. La réponse contient un identifiant pour une opération de longue durée (LRO). Les opérations de longue durée sont renvoyées lorsque les appels de méthode peuvent prendre davantage de temps. Notez la valeur de OPERATION_ID. Vous en aurez besoin à l'étape suivante.

  2. Utilisez la méthode projects.locations.datasets.operations.get pour obtenir l'état de l'opération de longue durée.

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

    • PROJECT_ID : ID de votre projet Google Cloud
    • DATASET_ID : ID de l'ensemble de données
    • LOCATION : emplacement de l'ensemble de données
    • OPERATION_ID : ID renvoyé par l'opération de longue durée

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

    curl

    Exécutez la commande suivante :

    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"

    PowerShell

    Exécutez la commande suivante :

    $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

    Explorateur d'API

    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. Renseignez tous les champs obligatoires, puis cliquez sur Execute (Exécuter).

    Le résultat est le suivant. Lorsque la réponse contient "done": true, l'opération de longue durée est terminée.

Afficher les fichiers de sortie de la récupération de la production

Une récupération de la production génère les fichiers suivants. Les fichiers sont créés dans un sous-dossier du dossier rollback_resources du bucket Cloud Storage de destination. Le nom du sous-dossier correspond à l'ID LRO renvoyé dans la réponse fhirStores.rollback. Pour afficher les fichiers, consultez Afficher les métadonnées d'objets.

  • success-NUMBER-of-TOTAL_NUMBER.txt : contient les ressources FHIR récupérées.
  • fail-NUMBER-of-TOTAL_NUMBER.txt : contient les ressources FHIR qui n'ont pas pu être récupérées. Un fichier vide est généré même en l'absence d'échecs.

Dans les noms de fichiers, NUMBER correspond au numéro du fichier et TOTAL_NUMBER au nombre total de fichiers.

Schéma du fichier de sortie de production

Les fichiers de réussite et d'échec d'une récupération de production utilisent le schéma suivant. Les fichiers d'erreurs contiennent une colonne ERROR_MESSAGE supplémentaire.

RESOURCE_TYPE RESOURCE_ID ROLLBACK_VERSION_ID NEW_VERSION_ID ERROR_MESSAGE (Fichiers d'erreur uniquement)
Type de ressource FHIR. ID de la ressource FHIR. ID de version actuel de la ressource au moment où la récupération a commencé. ID de version actuel de la ressource après la récupération. Si disableResourceVersioning est défini sur true ou si la récupération d'une ressource entraînerait sa suppression, ROLLBACK_VERSION_ID et NEW_VERSION_ID sont vides. Fichiers d'erreur uniquement. Décrit pourquoi la ressource FHIR n'a pas pu être récupérée.

Utiliser des filtres pour récupérer des ressources FHIR spécifiques

Les sections suivantes décrivent comment utiliser des filtres pour récupérer des ressources FHIR en fonction de critères de filtrage. Vous spécifiez les filtres dans l'objet RollbackFhirResourceFilteringFields lorsque vous envoyez une requête fhirStores.rollback.

Vous pouvez combiner des filtres ou les utiliser individuellement pour plusieurs cas d'utilisation, y compris les suivants :

  • Récupérer des ressources FHIR spécifiques après une suppression accidentelle, tout en laissant les autres inchangées.
  • Restaurez un magasin FHIR dans un état antérieur à une opération d'importation spécifique qui a importé certaines ressources FHIR.

Utiliser un fichier de filtres

Par défaut, la récupération PITR restaure toutes les ressources FHIR d'un magasin FHIR. Pour récupérer des ressources FHIR spécifiques, spécifiez les types de ressources et leurs ID de ressources dans un fichier, puis importez le fichier dans Cloud Storage. Spécifiez l'emplacement du fichier dans le champ inputGcsObject.

Pour lire un fichier de filtres depuis Cloud Storage, vous devez accorder des autorisations au compte de service Agent de service Cloud Healthcare. Pour en savoir plus, consultez Lire des fichiers de filtres depuis Cloud Storage.

Le fichier de filtres peut avoir n'importe quelle extension. Il doit utiliser le schéma suivant, avec une ressource FHIR par ligne :

FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID

Par exemple, pour récupérer une ressource Patient avec l'ID 8f25b0ac et deux ressources Observation avec les ID d507417e90e et e9950d90e, spécifiez les éléments suivants dans le fichier de filtre :

Patient/8f25b0ac
Observation/d507417e90e
Observation/e9950d90e

Utiliser des fonctions personnalisées

L'API Cloud Healthcare fournit les fonctions de filtrage personnalisées suivantes. Vous pouvez combiner les fonctions personnalisées avec le champ rollbackTime pour appliquer un filtre supplémentaire.

tag
Détails
Syntaxe des fonctions
tag("system") = "code"
Description
Filtre les ressources FHIR en fonction de l'élément Meta.tag de la ressource.
Arguments
system
string
URL qui fait référence à un système de codes. Pour en savoir plus, consultez Utiliser des codes dans les ressources.
code
string
Valeur qui identifie un concept tel que défini par le système de code. Pour en savoir plus, consultez Utiliser des codes dans les ressources.
extension_value_ts
Détails
Syntaxe des fonctions
extension_value_ts("url")
Description
Filtre les ressources FHIR en fonction de la valeur url dans un élément extension où url est un code temporel Unix. Accepte les opérateurs de comparaison suivants :
  • =
  • !=
  • <
  • >
  • <=
  • >=
Arguments
url
string
URL canonique d'une ressource StructureDefinition qui définit une extension. Par exemple, dans l'élément extension suivant, url est http://hl7.org/fhir/StructureDefinition/timezone : 
"extension" : [{
  "url" : "http://hl7.org/fhir/StructureDefinition/timezone",
  "valueCode" : "America/New_York"
}]
Pour en savoir plus, consultez Définir des extensions.

Filtrer par type de ressource FHIR

Pour filtrer les ressources FHIR de manière plus générale en fonction uniquement du type de ressource, spécifiez les types de ressources dans le tableau types[].

Filtrer par type d'opération

Pour filtrer les ressources FHIR qui ont été modifiées par une transaction CREATE, UPDATE ou DELETE, spécifiez une valeur dans l'énumération ChangeType.

Par exemple, pour ne récupérer que les ressources FHIR qui ont été supprimées, spécifiez la valeur DELETE.

Si vous spécifiez CHANGE_TYPE_UNSPECIFIED ou ALL, ou si vous ne spécifiez aucune valeur, toutes les ressources FHIR sont récupérées.

Exclure les récupérations précédentes

Pour exclure les récupérations précédentes lors de la récupération de ressources FHIR, définissez le champ excludeRollbacks sur true. Vous pouvez exclure les récupérations précédentes si elles ont fonctionné correctement et que vous ne souhaitez pas écraser leurs modifications. Vous pouvez également effectuer plusieurs récupérations avec des codes temporels qui se chevauchent.

Imaginez le scénario suivant :

  1. À 1:00, vous lancez une récupération avec le code temporel de récupération défini sur 0:01. À 2:00, l'opération de récupération supprime les ressources Patient Patient/1 et Patient/2 du magasin FHIR. L'opération de récupération se termine à 3:00.

  2. Quelques jours plus tard, vous exécutez une opération de récupération avec le code temporel de récupération défini sur 1:00. Par défaut, l'exécution de l'opération entraînerait les résultats suivants :

    • Recréation incorrecte des ressources Patient Patient/1 et Patient/2.
    • Récupérer correctement les ressources FHIR créées ou mises à jour après 3:00.

Pour exclure l'opération de récupération initiale qui a supprimé les ressources patient Patient/1 et Patient/2, et éviter de les recréer, définissez excludeRollbacks sur true.

Filtrer à l'aide des ID d'opération de longue durée (LRO)

Si des ressources FHIR ont été modifiées par une ou plusieurs opérations de longue durée (OLD), vous pouvez spécifier les ID des OLD dans le champ operationIds pour récupérer les ressources modifiées.

Pour savoir comment lister et afficher les ID d'opérations de longue durée dans un ensemble de données de l'API Cloud Healthcare, consultez Lister les opérations de longue durée.

Réessayer de récupérer les ressources FHIR qui n'ont pas pu l'être en production

Si la récupération de certains éléments FHIR en production a échoué, vous pouvez réessayer. Utilisez le fichier de sortie de production généré pour trouver les ressources FHIR qui ont échoué. Spécifiez les types de ces ressources FHIR et leurs ID dans un fichier de filtre, puis exécutez à nouveau la récupération.

Chaque fois que vous exécutez une récupération, elle est idempotente si vous utilisez la même configuration dans chaque requête et si le code temporel date de moins de 21 jours.

Limites

  • La restauration à un instant donné n'applique pas l'intégrité référentielle, quel que soit le paramètre disableReferentialIntegrity défini sur le magasin FHIR. Si vous ne restaurez que certaines ressources FHIR, le magasin FHIR peut se retrouver dans un état qui viole l'intégrité référentielle.

  • La récupération à un moment précis ignore la validation du profil FHIR, car les ressources FHIR restaurées ont été validées lors de leur création ou de leur mise à jour. Si la configuration du profil du magasin FHIR a changé, la PITR peut laisser le magasin FHIR dans un état qui ne respecte pas la validation du profil.

  • Si la valeur de rollbackTime précède le moment où une ressource FHIR a été supprimée dans le magasin FHIR, la enableUpdateCreate doit être activée dans le magasin FHIR, sinon la ressource ne sera pas récupérée.

  • Vous pouvez mettre à jour un magasin FHIR ou lire et écrire des données pendant une récupération, mais vous pouvez obtenir des résultats inattendus en fonction de l'étape de récupération. Par exemple, une requête de lecture peut renvoyer une combinaison de ressources FHIR récupérées et non récupérées. Si vous mettez à jour une ressource, la récupération peut écraser la mise à jour.

  • La récupération à un instant donné conserve l'historique des ressources FHIR. Chaque ressource restaurée obtient une nouvelle version actuelle et son historique est conservé.