نظرة عامة على البحث في واجهة برمجة تطبيقات Azure ل FHIR
هام
سيتم إيقاف Azure API ل FHIR في 30 سبتمبر 2026. اتبع استراتيجيات الترحيل للانتقال إلى خدمة Azure Health Data Services FHIR بحلول ذلك التاريخ. بسبب إيقاف Azure API ل FHIR، لن يسمح بالنشرات الجديدة بدءا من 1 أبريل 2025. خدمة Azure Health Data Services FHIR هي الإصدار المتطور من Azure API ل FHIR الذي يمكن العملاء من إدارة خدمات FHIR وDICOM وMedTech مع عمليات التكامل في خدمات Azure الأخرى.
تحدد مواصفات موارد التشغيل التفاعلي للرعاية الصحية السريعة (FHIR®) أساسيات البحث عن موارد FHIR. سترشدك هذه المقالة خلال بعض الجوانب الرئيسية للبحث في الموارد في FHIR. للحصول على تفاصيل كاملة حول البحث في موارد FHIR، راجع البحث في مواصفات HL7 FHIR. خلال هذه المقالة، سنقدم أمثلة على بناء جملة البحث. سيكون كل بحث مقابل خادم FHIR الخاص بك، والذي يحتوي عادة على عنوان URL ل https://<FHIRSERVERNAME>.azurewebsites.net. في الأمثلة، سنستخدم العنصر النائب {{FHIR_URL}} لعنون URL هذا.
يمكن أن تكون عمليات البحث في FHIR مقابل نوع مورد معين أو حجرة محددة أو جميع الموارد. أبسط طريقة لتنفيذ بحث في FHIR هي استخدام GET طلب. على سبيل المثال، إذا كنت تريد سحب جميع المرضى في قاعدة البيانات، يمكنك استخدام الطلب التالي:
GET {{FHIR_URL}}/Patient
يمكنك أيضا البحث باستخدام POST، وهو أمر مفيد إذا كانت سلسلة الاستعلام طويلة جدا. للبحث باستخدام POST، يمكن إرسال معلمات البحث كنص نموذج. يسمح هذا بسلسلة أطول وأكثر تعقيدا من معلمات الاستعلام التي قد يكون من الصعب رؤيتها وفهمها في سلسلة استعلام.
إذا نجح طلب البحث، فستتلقى استجابة حزمة FHIR مع النوع searchset. إذا فشل البحث، فستجد تفاصيل الخطأ في OperationOutcome لمساعدتك على فهم سبب فشل البحث.
في الأقسام التالية، سنغطي الجوانب المختلفة المتضمنة في البحث. بمجرد مراجعة هذه التفاصيل، راجع صفحة العينات التي تحتوي على أمثلة لعمليات البحث التي يمكنك إجراؤها في واجهة برمجة تطبيقات Azure ل FHIR.
معلمات البحث
عند إجراء بحث، ستقوم بالبحث استنادا إلى سمات مختلفة للمورد. تسمى هذه السمات معلمات البحث. يحتوي كل مورد على مجموعة من معلمات البحث المحددة. يجب تعريف معلمة البحث وفهرستها في قاعدة البيانات حتى تتمكن من البحث عنها بنجاح.
تحتوي كل معلمة بحث على أنواع بيانات محددة. يتم توضيح دعم أنواع البيانات المختلفة أدناه:
تحذير
هناك مشكلة حاليا عند استخدام _sort على واجهة برمجة تطبيقات Azure ل FHIR مع البحث المتسلسل. لمزيد من المعلومات، راجع المشكلة مفتوحة المصدر #2344. سيتم حل هذا خلال إصدار في ديسمبر 2021.
| نوع معلمة البحث | واجهة برمجة تطبيقات Azure ل FHIR | خدمة FHIR في Azure Health Data Services | تعليق |
|---|---|---|---|
| رقم | نعم | نعم | |
| date | نعم | نعم | |
| سلسلة | نعم | نعم | |
| الرمز المميز | نعم | نعم | |
| reference | نعم | نعم | |
| مركب | جزئي | جزئي | يتم وصف قائمة الأنواع المركبة المدعومة لاحقا في هذه المقالة |
| الكمية | نعم | نعم | |
| URI | نعم | نعم | |
| الخاصه | لا | لا |
معلمات البحث الشائعة
هناك معلمات بحث شائعة تنطبق على جميع الموارد. يتم سردها أدناه، جنبا إلى جنب مع دعمها داخل واجهة برمجة تطبيقات Azure ل FHIR:
| معلمة البحث الشائعة | واجهة برمجة تطبيقات Azure ل FHIR | خدمة FHIR في Azure Health Data Services | تعليق |
|---|---|---|---|
| _id | نعم | نعم | |
| _lastUpdated | نعم | نعم | |
| _العلامه | نعم | نعم | |
| _type | نعم | نعم | |
| _الامن | نعم | نعم | |
| _الشخصيه | نعم | نعم | |
| _has | جزئي | نعم | يتوفر دعم _has في MVP في واجهة برمجة تطبيقات Azure ل FHIR وإصدار OSS المدعوم من Azure Cosmos DB. يتم تضمين مزيد من التفاصيل ضمن قسم التسلسل أدناه. |
| _الاستعلام | لا | لا | |
| _تصفيه | لا | لا | |
| _قائمه | لا | لا | |
| _النص | لا | لا | |
| _المحتوي | لا | لا |
معلمات خاصة بالموارد
مع واجهة برمجة تطبيقات Azure ل FHIR، ندعم تقريبا جميع معلمات البحث الخاصة بالموارد المحددة بواسطة مواصفات FHIR. تتوفر معلمات البحث الوحيدة التي لا ندعمها في الارتباطات أدناه:
يمكنك أيضا مشاهدة الدعم الحالي لمعلمات البحث في بيان قدرة FHIR مع الطلب التالي:
GET {{FHIR_URL}}/metadata
لمشاهدة معلمات البحث في عبارة القدرة، انتقل إلى CapabilityStatement.rest.resource.searchParam لمشاهدة معلمات البحث لكل مورد والعثور CapabilityStatement.rest.searchParam على معلمات البحث لكافة الموارد.
إشعار
لا تقوم واجهة برمجة تطبيقات Azure ل FHIR تلقائيا بإنشاء أو فهرسة أي معلمات بحث لم يتم تعريفها بواسطة مواصفات FHIR. ومع ذلك، نحن نقدم لك الدعم لتحديد معلمات البحث الخاصة بك.
معلمات البحث المركب
يسمح لك البحث المركب بالبحث مقابل أزواج القيم. على سبيل المثال، إذا كنت تبحث عن ملاحظة ارتفاع حيث كان الشخص 60 بوصة، فسترغب في التأكد من أن مكونا واحدا من الملاحظة يحتوي على رمز الارتفاع وقيمة 60. لن ترغب في الحصول على ملاحظة حيث تم تخزين وزن 60 وارتفاع 48، على الرغم من أن الملاحظة سيكون لها إدخالات مؤهلة لقيمة 60 ورمز الارتفاع، فقط في أقسام مكونات مختلفة.
باستخدام واجهة برمجة تطبيقات Azure ل FHIR، ندعم أزواج نوع معلمة البحث التالية:
- مرجع، رمز مميز
- الرمز المميز، التاريخ
- الرمز المميز، الرقم، الرقم
- الرمز المميز، الكمية
- الرمز المميز، سلسلة
- الرمز المميز، الرمز المميز
لمزيد من المعلومات، راجع معلمات البحث المركب HL7.
إشعار
لا تدعم معلمات البحث المركب المعدلات وفقا لمواصفات FHIR.
المعدلات والبادئات
تسمح لك المعدلات بتعديل معلمة البحث. فيما يلي نظرة عامة على جميع معدلات FHIR والدعم في واجهة برمجة تطبيقات Azure ل FHIR.
| معدلات | واجهة برمجة تطبيقات Azure ل FHIR | خدمة FHIR في Azure Health Data Services | تعليق |
|---|---|---|---|
| :مفقود | نعم | نعم | |
| :الدقيق | نعم | نعم | |
| :يحتوي | نعم | نعم | |
| :النص | نعم | نعم | |
| :type (مرجع) | نعم | نعم | |
| :لا | نعم | نعم | |
| :أدناه (uri) | نعم | نعم | |
| :above (uri) | نعم | نعم | |
| :in (رمز مميز) | لا | لا | |
| :أدناه (رمز مميز) | لا | لا | |
| :أعلاه (رمز مميز) | لا | لا | |
| :غير موجود (رمز مميز) | لا | لا |
بالنسبة لمعلمات البحث التي لها ترتيب معين (أرقام وتواريخ وكميات)، يمكنك استخدام بادئة على المعلمة للمساعدة في العثور على التطابقات. تدعم واجهة برمجة تطبيقات Azure ل FHIR جميع البادئات.
معلمات نتائج البحث
للمساعدة في إدارة الموارد التي تم إرجاعها، هناك معلمات نتائج البحث التي يمكنك استخدامها في البحث. للحصول على تفاصيل حول كيفية استخدام كل معلمة من معلمات نتائج البحث، راجع موقع HL7 على الويب.
| معلمات نتائج البحث | واجهة برمجة تطبيقات Azure ل FHIR | خدمة FHIR في Azure Health Data Services | تعليق |
|---|---|---|---|
| _عناصر | نعم | نعم | |
| _عدد | نعم | نعم | يقتصر _count على 1000 مورد. إذا تم تعيين أعلى من 1000، فسيتم إرجاع 1000 فقط وسيتم إرجاع تحذير في المجموعة. |
| _تشمل | نعم | نعم | تقتصر العناصر المضمنة على 100. لا تتضمن _include على PaaS وOSS على Azure Cosmos DB :iterate support (#2137). |
| _revinclude | نعم | نعم | تقتصر العناصر المضمنة على 100. لا تتضمن _revinclude على PaaS وOSS على Azure Cosmos DB :iterate support (#2137). هناك أيضا رمز حالة غير صحيح لطلب غير صحيح #1319 |
| _موجز | نعم | نعم | |
| _مجموع | جزئي | جزئي | _total=none و _total=دقيقة |
| _نوع | جزئي | جزئي | يتم دعم sort=_lastUpdated على Azure API ل FHIR وخدمة FHIR. بالنسبة لواجهة برمجة تطبيقات Azure لقواعد بيانات FHIR وOSS Azure Cosmos DB التي تم إنشاؤها بعد 20 أبريل 2021، يتم دعم الفرز على الاسم الأول واسم العائلة وتاريخ الميلاد والتاريخ السريري. |
| _الوارده | لا | لا | |
| _containedType | لا | لا | |
| _نقاط | لا | لا |
إشعار
بشكل افتراضي _sort ، يقوم بفرز السجل بترتيب تصاعدي. يمكنك استخدام البادئة '-' للفرز بترتيب تنازلي. بالإضافة إلى ذلك، تسمح لك خدمة FHIR وواجهة برمجة تطبيقات Azure ل FHIR فقط بالفرز على حقل واحد في كل مرة.
بشكل افتراضي، يتم تعيين واجهة برمجة تطبيقات Azure ل FHIR إلى معالجة متساهلة. وهذا يعني أن الخادم سيتجاهل أي معلمات غير معروفة أو غير مدعومة. إذا كنت ترغب في استخدام معالجة صارمة، يمكنك استخدام العنوان تفضيل وتعيين handling=strict.
البحث المتسلسل والعكسي
يسمح لك البحث المتسلسل بالبحث باستخدام معلمة بحث على مورد يشير إليه مورد آخر. على سبيل المثال، إذا كنت تريد العثور على لقاءات حيث يكون اسم المريض هو جين، فاستخدم:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
وبالمثل، يمكنك إجراء بحث عكسي متسلسل. يسمح لك هذا بالحصول على الموارد حيث تحدد معايير على الموارد الأخرى التي تشير إليها. لمزيد من الأمثلة على البحث المتسلسل والعكسي، راجع صفحة أمثلة بحث FHIR.
إشعار
في واجهة برمجة تطبيقات Azure ل FHIR مصدر مفتوح المدعومة من Azure Cosmos DB، هناك قيود حيث سيعيد كل استعلام فرعي مطلوب لعمليات البحث المتسلسلة والعكسية المتسلسلة 1000 عنصر فقط. إذا تم العثور على أكثر من 1000 عنصر، فستتلقى رسالة الخطأ التالية: "لا يمكن أن ترجع الاستعلامات الفرعية في تعبير متسلسل أكثر من 1000 نتيجة، يرجى استخدام معايير أكثر انتقائية." للحصول على استعلام ناجح، ستحتاج إلى أن تكون أكثر تحديدا في ما تبحث عنه.
فصل الصفحات
كما ذكر أعلاه، ستكون النتائج من البحث مجموعة صفحات. بشكل افتراضي، سيرجع البحث 10 نتائج لكل صفحة، ولكن يمكن زيادة هذا (أو تقليله) عن طريق تحديد _count. داخل المجموعة، سيكون هناك ارتباط ذاتي يحتوي على النتيجة الحالية للبحث. إذا كانت هناك تطابقات إضافية، فستحتوي المجموعة على ارتباط تالي. يمكنك الاستمرار في استخدام الارتباط التالي للحصول على الصفحات اللاحقة من النتائج. _count يقتصر على 1000 عنصر أو أقل.
يحتوي الارتباط التالي في الحزمة على حد لحجم الرمز المميز للمتابعة وهو 3 كيلوبايت. لديك مرونة لتعديل حجم الرمز المميز للمتابعة بين 1 إلى 3 كيلوبايت، باستخدام العنوان "x-ms-documentdb-responsecontinuationtokenlimitinkb".
حاليا، تدعم واجهة برمجة تطبيقات Azure ل FHIR الارتباط التالي فقط في الحزم، ولا تدعم الارتباطات الأولى أو الأخيرة أو السابقة.
الخطوات التالية
الآن بعد أن تعرفت على أساسيات البحث، راجع صفحة نماذج البحث للحصول على تفاصيل حول كيفية البحث باستخدام معلمات بحث مختلفة ومؤشرات وسيناريوهات بحث FHIR الأخرى.
FHIR® هي علامة تجارية مسجلة ل HL7 وتستخدم بإذن من HL7.