Cette page explique comment utiliser la méthode projects.locations.datasets.fhirStores.fhir.search
pour rechercher des ressources dans un datastore FHIR donné. Vous pouvez appeler la méthode de différentes manières à l'aide de requêtes GET
ou POST
. La spécification de recherche FHIR comprend un large éventail de fonctionnalités de requête. Cette page présente un aperçu des nombreuses fonctionnalités couramment utilisées, mais ne constitue pas une liste exhaustive des parties des spécifications de recherche compatibles avec l'API Cloud Healthcare.
Utiliser la méthode search
avec GET
Les exemples suivants montrent comment rechercher des ressources dans un datastore FHIR donné à l'aide de la méthode projects.locations.datasets.fhirStores.fhir.search
avec GET
.
curl
Pour rechercher des ressources dans un datastore FHIR, envoyez une requête GET
et spécifiez les informations suivantes :
- Le nom de l'ensemble de données
- Le nom du datastore FHIR
- Le type de ressource à rechercher
- Une chaîne de requête contenant les informations que vous recherchez, comme décrit dans la section Créer une requête de recherche
- Un jeton d'accès
L'exemple suivant montre une requête GET
utilisant curl
pour rechercher tous les patients portant le nom de famille "Smith".
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/fhirStores/FHIR_STORE_ID/fhir/Patient?family:exact=Smith"
Si la requête aboutit, le serveur renvoie la réponse en tant que Bundle
FHIR au format JSON. Le Bundle.type
est searchset
et les résultats de recherche sont des entrées du tableau Bundle.entry
. Dans cet exemple, la requête renvoie une seule ressource "Patient" incluant les données qu'elle contient :
{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
PowerShell
Pour rechercher des ressources dans un datastore FHIR, envoyez une requête GET
et spécifiez les informations suivantes :
- Le nom de l'ensemble de données
- Le nom du datastore FHIR
- Le type de ressource à rechercher
- Une chaîne de requête contenant les informations que vous recherchez, comme décrit dans la section Créer une requête de recherche
- Un jeton d'accès
L'exemple suivant montre une requête GET
utilisant Windows PowerShell pour rechercher tous les patients portant le nom de famille "Smith".
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Get ` -Headers $headers ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE?family:exact=Smith" | ConvertTo-Json
Si la requête aboutit, le serveur renvoie la réponse en tant que Bundle
FHIR au format JSON. Le Bundle.type
est searchset
et les résultats de recherche sont des entrées du tableau Bundle.entry
. Dans cet exemple, la requête renvoie une seule ressource "Patient" incluant les données qu'elle contient :
{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
Java
Node.js
Python
Utiliser la méthode search
avec POST
Les exemples suivants montrent comment rechercher des ressources dans un datastore FHIR donné à l'aide de la méthode projects.locations.datasets.fhirStores.fhir.search
avec POST
.
curl
Pour rechercher des ressources dans un datastore FHIR, envoyez une requête POST
et spécifiez les informations suivantes :
- Le nom de l'ensemble de données
- Le nom du datastore FHIR
- Le type de ressource à rechercher
- Une chaîne de requête contenant les informations que vous recherchez, comme décrit dans la section Créer une requête de recherche
- Un jeton d'accès
L'exemple suivant montre une requête POST
utilisant curl
pour rechercher tous les patients portant le nom de famille "Smith".
curl -X POST \ --data "" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/fhir+json; charset=utf-8" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/_search?family:exact=Smith"
Si la requête aboutit, le serveur renvoie la réponse en tant que Bundle
FHIR au format JSON. Le Bundle.type
est searchset
et les résultats de recherche sont des entrées du tableau Bundle.entry
. Dans cet exemple, la requête renvoie une seule ressource "Patient" incluant les données qu'elle contient :
{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
PowerShell
Pour rechercher des ressources dans un datastore FHIR, envoyez une requête POST
et spécifiez les informations suivantes :
- Le nom de l'ensemble de données
- Le nom du datastore FHIR
- Le type de ressource à rechercher
- Une chaîne de requête contenant les informations que vous recherchez, comme décrit dans la section Créer une requête de recherche
- Un jeton d'accès
L'exemple suivant montre une requête POST
utilisant Windows PowerShell pour rechercher tous les patients portant le nom de famille "Smith".
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json; charset=utf-8" ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/_search?family:exact=Smith" | ConvertTo-Json
Si la requête aboutit, le serveur renvoie la réponse en tant que Bundle
FHIR au format JSON. Le Bundle.type
est searchset
et les résultats de recherche sont des entrées du tableau Bundle.entry
. Dans cet exemple, la requête renvoie une seule ressource "Patient" incluant les données qu'elle contient :
{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
Java
Node.js
Python
Créer une requête de recherche
La chaîne de requête est une série de paires name=value
encodées sous forme d'URL. Une recherche combine toutes les paires à l'aide d'un AND
logique. Chaque valeur peut être une liste de valeurs séparées par des virgules, qui sont traitées comme un OR
logique de ces valeurs. Exemple :
Patient?key1=value1&key2=value2,value3
correspond à une recherche sur des ressources Patient
selon les critères suivants :
(key1 = value1) AND (key2 = value2 OR key2 = value3)
Il n'existe pas de syntaxe permettant d'effectuer un OR de deux paires nom=valeur.
Chaque type de ressource FHIR définit ses propres paramètres de recherche dans chaque version de FHIR. Les paramètres disponibles sont documentés dans la spécification FHIR de chaque ressource, par exemple FHIR R4 Patient, et peuvent être récupérés de manière automatisée via la déclaration de capacités. L'API Cloud Healthcare accepte la plupart des paramètres de recherche. Les exclusions sont disponibles via la déclaration de capacités ou la déclaration de conformité FHIR.
Pagination et tri
Le nombre maximal de ressources renvoyées par la méthode de recherche est contrôlé par le paramètre _count
. Par exemple, _count=10
renvoie au maximum 10 ressources correspondant à la requête. La valeur par défaut est 100 et la valeur maximale autorisée est 1 000.
Si la recherche renvoie un nombre de ressources supérieur à une page, la réponse inclut une URL de pagination dans le champ Bundle.link
. Ce champ peut contenir plusieurs valeurs. La valeur Bundle.link.relation = next
indique que la valeur Bundle.link.url
correspondant peut être utilisée pour récupérer la page suivante. La valeur Bundle.total
indique le nombre total de ressources correspondantes. Cette valeur est exacte si les résultats tiennent entièrement sur une page ; elle est approximative lorsque le nombre de résultats devient beaucoup dépasse largement une page. Pour un grand nombre de résultats, le nombre total exact de ressources correspondantes ne peut être obtenu qu'en suivant les liens de pagination à plusieurs reprises, jusqu'à ce que les résultats soient épuisés.
Les résultats peuvent être triés à l'aide du paramètre _sort
, qui accepte une liste de noms de paramètres de recherche séparés par des virgules par ordre de priorité, éventuellement avec un préfixe -
pour indiquer un ordre décroissant. Exemple :
_sort=status,-date,category
trie par ordre croissant, départage les égalités par date décroissante et les égalités restantes par ordre de catégorie croissant.
Délai d'indexation
Les ressources FHIR sont indexées de manière asynchrone. Il peut donc s'écouler quelques instants entre le moment où une ressource est créée ou modifiée et le moment où elle apparaît dans les résultats de recherche.
Rechercher dans tous les types de ressources
Certains paramètres de recherche, signalés par un trait de soulignement tel que _id
, s'appliquent à tous les types de ressources. Ces paramètres "toutes les ressources" sont répertoriés dans la spécification FHIR pour le type Resource
.
Lorsque vous utilisez ces paramètres de recherche, vous pouvez effectuer une recherche sur plusieurs types de ressources en omettant le type de ressource dans le chemin de la requête. Par exemple, GET .../fhir?_id=1234
recherche dans toutes les ressources, alors que GET .../fhir/Patient?_id=1234
ne recherche que dans les ressources "Patient". Le paramètre spécial _type
peut être utilisé avec ce type de requête pour limiter les résultats à une liste de types de ressources séparés par des virgules, par exemple :
GET .../fhir?_tag=active&_type=Observation,Condition
renvoie uniquement les résultats correspondants pour les ressources Observation
et Condition
.
Types de données
Chaque paramètre de recherche défini par FHIR possède un type de données, qui inclut des types primitifs tels que chaîne, nombre et date, ainsi que des types complexes tels que jeton, référence et quantité. Chaque type de données possède sa propre syntaxe pour spécifier des valeurs et accepte des modificateurs qui modifient la façon dont la recherche est effectuée.
Voici quelques exemples simples d'utilisation des types de données :
- Nombre recherche sur des valeurs entières ou à virgule flottante. La valeur peut être précédée d'un modificateur tel que
ne, lt, le, gt, ge
pour modifier le comparatif, par exemple[parameter]=100
pour égalité,[parameter]=ge100
pour supérieur ou égal à 100. - Date recherche sur n'importe quel type de date, d'heure ou de période. Le format du paramètre de date est
yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm]
, et les mêmes modificateurs de préfixe utilisés pour le nombre s'appliquent également ici. - Chaîne utilise par défaut une recherche de préfixe non sensible à la casse et aux accents ou autres signes diacritiques.
- Jeton recherche une correspondance exacte de chaîne d'un "code", éventuellement limitée à l'URI d'un "système", indiquant que la valeur de code définie est issue du format
[parameter]=[system]|[code]
. Par exemple,code=http://hl7.org/fhir/ValueSet/observation-codes|10738-3
correspond à un code compris entre 10 738 et 3, mais seulement lorsqu'il est considéré comme une valeur d'un système de codage avec l'URI spécifié. - Quantité recherche une valeur numérique à l'aide des mêmes modificateurs de préfixe qu'un nombre, éventuellement qualifiée avec un système et un code spécifiques indiquant les unités de la valeur au format
[parameter]=[prefix][number]|[system]|[code]
. Par exemple,value-quantity=lt9.1|http://unitsofmeasure.org|mg
recherche des valeurs de quantité inférieures à 9,1 avec le système d'unités et le code spécifiés. - Référence recherche des références parmi les ressources, qui peuvent être spécifiées par
[parameter]=[id]
ou[parameter]=[type]/[id]
pour les références à des ressources présentes dans le datastore FHIR, ou par[parameter]=[url]
pour des références par URL pouvant se trouver en dehors du datastore FHIR.
Pour en savoir plus sur les autres types de données, les syntaxes de valeur et les modificateurs, consultez la page Fonctionnalités de recherche FHIR avancées.
Gestion des paramètres de recherche
Par défaut, la méthode de recherche applique un traitement "indulgent" qui ignore les paramètres qu'elle ne reconnaît pas et effectue la recherche à l'aide des paramètres de requête restants, ce qui peut renvoyer plus de ressources que prévu.
La réponse inclut une valeur dans Bundle.link
avec une valeur Bundle.link.relation = self
et une valeur d'URL Bundle.link.url
ne contenant que des paramètres appliqués à la recherche. Cette valeur peut être inspectée pour déterminer si des paramètres ont été ignorés.
Vous pouvez également définir l'en-tête HTTP Prefer: handling=strict
sur une requête de recherche pour que le datastore FHIR renvoie une erreur sur tout paramètre non reconnu.