Questa pagina è stata tradotta dall'API Cloud Translation.

Scrivere dati medici

Questa guida è compatibile con la versione 1.1.0-beta02 di Connessione Salute.

Per scrivere dati medici utilizzando Cartelle cliniche in Connessione Salute, segui questi passaggi:

Verifica la disponibilità delle funzionalità
Richiedere le autorizzazioni di scrittura
Crea un'origine dati (MedicalDataSource)
Scrivere una risorsa medica (MedicalResource)

Disponibilità della funzionalità

Per determinare se il dispositivo di un utente supporta le cartelle cliniche su Health Connect, controlla la disponibilità di FEATURE_PERSONAL_HEALTH_RECORD sul client:

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

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

Per saperne di più, consulta la sezione Verificare la disponibilità delle funzionalità.

Autorizzazioni richieste

La scrittura di dati medici è protetta dalla seguente autorizzazione:

android.permission.health.WRITE_MEDICAL_DATA

Dichiara queste autorizzazioni in Play Console per la tua app, nonché nel manifest dell'app:

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

Sei responsabile della dichiarazione di tutte le autorizzazioni appropriate che intendi utilizzare nei tuoi dispositivi e nelle tue app. Prima dell'utilizzo, devi anche verificare che ogni autorizzazione sia stata concessa dall'utente.

Richiedere le autorizzazioni all'utente

Dopo aver creato un'istanza client, l'app deve richiedere le autorizzazioni all'utente. Gli utenti devono poter concedere o negare le autorizzazioni in qualsiasi momento.

A questo scopo, crea un insieme di autorizzazioni per i tipi di dati richiesti. Assicurati che le autorizzazioni nel set siano dichiarate prima nel file manifest di 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
)

Utilizza getGrantedPermissions per verificare se alla tua app sono già state concesse le autorizzazioni richieste. In caso contrario, utilizza createRequestPermissionResultContract per richiedere queste autorizzazioni. Viene visualizzata la schermata delle autorizzazioni di Connessione Salute.

// 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)
  }
}

Poiché gli utenti possono concedere o revocare le autorizzazioni in qualsiasi momento, la tua app deve controllare periodicamente le autorizzazioni concesse e gestire gli scenari in cui l'autorizzazione viene persa.

Origini dati

Un MedicalDataSource in Connessione Salute rappresenta un'origine dati rivolta agli utenti, ad esempio un'organizzazione sanitaria, un ospedale o un'API.

Le cartelle cliniche memorizzate in Connessione Salute sono organizzate in un MedicalDataSource. Ciò consente la separazione delle cartelle cliniche della stessa persona provenienti da fonti diverse, come API o sistemi sanitari.

Se tutti i record provengono dalla stessa origine, un'app di scrittura deve creare un solo MedicalDataSource. Se i record provengono da più origini, un'app può comunque creare un singolo MedicalDataSource se i dati vengono riconciliati e tutti i record hanno una combinazione univoca di tipo di risorsa FHIR e ID risorsa FHIR. In caso contrario, deve essere creato un MedicalDataSource per ogni origine dati.

Tutte le cartelle cliniche devono essere associate a un MedicalDataSource, quindi questo deve essere creato prima di scrivere le risorse.

Proprietà di MedicalDataSource:

Nome visualizzato (obbligatorio): nome visualizzato rivolto agli utenti per l'origine dati, identificato in modo univoco per app di scrittura.
URI di base FHIR (obbligatorio): per i dati provenienti da un server FHIR, questo deve essere l'URL di base FHIR (ad esempio, https://example.com/fhir/). Più origini dati possono essere associate allo stesso URL di base FHIR.

Se i dati vengono generati da un'app senza un URL FHIR, questo deve essere un URI univoco e comprensibile definito dall'app (ad esempio, myapp://..) che punta all'origine dei dati.

Ad esempio, se un'app client supporta i link diretti, questi link diretti potrebbero essere utilizzati come URI di base FHIR. La lunghezza massima dell'URI è di 2000 caratteri.
Nome del pacchetto (compilato automaticamente): l'app che scrive i dati.
Versione FHIR (obbligatoria): la versione FHIR. Deve essere una versione supportata.

Crea un record MedicalDataSource

Crea un record per ogni organizzazione o entità sanitaria a cui è collegata la tua app.

// 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)
        )
    )

Elimina un record MedicalDataSource

L'esempio precedente restituisce un id dal sistema al momento della creazione. Se devi eliminare il record MedicalDataSource, fai riferimento allo stesso id:

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

Risorse mediche

Un MedicalResource in Connessione Salute rappresenta una risorsa FHIR (che contiene una cartella clinica), insieme ai metadati.

Proprietà di MedicalResource:

DataSourceId (obbligatorio): origine dati come descritta per un MedicalDataSource.
Versione FHIR (obbligatoria): la versione FHIR. Deve essere una versione supportata.
Risorsa FHIR (obbligatoria) L'istanza della risorsa FHIR con codifica JSON.
Tipo di risorsa medica (compilato automaticamente): la categoria visibile all'utente della risorsa, mappata alle autorizzazioni visibili all'utente.

Prepara le risorse FHIR in JSON

Prima di scrivere risorse mediche in Connessione Salute, prepara i record delle risorse FHIR in formato JSON. Memorizza ogni JSON nella propria variabile per l'inserimento come risorsa medica.

Se hai bisogno di aiuto con il formato JSON FHIR, consulta i dati di esempio forniti dall'organizzazione HL7.

Inserisci o aggiorna i record MedicalResource

Utilizza UpsertMedicalResourceRequest per inserire nuovi record o aggiornare quelli esistenti MedicalResource per un 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
            )
        )
    )

Risorsa FHIR di esempio

Nell'esempio precedente, la variabile medicationJsonToInsert rappresentava una stringa JSON FHIR valida.

Ecco un esempio di come potrebbe apparire il JSON, utilizzando AllergyIntolerance come tipo di risorsa FHIR, che corrisponde al tipo di risorsa medica FHIR_RESOURCE_TYPE_ALLERGY_INTOLERANCE in Cartella clinica:

{
  "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"
  }
  ...
}

Elimina un record MedicalResource

MedicalResource record potrebbero essere eliminati per ID:

// 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
        )
    }
)

In alternativa, possono essere eliminati da 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)
    )
)