Determinazione degli accessi

Questa pagina descrive come eseguire le determinazioni di accesso utilizzando l'API Consent Management.

Le applicazioni possono richiedere determinazioni dell'accesso dall'API Consent Management per un elemento dati specifico, per tutti gli elementi dati associati a un utente o per interi datastore. In ogni caso, l'API Consent Management effettua una determinazione dell'accesso valutando le seguenti informazioni confrontandole con quelle contenute nella richiesta di accesso:

  • Il consenso dell'utente, ad esempio i valori degli attributi REQUEST
  • Le mappature dei dati utente, ad esempio i valori degli attributi RESOURCE.

Per impostazione predefinita, le determinazioni dell'accesso valutano solo i consensi di ACTIVE. I consensi DRAFT possono essere inclusi in una determinazione dell'accesso specificandoli in una richiesta di determinazione dell'accesso.

Le richieste di determinazione dell'accesso ignorano sempre i consensi scaduti, revocati o rifiutati.

Puoi richiedere una determinazione dell'accesso a un elemento di dati specifico utilizzando il metodo projects.locations.datasets.consentStores.checkDataAccess. Questo metodo restituisce un messaggio che indica se l'elemento UserDataMapping specificato ha il consenso valido per l'uso proposto.

Per richiedere una determinazione dell'accesso per un elemento dati specifico, effettua una richiesta POST e specifica le seguenti informazioni nella richiesta:

  • Il nome dell'archivio del consenso dei genitori.
  • Un ID risorsa di dati, ovvero una descrizione dell'elemento di dati, come il percorso REST di una risorsa.
  • Un insieme di coppie chiave-valore che rappresentano il richiedente in termini di attributi REQUEST pertinenti e relativi valori. Ad esempio, requesterIdentity == external-researcher.
  • Un flag facoltativo che indica se devono essere restituite determinazioni di accesso dettagliate. Se questo flag è impostato su FULL, il metodo restituisce i risultati per ogni consenso valutato. Se questo flag viene impostato su BASIC o non viene definito, il metodo restituisce solo se l'accesso ai dati specificati è consentito dai consensi valutati. Questa funzionalità facoltativa viene utilizzata quando l'applicazione deve esaminare le modalità di determinazione del consenso.
  • Un elenco facoltativo di ACTIVE o DRAFT acconsente al metodo da prendere in considerazione. Se non viene specificato alcun consenso, il metodo valuta tutti i consensi relativi a ACTIVE. Questa funzionalità facoltativa può essere utilizzata per testare il comportamento dei consensi nuovi o specifici.
  • Un token di accesso

Curling

L'esempio seguente mostra una richiesta POST che utilizza curl:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
       'dataId' : 'DATA_ID',
       'requestAttributes': {
         'requesterIdentity': 'external-researcher'},
       'consentList':{
         'consents':[
           'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_NAME'
         ]
       },
       'responseView': 'DETAILED_ACCESS_LEVEL'
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:checkDataAccess"

Se la richiesta ha esito positivo, il server restituisce una risposta simile al seguente esempio in formato JSON o un corpo della risposta vuoto se nessun dato utente corrisponde all'accesso ai dati specificato. La risposta di esempio utilizza FULL come responseView.

{
  "consentDetails": {                                                                                                                         "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID": {
      "evaluationResult": "EVALUATION_RESULT"
    }
  }
}

EVALUATION_RESULT è uno di NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY oHAS_SATISFIED_POLICY.

PowerShell

L'esempio seguente mostra una richiesta POST che utilizza Windows PowerShell:

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
       'dataId' : 'DATA_ID',
       'requestAttributes': {
         'requesterIdentity': 'external-researcher'
       },
       'consentList': {
         'consents':[
           'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID'
         ]
       },
       'responseView': 'DETAILED_ACCESS_LEVEL'
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:checkDataAccess" | Select-Object -Expand Content

Se la richiesta ha esito positivo, il server restituisce una risposta simile al seguente esempio in formato JSON o un corpo della risposta vuoto se nessun dato utente corrisponde all'accesso ai dati specificato. La risposta di esempio utilizza FULL come responseView.

{
  "consentDetails": {                                                                                                                         "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID": {
      "evaluationResult": "EVALUATION_RESULT"
    }
  }
}

EVALUATION_RESULT è uno di NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY oHAS_SATISFIED_POLICY.

Decidere l'accesso per tutti i consensi di un utente

Puoi richiedere una determinazione dell'accesso per tutti gli elementi di dati associati a un utente utilizzando il metodo projects.locations.datasets.consentStores.evaluateUserConsents. Questo metodo restituisce tutti gli elementi di dati associati a un utente specifico che hanno il consenso valido per l'uso proposto.

Per richiedere una determinazione dell'accesso per tutti gli elementi di dati associati a un utente, effettua una richiesta POST e specifica le seguenti informazioni nella richiesta:

  • Il nome dell'archivio del consenso dei genitori.
  • Uno User-ID che definisce gli elementi di dati e acconsente alla valutazione.
  • Un insieme facoltativo di coppie chiave-valore che definiscono gli attributi RESOURCE degli elementi di dati da valutare. Ad esempio, dataIdentifiable == de-identified. Se non definisci un insieme di attributi RESOURCE, vengono valutati tutti gli elementi di dati.
  • Un insieme di coppie chiave-valore che definiscono gli attributi REQUEST pertinenti e i relativi valori. Ad esempio, requesterIdentity == external-researcher.
  • Un flag facoltativo che indica se devono essere restituite determinazioni di accesso dettagliate. Se questo flag è impostato su FULL, il metodo restituisce i risultati per ogni consenso valutato. Se questo flag viene impostato su BASIC o non viene definito, il metodo restituisce solo se l'accesso ai dati specificati è consentito dai consensi valutati. Questa funzionalità facoltativa viene utilizzata quando l'applicazione deve esaminare le modalità di determinazione del consenso.
  • Un elenco facoltativo di ACTIVE o DRAFT acconsente al metodo da prendere in considerazione. Se non viene specificato alcun consenso, il metodo valuta tutti i consensi relativi a ACTIVE. Questa funzionalità facoltativa può essere utilizzata per testare il comportamento dei consensi nuovi o specifici.
  • Un token di accesso

Curling

L'esempio seguente mostra una richiesta POST che utilizza curl:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
       'userId' :
         'USER_ID',
       'consentList':{
         'consents':[
           'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID'
         ]
       },
       'resourceAttributes': {
         'dataIdentifiable': 'de-identified'
       },
       'requestAttributes': {
         'requesterIdentity': 'external-researcher'
       },
       'responseView': 'DETAILED_ACCESS_LEVEL'
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:evaluateUserConsents"

Se la richiesta ha esito positivo, il server restituisce una risposta simile al seguente esempio in formato JSON o un corpo della risposta vuoto se nessun dato utente corrisponde all'accesso ai dati specificato. La risposta di esempio utilizza FULL come responseView.

{
  "results": [
    {
      "dataId": "DATA_ID",
      "consentDetails": {
       "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID": {
       "evaluationResult": "EVALUATION_RESULT"
        }
      }
    }
  ]
}

PowerShell

L'esempio seguente mostra una richiesta POST che utilizza Windows PowerShell:

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
       'userId' : 'USER_ID',
       'consentList':{
         'consents':[
           'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_NAME'
         ]
       },
       'resourceAttributes': { 'dataIdentifiable': 'de-identified'},
       'requestAttributes': { 'requesterIdentity': 'external-researcher'},
       'responseView': 'DETAILED_ACCESS_LEVEL'
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:evaluateUserConsents" | Select-Object -Expand Content

Se la richiesta ha esito positivo, il server restituisce una risposta simile al seguente esempio in formato JSON o un corpo della risposta vuoto se nessun dato utente corrisponde all'accesso ai dati specificato. La risposta di esempio utilizza FULL come responseView.

{
  "results": [
    {
      "dataId": "DATA_ID",
      "consentDetails": {
       "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID": {
       "evaluationResult": "EVALUATION_RESULT"
        }
      }
    }
  ]
}

Puoi richiedere una determinazione dell'accesso per un intero archivio di consensi utilizzando il metodo projects.locations.datasets.consentStores.queryAccessibleData. Questo metodo restituisce tutti gli elementi di dati all'interno di un archivio di consenso che hanno un consenso valido.

Per richiedere una determinazione dell'accesso in un intero archivio di consensi, effettua una richiesta POST e specifica le seguenti informazioni nella richiesta:

  • Il nome dell'archivio del consenso dei genitori
  • Un insieme di coppie chiave-valore che definiscono gli attributi REQUEST pertinenti e i relativi valori. Ad esempio, requesterIdentity == external-researcher.
  • Un insieme facoltativo di coppie chiave-valore che definiscono gli attributi RESOURCE degli elementi di dati da valutare. Ad esempio, dataIdentifiable == de-identified. Se non definisci un set di attributi RESOURCE, vengono valutati tutti gli elementi di dati
  • Una destinazione Cloud Storage in cui viene salvato l'elenco dei risultati. L'account di servizio API Cloud Healthcare deve avere il ruolo IAM roles/storage.objectAdmin in questa destinazione. Per maggiori informazioni, consulta la pagina Autorizzazioni di Cloud Storage per l'archiviazione del consenso.
  • Un token di accesso

Curling

L'esempio seguente mostra una richiesta POST che utilizza curl:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
       'gcsDestination': {
         'uriPrefix': 'gs://BUCKET/DIRECTORY'
       },
       'resourceAttributes': {
         'dataIdentifiable': 'de-identified'
       },
       'requestAttributes': {
         'requesterIdentity': 'external-researcher'
       }
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:queryAccessibleData"

Se la richiesta ha esito positivo, il server restituisce una risposta simile al seguente esempio in formato JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

La risposta contiene il nome di un'operazione. Per monitorare lo stato dell'operazione, puoi utilizzare il metodo Operazione get:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

Se la richiesta ha esito positivo, il server restituisce una risposta con lo stato dell'operazione in formato JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.consent.consentService.queryAccessibleData",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME"
    "logsUrl": "LOGS_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Al termine dell'operazione a lunga esecuzione, i risultati vengono visualizzati in un file di testo nella cartella specificata. Per informazioni sulle operazioni a lunga esecuzione, consulta Gestione delle operazioni a lunga esecuzione.

PowerShell

L'esempio seguente mostra una richiesta POST che utilizza Windows PowerShell:

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
       'gcsDestination': {
         'uriPrefix': 'gs://BUCKET/DIRECTORY'
       },
       'resourceAttributes': {
         'dataIdentifiable': 'de-identified'
       },
       'requestAttributes': {
         'requesterIdentity': 'external-researcher'
       }
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:queryAccessibleData" | Select-Object -Expand Content

Se la richiesta ha esito positivo, il server restituisce una risposta simile al seguente esempio in formato JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

La risposta contiene il nome di un'operazione. Per monitorare lo stato dell'operazione, puoi utilizzare il metodo Operazione get:

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

Se la richiesta ha esito positivo, il server restituisce una risposta con lo stato dell'operazione in formato JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.consent.consentService.queryAccessibleData",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME"
    "logsUrl": "LOGS_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Al termine dell'operazione a lunga esecuzione, i risultati vengono visualizzati in un file di testo nella cartella specificata. Per informazioni sulle operazioni a lunga esecuzione, consulta Gestione delle operazioni a lunga esecuzione.

Logging delle richieste e delle risposte di accesso

Se gli audit log degli accessi ai dati sono abilitati, l'API Consent Management registra le richieste effettuate utilizzando i metodi checkDataAccess, evaluateUserConsents e queryAccessibleData. Questi log registrano le informazioni contenute nella richiesta, come l'attributo target UserDataMapping o gli attributi RESOURCE o REQUEST specificati. I log conterranno anche la risposta dell'API, che include il risultato della determinazione dell'accesso all'API di gestione del consenso. Ogni log include l'identità dello strumento Google Cloud che effettua la richiesta.

Per ulteriori informazioni sull'attivazione degli audit log di accesso ai dati, vedi Configurazione degli audit log di accesso ai dati. Per ulteriori informazioni sull'audit logging nell'API Cloud Healthcare, consulta Visualizzazione degli audit log di Cloud.