كتابة البيانات الطبية

يتوافق هذا الدليل مع الإصدار 1.1.0-beta02 من Health Connect.

لكتابة بيانات طبية باستخدام "السجلّات الطبية" في Health Connect، اتّبِع الخطوات التالية:

  1. التحقّق من توفّر الميزات
  2. طلب أذونات الكتابة
  3. إنشاء مصدر بيانات (MedicalDataSource)
  4. كتابة مرجع طبي (MedicalResource)

مدى توفّر الميزة

لتحديد ما إذا كان جهاز المستخدم يتيح استخدام "السجلات الطبية" في Health Connect، تحقَّق من توفّر FEATURE_PERSONAL_HEALTH_RECORD على الجهاز:

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_PERSONAL_HEALTH_RECORD
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
} else {
  // Feature isn't available
}

يمكنك الاطّلاع على التحقّق من توفّر الميزة لمعرفة المزيد.

الأذونات المطلوبة

تتم حماية كتابة البيانات الطبية من خلال الإذن التالي:

  • android.permission.health.WRITE_MEDICAL_DATA

يجب الإفصاح عن هذه الأذونات في Play Console لتطبيقك، وكذلك في ملف البيان الخاص بتطبيقك، وذلك باتّباع الخطوات التالية:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_MEDICAL_DATA" />
</application>

أنت المسؤول عن الإفصاح عن جميع الأذونات المناسبة التي تنوي استخدامها في أجهزتك وتطبيقاتك. يجب أيضًا التأكّد من أنّ المستخدم قد منح كل إذن قبل استخدامه.

طلب الأذونات من المستخدم

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

لإجراء ذلك، أنشئ مجموعة من الأذونات لأنواع البيانات المطلوبة. تأكَّد من أنّ الأذونات في المجموعة معرَّفة في بيان Android أولاً.

// Create a set of permissions for required data types
import androidx.health.connect.client.permission.HealthPermission.Companion.PERMISSION_WRITE_MEDICAL_DATA

val PERMISSIONS =
    setOf(
       PERMISSION_WRITE_MEDICAL_DATA
)

استخدِم getGrantedPermissions لمعرفة ما إذا كان تطبيقك قد حصل على الأذونات المطلوبة. إذا لم يكن الأمر كذلك، استخدِم createRequestPermissionResultContract لطلب هذه الأذونات. سيؤدي ذلك إلى عرض شاشة أذونات Health Connect.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

بما أنّ المستخدمين يمكنهم منح الأذونات أو إبطالها في أي وقت، يجب أن يتحقّق تطبيقك بشكل دوري من الأذونات الممنوحة وأن يتعامل مع السيناريوهات التي يتم فيها فقدان الإذن.

مصادر البيانات

يمثّل MedicalDataSource في Health Connect مصدر بيانات متاحًا للمستخدمين، مثل مؤسسة رعاية صحية أو مستشفى أو واجهة برمجة تطبيقات.

يتم تنظيم السجلات الطبية المخزَّنة في Health Connect في MedicalDataSource. ويتيح ذلك فصل السجلات الطبية للشخص نفسه الواردة من مصادر مختلفة، مثل واجهات برمجة التطبيقات أو أنظمة الرعاية الصحية.

إذا كانت جميع السجلات من المصدر نفسه، لن يحتاج تطبيق الكتابة إلى إنشاء سوى MedicalDataSource واحد. إذا كانت السجلات واردة من مصادر متعددة، يمكن لأحد التطبيقات إنشاء MedicalDataSource واحد إذا تمت مطابقة البيانات وكان لكل السجلات مجموعة فريدة من نوع مورد FHIR ومعرّف مورد FHIR. بخلاف ذلك، يجب إنشاء MedicalDataSource لكل مصدر بيانات.

يجب ربط جميع السجلات الطبية بـ MedicalDataSource، لذا يجب إنشاء هذا السجل قبل كتابة الموارد.

خصائص MedicalDataSource:

  • الاسم المعروض (مطلوب): الاسم المعروض لمصدر البيانات الذي يظهر للمستخدمين، ويتم تعريفه بشكل فريد لكل تطبيق كتابة.
  • عنوان URI الأساسي لـ FHIR (مطلوب): بالنسبة إلى البيانات الواردة من خادم FHIR، يجب أن يكون هذا العنوان هو عنوان URL الأساسي لـ FHIR (على سبيل المثال، https://example.com/fhir/). يمكن ربط مصادر بيانات متعددة بعنوان URL الأساسي نفسه لـ FHIR.

    إذا تم إنشاء البيانات بواسطة تطبيق بدون عنوان URL بتنسيق FHIR، يجب أن يكون هذا المعرّف معرّف موارد منتظمًا فريدًا ومفهومًا يحدّده التطبيق (على سبيل المثال، myapp://..) ويشير إلى مصدر البيانات.

    على سبيل المثال، إذا كان تطبيق العميل يتيح الربط بصفحات في التطبيق، يمكن استخدام هذا الرابط كمعرّف الموارد المنتظم الأساسي لـ FHIR. الحد الأقصى لطول معرّف الموارد الموحّد (URI) هو 2000 حرف.

  • اسم الحزمة (تتم تعبئته تلقائيًا): التطبيق الذي يكتب البيانات.

  • إصدار FHIR (مطلوب): إصدار FHIR. يجب أن يكون إصدارًا متوافقًا.

إنشاء سجلّ MedicalDataSource

أنشئ سجلاً لكل مؤسسة أو جهة رعاية صحية يرتبط بها تطبيقك.

// Create a `MedicalDataSource`
// Note that `displayName` must be unique across `MedicalDataSource`s
// Each `MedicalDataSource` is assigned an `id` by the system on creation
val medicalDataSource: MedicalDataSource =
    healthConnectClient.createMedicalDataSource(
        CreateMedicalDataSourceRequest(
            fhirBaseUri = Uri.parse("https://fhir.com/oauth/api/FHIR/R4/"),
            displayName = "Test Data Source",
            fhirVersion = FhirVersion(4, 0, 1)
        )
    )

حذف سجلّ MedicalDataSource

يعرض المثال السابق id من خلال النظام عند الإنشاء. إذا كنت بحاجة إلى حذف سجل MedicalDataSource، عليك الرجوع إلى id نفسه:

// Delete the `MedicalDataSource` that has the specified `id`
healthConnectClient.deleteMedicalDataSourceWithData(medicalDataSource.id)

المراجع الطبية

يمثّل MedicalResource في Health Connect مصدر FHIR (الذي يحتوي على سجلّ طبي)، بالإضافة إلى البيانات الوصفية.

خصائص MedicalResource:

  • DataSourceId (مطلوب): مصدر البيانات كما هو موضّح في MedicalDataSource.
  • إصدار FHIR (مطلوب): إصدار FHIR. يجب أن تكون إصدارًا متوافقًا.
  • مورد FHIR (مطلوب): مثيل مورد FHIR بترميز JSON
  • نوع المورد الطبي (تتم تعبئته تلقائيًا): الفئة التي تظهر للمستخدم الخاصة بالمورد، والتي يتم ربطها بالأذونات التي تظهر للمستخدم.

إعداد موارد FHIR بتنسيق JSON

قبل كتابة موارد طبية في Health Connect، عليك إعداد سجلات موارد FHIR بتنسيق JSON. خزِّن كل ملف JSON في متغير خاص به لإدراجه كمورد طبي.

إذا كنت بحاجة إلى مساعدة بشأن تنسيق FHIR JSON، يمكنك الرجوع إلى بيانات المثال التي تقدّمها مؤسسة HL7.

إدراج سجلّات MedicalResource أو تعديلها

استخدِم UpsertMedicalResourceRequest لإدراج سجلات جديدة أو تعديل السجلات الحالية MedicalResource الخاصة بـ MedicalDataSource:

// Insert `MedicalResource`s into the `MedicalDataSource`
val medicalResources: List<MedicalResource> =
    healthConnectClient.upsertMedicalResources(
        listOf(
            UpsertMedicalResourceRequest(
                medicalDataSource.id,
                medicalDataSource.fhirVersion,
                medicationJsonToInsert // a valid FHIR json string
            )
        )
    )

// Update `MedicalResource`s in the `MedicalDataSource`
val updatedMedicalResources: List<MedicalResource> =
    healthConnectClient.upsertMedicalResources(
        listOf(
            UpsertMedicalResourceRequest(
                medicalDataSource.id,
                medicalDataSource.fhirVersion,
                // a valid FHIR json string
                // if this resource has the same type and ID as in `medicationJsonToInsert`,
                // this `upsertMedicalResources()` call will update the previously inserted
                // `MedicalResource`
                updatedMedicationJsonToInsert
            )
        )
    )

مثال على مورد FHIR

في المثال السابق، مثّل المتغير medicationJsonToInsert سلسلة JSON صالحة بتنسيق FHIR.

في ما يلي مثال على شكل ملف JSON، باستخدام AllergyIntolerance كنوع مورد FHIR، والذي سيتم ربطه بنوع المورد الطبي FHIR_RESOURCE_TYPE_ALLERGY_INTOLERANCE في &quot;السجلات الطبية&quot;:

{
  "resourceType": "AllergyIntolerance",
  "id": "allergyintolerance-1",
  "criticality": "high",
  "code": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "91936005",
        "display": "Penicillin allergy"
      }
    ],
    "text": "Penicillin allergy"
  },
  "recordedDate": "2020-10-09T14:58:00+00:00",
   "asserter": {
    "reference": "Patient/patient-1"
  },
  "lastOccurrence": "2020-10-09",
  "patient": {
    "reference": "Patient/patient-1",
    "display": "B., Alex"
  }
  ...
}

حذف سجلّ MedicalResource

يمكن حذف سجلّات MedicalResource حسب رقم التعريف:

// Delete `MedicalResource`s matching the specified `dataSourceId`, `type` and `fhirResourceId`
healthConnectClient.deleteMedicalResources(
    medicalResources.map { medicalResource: MedicalResource ->
        MedicalResourceId(
            dataSourceId = medicalDataSource.id,
            fhirResourceType = medicalResource.id.fhirResourceType,
            fhirResourceId = medicalResource.id.fhirResourceId
        )
    }
)

أو يمكن حذفها من خلال medicalResourceType:

// Delete all `MedicalResource`s that are in any pair of provided `dataSourceIds` and
// `medicalResourceTypes`
healthConnectClient.deleteMedicalResources(
    DeleteMedicalResourcesRequest(
        dataSourceIds = setOf(medicalDataSource.id),
        medicalResourceTypes = setOf(MEDICAL_RESOURCE_TYPE_MEDICATIONS)
    )
)