Vue d’ensemble de la recherche dans l’API Azure pour FHIR
Important
L’API Azure pour FHIR sera supprimée le 30 septembre 2026. Suivez les stratégies de migration pour passer au service FHIR Azure Health Data Services à cette date. En raison de la mise hors service de l’API Azure pour FHIR, les nouveaux déploiements ne seront pas autorisés à compter du 1er avril 2025. Le service FHIR Azure Health Data Services est la version évoluée de l’API Azure pour FHIR qui permet aux clients de gérer les services FHIR, DICOM et MedTech avec des intégrations dans d’autres services Azure.
La spécification Fast Healthcare Interoperability Resources (FHIR®) définit les notions de base de la recherche de ressources FHIR. Cet article vous guide tout au long des aspects clés de la recherche de ressources dans FHIR. Pour obtenir toute les informations sur la recherche de ressources FHIR, reportez-vous à Recherche dans la spécification FHIR HL7. Tout au long de cet article, nous allons donner des exemples de syntaxe de recherche. Chaque recherche est effectuée sur votre serveur FHIR, qui a généralement une URL https://<FHIRSERVERNAME>.azurewebsites.net. Dans les exemples, nous allons utiliser l’espace réservé {{FHIR_URL}} pour cette URL.
Des recherches FHIR peuvent être effectuées sur un type de ressource spécifique, un compartiment spécifié ou toutes les ressources. La façon la plus simple d’exécuter une recherche dans FHIR consiste à utiliser une requête GET. Par exemple, si vous souhaitez extraire tous les patients de la base de données, vous pouvez utiliser la requête suivante :
GET {{FHIR_URL}}/Patient
Vous pouvez également effectuer une recherche à l’aide de POST, ce qui est utile si la chaîne de requête est trop longue. Pour effectuer une recherche à l’aide de POST, les paramètres de recherche peuvent être envoyés sous forme de corps de formulaire. Cela permet une série plus longue et plus complexe de paramètres de requête qui peuvent être difficiles à voir et à comprendre dans une chaîne de requête.
Si la requête de recherche réussit, vous recevrez une réponse de bundle FHIR avec le type searchset. Si la recherche échoue, vous trouverez les détails de l’erreur dans le OperationOutcome pour vous aider à comprendre pourquoi la recherche a échoué.
Dans les sections suivantes, nous allons aborder les différents aspects impliqués dans la recherche. Une fois que vous avez examiné ces détails, reportez-vous à notre page d’exemples contenant des exemples de recherches que vous pouvez effectuer dans l’API Azure pour FHIR.
Paramètres de recherche
Lorsque vous effectuez une recherche, vous allez effectuer une recherche basée sur différents attributs de la ressource. Ces attributs sont appelés paramètres de recherche. Chaque ressource a un ensemble de paramètres de recherche définis. Le paramètre de recherche doit être défini et indexé dans la base de données pour pouvoir effectuer une recherche sur celle-ci.
Chaque paramètre de recherche a des types de données définis. La prise en charge des différents types de données est décrite ci-dessous :
Avertissement
Il existe actuellement un problème lors de l’utilisation de _sort sur l’API Azure pour FHIR avec la recherche chaînée. Pour plus d’informations, consultez le problème open source #2344. Cela sera résolu lors d’une version en décembre 2021.
| Type de paramètre de recherche | Azure API pour FHIR | Service FHIR dans les Services de données de santé Azure | Commentaire |
|---|---|---|---|
| number | Oui | Oui | |
| date | Oui | Oui | |
| string | Oui | Oui | |
| token | Oui | Oui | |
| reference | Oui | Oui | |
| composite | Partiel | Partiel | La liste des types composites pris en charge est décrite plus loin dans cet article |
| quantité | Oui | Oui | |
| URI | Oui | Oui | |
| spécial | Non | Non |
Paramètres de recherche courants
Il existe des paramètres de recherche courants qui s’appliquent à toutes les ressources. Ceux-ci sont répertoriés ci-dessous, ainsi que leur prise en charge dans l’API Azure pour FHIR :
| Paramètre de recherche commun | Azure API pour FHIR | Service FHIR dans les Services de données de santé Azure | Commentaire |
|---|---|---|---|
| _id | Oui | Oui | |
| _lastUpdated | Oui | Oui | |
| _tag | Oui | Oui | |
| _type | Oui | Oui | |
| _security | Oui | Oui | |
| _profile | Oui | Oui | |
| _has | Partiel | Oui | La prise en charge de _has est en MVP dans l’API Azure pour FHIR et la version OSS soutenue par Azure Cosmos DB. Vous trouverez plus d’informations dans la section de chaînage ci-dessous. |
| _query | Non | Non | |
| _filter | Non | Non | |
| _list | Non | Non | |
| _text | Non | Non | |
| _content | Non | Non |
Paramètres spécifiques de ressources
Avec l’API Azure pour FHIR, nous prenons en charge presque tous les paramètres de recherche spécifiques de ressources définis par la spécification FHIR. Les seuls paramètres de recherche que nous ne prenons pas en charge peuvent être retrouvés dans les liens ci-dessous :
Vous pouvez également voir la prise en charge actuelle des paramètres de recherche dans la déclaration de capacité FHIR avec la requête suivante :
GET {{FHIR_URL}}/metadata
Pour afficher les paramètres de recherche dans la déclaration de capacité, accédez à CapabilityStatement.rest.resource.searchParam pour voir les paramètres de recherche de chaque ressource et à CapabilityStatement.rest.searchParam pour retrouver les paramètres de recherche pour toutes les ressources.
Remarque
L’API Azure pour FHIR ne crée pas ou n’indexe pas automatiquement des paramètres de recherche qui ne sont pas définis par la spécification FHIR. Toutefois, nous vous fournissons une prise en charge pour définir vos propres paramètres de recherche.
Paramètres de recherche composite
La recherche composite vous permet de rechercher sur des paires de valeur. Par exemple, si vous recherchiez une observation de grandeur dans laquelle la personne mesurait 60 pouces, vous souhaitez vous assurer qu’un seul composant de l’observation contenait le code de hauteur et la valeur de 60. Vous ne souhaitez pas obtenir une observation dans laquelle un poids de 60 et une grandeur de 48 ont été stockés, même si l’observation aurait des entrées qualifiées pour la valeur de 60 et le code de grandeur, simplement dans différentes sections de composant.
Avec l’API Azure pour FHIR, nous prenons en charge les paires de types de paramètres de recherche suivantes :
- Référence, Jeton
- Jeton, Date
- Jeton, Nombre, Nombre
- Jeton, Quantité
- Jeton, Chaîne
- Jeton, Jeton
Pour plus d’informations, consultez les paramètres de recherche composite de HL7.
Remarque
Les paramètres de recherche composite ne prennent pas en charge les modificateurs conformément à la spécification FHIR.
Modificateurs &préfixes
Les modificateurs vous permettent de modifier le paramètre de recherche. Voici une vue d’ensemble de tous les modificateurs FHIR et de la prise en charge dans l’API Azure pour FHIR.
| Modificateurs | Azure API pour FHIR | Service FHIR dans les Services de données de santé Azure | Commentaire |
|---|---|---|---|
| :missing | Oui | Oui | |
| :exact | Oui | Oui | |
| :contains | Oui | Oui | |
| :text | Oui | Oui | |
| :type (référence) | Oui | Oui | |
| :not | Oui | Oui | |
| :below (uri) | Oui | Oui | |
| :above (uri) | Oui | Oui | |
| :in (jeton) | Non | Non | |
| :below (jeton) | Non | Non | |
| :above (jeton) | Non | Non | |
| :not-in (jeton) | Non | Non |
Pour les paramètres de recherche qui ont un ordre spécifique (nombres, dates et quantités), vous pouvez utiliser un préfixe sur le paramètre pour vous aider à trouver des correspondances. L’API Azure pour FHIR prend en charge tous les préfixes.
Paramètres des résultats de la recherche
Pour vous aider à gérer les ressources retournées, il existe des paramètres de résultat de recherche que vous pouvez utiliser dans votre recherche. Pour plus d’informations sur l’utilisation de chacun des paramètres de résultat de recherche, reportez-vous au site web HL7.
| Paramètres de résultat de la recherche | Azure API pour FHIR | Service FHIR dans les Services de données de santé Azure | Commentaire |
|---|---|---|---|
| _elements | Oui | Oui | |
| _Compter | Oui | Oui | _count est limité à 1 000 ressources. Si la valeur est supérieure à 1 000, seuls 1 000 résultats sont retournés et un avertissement est retourné dans le bundle. |
| _include | Oui | Oui | Les éléments inclus sont limités à 100. _include sur PaaS et OSS sur Azure Cosmos DB n’inclut pas la prise en charge du modificateur :iterate (#2137). |
| _revinclude | Oui | Oui | Les éléments inclus sont limités à 100. _revinclude sur PaaS et OSS sur Azure Cosmos DB n’inclut pas la prise en charge du modificateur :iterate (2137). Il existe également un code d’état incorrect pour une requête incorrecte #1319 |
| _summary | Oui | Oui | |
| _total | Partiel | Partiel | _total=none et _total=accurate |
| _sort | Partiel | Partiel | sort=_lastUpdated est pris en charge sur l’API Azure pour FHIR et le service FHIR. Pour l’API Azure pour FHIR et les bases de données Azure Cosmos DB OSS créées après le 20 avril 2021, le tri est pris en charge sur le prénom, le nom, la date de naissance et la date clinique. |
| _contained | Non | Non | |
| _containedType | Non | Non | |
| _score | Non | N° |
Remarque
Par défaut, _sort trie l’enregistrement par ordre croissant. Vous pouvez également utiliser le préfixe '-' pour trier par ordre décroissant. En outre, le service FHIR et l’API Azure pour FHIR vous permettent uniquement de trier sur un seul champ à la fois.
Par défaut, l’API Azure pour FHIR est définie sur la gestion tolérante. Cela signifie que le serveur ignore tous les paramètres inconnus ou non pris en charge. Si vous souhaitez utiliser une gestion stricte, vous pouvez inclure l’en-tête Prefer et définir handling=strict.
Chaîné et recherche en chaînée inversée
Une recherche chaînée vous permet d’effectuer un recherche à l’aide d’un paramètre de recherche sur une ressource référencée par une autre ressource. Par exemple, si vous souhaitez trouver des rencontres où le nom du patient est Jane, utilisez :
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
De même, vous pouvez effectuer une recherche chaînée inversée. Cela vous permet d’accéder à des ressources où vous spécifiez des critères sur d’autres ressources qui y font référence. Pour obtenir plus d’exemples de recherche chaînée et chaînée inversée, reportez-vous à la page Exemples de recherche FHIR.
Remarque
Dans l’API Azure pour FHIR et l’open source soutenu par Azure Cosmos DB, il existe une limitation dans laquelle chaque sous-requête requise pour les recherches chaînées et chaînées inversées retourne uniquement 1 000 éléments. S’il plus de 1 000 éléments sont trouvés, vous recevrez le message d’erreur suivant : « Les sous-requêtes dans une expression chaînée ne peuvent pas retourner plus de 1 000 résultats, utilisez des critères plus sélectifs. » Pour qu’une requête réussisse, vous devez être plus spécifique dans ce que vous recherchez.
Pagination
Comme mentionné ci-dessus, les résultats d’une recherche sont un bundle paginé. Par défaut, la recherche renverra 10 résultats par page, mais cela peut être augmenté (ou diminué) en spécifiant _count. Dans le bundle, il y aura un lien automatique qui contient le résultat actuel de la recherche. S’il existe des correspondances supplémentaires, le bundle contient un lien suivant. Vous pouvez continuer à utiliser le lien suivant pour obtenir les pages de résultats suivantes. _count est limité à 1 000 éléments maximum.
Le lien suivant dans le bundle a une limite de taille de jeton de continuation de 3 Ko. Vous avez la possibilité d’ajuster la taille du jeton de continuation comprise entre 1 et 3 Ko, à l’aide de l’en-tête « x-ms-documentdb-responsecontinuationtokenlimitinkb ».
Actuellement, l’API Azure pour FHIR prend uniquement en charge le lien suivant dans les bundles et ne prend pas en charge les liens premier, dernier ou précédent.
Étapes suivantes
Maintenant que vous avez découvert les principes de base de la recherche, consultez la page d’exemples de recherche pour plus d’informations sur la façon de rechercher à l’aide de différents paramètres de recherche, modificateurs et autres scénarios de recherche FHIR.
FHIR® est une marque déposée de HL7 utilisé avec l’autorisation de HL7.