本頁面由 Cloud Translation API 翻譯而成。

寫入醫療資料

本指南適用於「健康資料同步」1.1.0-beta02 版。

如要使用「健康資料同步」的「健康記錄」寫入醫療資料，請按照下列步驟操作：

查看功能適用情形
要求寫入權限
建立資料來源 (MedicalDataSource)
撰寫醫療資源 (MedicalResource)

功能適用情況

如要判斷使用者的裝置是否支援「健康資料同步」的「健康記錄」，請檢查用戶端是否提供 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 管理中心和應用程式資訊清單中，為應用程式聲明這些權限：

<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代表面向使用者的資料來源，例如醫療機構、醫院或 API。

儲存在「健康資料同步」中的病歷會整理成 MedicalDataSource。這樣一來，系統就能區分來自不同來源 (例如 API 或醫療保健系統) 的同一位病患醫療記錄。

如果所有記錄都來自相同來源，撰寫應用程式只需要建立一個 MedicalDataSource。如果記錄來自多個來源，只要資料經過比對，且所有記錄都有 FHIR 資源類型和 FHIR 資源 ID 的不重複組合，應用程式仍可建立單一 MedicalDataSource。否則，請為每個資料來源建立 MedicalDataSource。

所有病歷都必須與 MedicalDataSource 建立關聯，因此必須先建立這項資源，才能寫入其他資源。

MedicalDataSource 的屬性：

顯示名稱 (必填) - 資料來源的使用者顯示名稱，每個撰寫應用程式的顯示名稱都不得重複。
FHIR 基礎 URI (必填) - 如果資料來自 FHIR 伺服器，這應該是 FHIR 基礎網址 (例如 https://example.com/fhir/)。多個資料來源可以與同一個 FHIR 基礎網址建立關聯。

如果資料是由沒有 FHIR 網址的應用程式產生，這應該是應用程式定義的專屬且可理解的 URI (例如 myapp://..)，指向資料來源。

舉例來說，如果用戶端應用程式支援深層連結，這個深層連結可用做 FHIR 基礎 URI。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 代表 FHIR 資源 (內含醫療記錄) 和中繼資料。

MedicalResource 的屬性：

DataSourceId (必要) - 資料來源，如 MedicalDataSource 所述。
FHIR 版本 (必填) - FHIR 版本。必須是支援的版本。
FHIR 資源 (必要)：採用 JSON 編碼的 FHIR 資源例項。
醫療資源類型 (系統會自動填入) - 資源的使用者面向類別，對應使用者面向權限。

準備 JSON 格式的 FHIR 資源

將醫療資源寫入健康資料同步前，請先準備 JSON 格式的 FHIR 資源記錄。將每個 JSON 儲存在各自的變數中，以便插入為醫療資源。

如需 FHIR JSON 格式的相關協助，請參閱 HL7 機構提供的範例資料。

插入或更新 MedicalResource 記錄

使用 UpsertMedicalResourceRequest 插入新記錄或更新現有記錄，適用於 MedicalDataSource：MedicalResource

// 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 代表有效的 FHIR JSON 字串。

以下是 JSON 的範例，使用 AllergyIntolerance 做為 FHIR 資源類型，這會對應至醫療記錄中的「醫療資源類型」FHIR_RESOURCE_TYPE_ALLERGY_INTOLERANCE：

{
  "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 記錄

系統可能會依 ID 刪除 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)
    )
)