إجراء تحديثات مجمعة على بيانات FHIR

تسمح لك العملية $bulk-update بتحديث موارد FHIR متعددة بشكل مجمع باستخدام المعالجة غير المتزامنة. يدعم:

• تحديثات على مستوى النظام عبر جميع أنواع الموارد
• التحديثات ذات النطاق لأنواع الموارد الفردية
• عمليات متعددة الموارد في طلب واحد

إشعار

استخدم العملية $bulk-update بحذر. لا يمكن التراجع عن الموارد المحدثة بمجرد الالتزام بها. نوصي أولا بتشغيل بحث FHIR بنفس المعلمات مثل مهمة التحديث المجمع للتحقق من البيانات التي تريد تحديثها.

$bulk-update تستخدم العملية أنواع التصحيحات المدعومة المدرجة أدناه لإجراء التحديثات.

• replace: استبدال قيمة موجودة. إنه يستفيد من دلالة "استبدال" FHIR Patch ، مما يضمن بقاء التحديثات غير فعالة
• upsert: تضيف هذه العملية قيمة إذا لم تكن موجودة، أو تستبدل إذا كانت موجودة

إشعار

عمليات التصحيح الأخرى (على سبيل المثال: إضافة ، نقل ، حذف ، إدراج) غير مدعومة.

المتطلبات الأساسية لعملية التحديث المجمع

الأدوار المطلوبة

لتنفيذ تحديث مجمع، يجب تعيين أحد الأدوار التالية للتطبيق أو المستخدم:

• مشغل بيانات FHIR المجمع: يوفر الوصول إلى العمليات المجمعة في خدمة FHIR.
• مساهم بيانات FHIR: الوصول الإداري إلى خدمة FHIR.

الرؤوس المطلوبة

الرأس	Value
Accept	التطبيق / FHIR + JSON
فضل	الاستجابة غير المتزامنة

Request

يمكنك استخدام معلمات بحث FHIR في الطلب. تدعم عملية التحديث المجمع عوامل تصفية البحث القياسية ، على سبيل المثال: address:contains = Meadow ، أو Patient.birthdate = 1987-02-20. يمكنك أيضا استخدام _include و_revinclude و_not مرجعية لتوسيع معايير البحث، وتاريخ _meta لتكوين سلوك الإصدارات لتحديثات البيانات الوصفية فقط.

طلب أمثلة

1. التحديث المجمع على مستوى النظام: يتيح تنفيذ العملية على مستوى النظام التحديث لموارد FHIR عبر جميع أنواع الموارد على خادم FHIR.

PATCH https://{FHIR-SERVICE-HOST}/$bulk-update

2. التحديثات ذات النطاق إلى نوع المورد الفردي: يسمح تنفيذ العملية لأنواع الموارد الفردية بالتحديث على موارد FHIR التي يتم تعيينها إلى نوع المورد في عنوان URL.

PATCH https://{FHIR-SERVICE-HOST}/[ResourceType]/$bulk-update

3. الاستعلام عن الموارد لتحديثها استنادا إلى معلمات البحث. في هذا المثال ، سنستخدم _include_revinclude ونحدث جميع موارد المريض التي تم تحديثها آخر مرة قبل 2021-12-18 وأي موارد تشير إليها:

PATCH {FHIR-SERVICE-HOST}/Patient/$bulk-update?_lastUpdated=lt2021-12-18&_revinclude=*

PATCH {FHIR-SERVICE-HOST}/DiagnosticReport/$bulk-update?_lastUpdated=lt2021-12-12&_include=DiagnosticReport:based-on:ServiceRequest&_include:iterate=ServiceRequest:encounter

4. تحديثات البيانات الوصفية فقط مع _meta-history معلمة الاستعلام: عندما يتم تعيين سياسة إصدار الخوادم FHIR على إما versioned أو version-update، يسمح لك هذا _meta-history المعلمة بالتحكم فيما إذا كانت التغييرات الوصفية فقط في مورد ما تخلق نسخة تاريخية جديدة من المورد أم لا. افتراضيا، أي تغيير في مورد ما، بما في ذلك التغييرات المتعلقة بالبيانات الوصفية فقط، ينشئ نسخة جديدة ويحفظ النسخة السابقة كسجل تاريخي. عندما تضبط المعامل _meta-history على خطأ، لا تؤدي التغييرات المتعلقة بالبيانات الوصفية فقط إلى إنشاء نسخة جديدة، ولا يتم حفظ النسخة السابقة كسجل تاريخي. هذه الميزة مفيدة في الحالات التي يتم فيها تحديث البيانات الوصفية بشكل متكرر، وتريد تجنب ازدحام تاريخ الموارد بإصدارات متعددة تختلف فقط في البيانات الوصفية. لمزيد من المعلومات والأمثلة، راجع سياسة إصدار FHIR وإدارة التاريخ.

PATCH https://{FHIR-SERVICE-HOST}/$bulk-update?_meta-history=false

عند استخدام التحديث المجمع مع معلمات بحث FHIR، ننصحك باستخدام طلب البحث نفسه في بحث FHIR أولا، حتى تتمكن من التحقق من البيانات التي تخطط لتحديثها.

فيما يلي مثال على نص الطلب.

{ 
  "resourceType": "Parameters", 
  "parameter": [ 
    { 
      "name": "operation", 
      "part": [ 
        { 
          "name": "type", 
          "valueCode": "upsert" 
        }, 

        { 
          "name": "path", 
          "valueString": "Resource.meta" 
        }, 

        { 
          "name": "name", 
          "valueString": "security" 
        }, 

        { 
          "name": "value", 
          "valueCoding": { 
            "system": "http://example.org/security-system", 
            "code": "SECURITY_TAG_CODE", 
            "display": "Updated Security Tag Display" 
          } 
        } 
      ] 
    } 
  ] 
}

النقاط الرئيسية

• يجب أن يبدأ كل مسار تصحيح بالجذر ResourceType (على سبيل المثال ، ) Patient.meta.tagللتمييز بوضوح بين تحديثات المستوى التعريفي وتحديثات العناصر. يمكن تصحيح الخصائص الشائعة باستخدام جذر المورد. يمكن إجراء التحديث المجمع على مستوى النظام أو لنوع مورد واحد أو لأنواع موارد متعددة. إذا كنت بحاجة إلى تحديث حقول مختلفة لأنواع موارد مختلفة، فيمكنك تحديد تعيينات قيمة الحقل في عمليات منفصلة.
• إذا كان بحثك يرجع أنواعا متعددة من الموارد، تطبيق التصحيح فقط على الموارد التي يتطابق نوعها مع ResourceType البادئة في مسار التصحيح؛ يتم تجاهل الأنواع الأخرى.
• SearchParameter وتعتبر StructureDefinition خارج نطاق التحديثات المجمعة. يؤدي تشغيل مهمة تحديث مجمع حسب نوع المورد إلى تشغيل SearchParameter أو StructureDefinition سيؤدي أيضا إلى خطأ 400 Bad Request. إذا قام استعلام تحديث مجمع على مستوى النظام أو نوع المورد بإرجاع موارد من النوع SearchParameter أو StructureDefinition، تجاهلها أثناء العملية. سيتم تحديث أنواع الموارد الأخرى فقط.

استجابة

عند إرسال عملية تحديث مجمعة، يتم إرجاع استجابة بالتنسيق التالي، مع رأس موقع المحتوى-يشير إلى نقطة نهاية الاستقصاء.

Content-Location: https://{hostname}/_operations/bulk-update/{job-id}

نتائج نقطة نهاية الاستقصاء

ستؤدي الطلبات إلى نقطة نهاية الاستقصاء إلى إحدى النتائج الأربع، بناء على حالة مهمة التحديث المجمع. وترد النتيجة في OperationOutcome رد FHIR.

‏الحالة	‏‏الوصف
202	المهمة قيد التنفيذ
200	المهمة التي تم إكمالها أو إلغاؤها من قبل المستخدم
Other	حالة الفشل استنادا إلى نوع الخطأ

تتضمن الاستجابة لعملية التحديث المجمع أربعة مكونات رئيسية:

1. ResourceUpdatedCount: يعرض عدد الموارد التي تم تحديثها بنجاح، مجمعة حسب نوع المورد.
2. ResourceIgnoredCount: يشير إلى عدد الموارد التي تم تجاهلها أثناء التحديث المجمع، حسب نوع المورد. يتم تجاهل الموارد إذا لم يكن هناك طلب تصحيح مطابق لنوعها، أو إذا كانت أنواع مستبعدة مثل SearchParameter أو StructureDefinition.
3. ResourcePatchFailedCount: يعرض عدد الموارد التي فشلت فيها عملية التصحيح، حسب نوع المورد. على سبيل المثال، إذا تمت محاولة استبدال قيمة غير موجودة، فسيفشل التصحيح ويتم احتسابه هنا. تعتبر الوظيفة "فشلا ناعما" إذا فشلت بعض الموارد ولكن نجح البعض الآخر. يتم توفير رسالة عامة في قسم المشاكل، توصي باستخدام عملية تصحيح FHIR على الموارد الفردية للحصول على معلومات خطأ مفصلة.
4. المشاكل: يوفر تفاصيل حول أي حالات فشل في الوظائف أو أسباب التحديثات غير الناجحة.

فيما يلي مثال على نص الاستجابة.

{ 

  "resourceType": "Parameters", 

  "parameter": [ 
    { 
      "name": "ResourceUpdatedCount", 
      "part": [ 
        { "name": "Practitioner", "valueInteger64": 10 }, 
        { "name": "Specimen", "valueInteger64": 7 }, 
        { "name": "Device", "valueInteger64": 3 } 
      ] 
    }, 

    { 
      "name": "ResourceIgnoredCount", 
      "part": [ 
        { "name": "StructureDefinition", "valueInteger64": 9 }, 
        { "name": "SearchParameter", "valueInteger64": 8 } 
      ] 
    } 
  ] 
}

معالجة أخطاء الاستجابة

حالة HTTP	Cause	فعل
400	الوظيفة قيد التشغيل بالفعل أو نوع العملية غير المدعوم أو نوع المورد المستبعد. يمكن تشغيل مهمة تحديث مجمع واحدة فقط في كل مرة. ستؤدي محاولة بدء مهمة أخرى أثناء تقدم وظيفة واحدة بالفعل إلى خطأ 400 طلب غير صحيح.	أعد المحاولة بعد حل النزاع.
403	Unauthorized	قم بتعيين الدور المطلوب.
429	مخنوق	أعد المحاولة مع انخفاض الحمل.
500	خطأ في الخادم	قم بإنشاء تذكرة دعم.
503	مشاكل قاعدة البيانات	أعد المحاولة بعد مرور بعض الوقت.

إلغاء مهمة تحديث مجمع

أرسل طلب DELETE إلى نقطة نهاية استقصاء الوظيفة على النحو التالي.

DELETE https://{FHIR-SERVICE-HOST}/_operations/bulk-update/{job-id}

إشعار

يؤدي إلغاء مهمة إلى استئناف عملية الحذف من حيث توقفت إذا تمت إعادة المحاولة.

سجلات التدقيق

يمكن الاستعلام عن سجلات التدقيق من MicrosoftHealthcareApisAuditLogs:

• تصفية حسب ResourceId.
• ابحث في الإدخالات عن: بدأت المهمة ونجحت الوظيفة وفشل التصحيح.

FAQ

لماذا لا يتطابق عدد الموارد المحدثة مع التوقعات؟

• أقل: ربما تم تعديل الموارد بواسطة وظيفة أخرى قبل تشغيل هذه الوظيفة.
• المزيد: قد تكون مهمة استيراد جديدة قد أدخلت موارد بعد بدء التحديث المجمع.

ما هي خطوات الحل إذا بدا أن مهمة التحديث المجمع الخاصة بي عالقة؟ للتحقق مما إذا كانت مهمة التحديث المجمع عالقة، قم بتشغيل بحث FHIR بنفس المعلمات مثل مهمة التحديث المجمع، حيث تتم إضافة شرط التشغيل المناسب في الاستعلام و _summary=count. إذا كان عدد الموارد ينخفض ، فإن الوظيفة تعمل. يمكنك أيضا إلغاء مهمة التحديث المجمع والمحاولة مرة أخرى.

ما هو التأثير على استدعاءات واجهة برمجة تطبيقات REST عند تنفيذ مهمة عملية تحديث مجمع بشكل متزامن؟ عند تشغيل عملية تحديث مجمع، قد ترى زمن انتقال متزايد في المكالمات المتزامنة للخدمة. لتجنب زيادة وقت الوصول، نوصي بإلغاء مهمة التحديث المجمع، ثم إعادة تشغيلها خلال فترة انخفاض عدد الزيارات.

هل يمكنني التراجع عن التغييرات؟ يجب عليك استخدام إمكانية التحديث المجمع بعناية. على سبيل المثال، إذا تم تفعيل تعيين الإصدار، يمكنك إحضار الإصدارات السابقة واستخدام PUT لاستعادتها، أو استعادتها من نسخة احتياطية (يتم الاحتفاظ بالبيانات لمدة 7-30 يوما حسب الضبط).

ما هو ResourcePatchFailedCount؟ هذا عدد من الموارد التي فشلت أثناء العملية PATCH . قد تشمل الأسباب ما يلي:

• استبدال عنصر غير موجود
• محاولة تحديث حقل غير قابل للتغيير

تحقق من سجل التدقيق أو أرسل طلب PATCH بشكل فردي للحصول على تفاصيل الخطأ.

الخطوات التالية

• تعرف على المزيد حول تصحيح مسار FHIR
• استكشاف وثائق Azure Health Data Services FHIR
• إدارة الأدوار والوصول