Creazione e aggiornamento dei consensi degli utenti

In questa pagina viene descritto come creare, aggiornare e revocare i consensi degli utenti.

La tua applicazione registra separatamente gli artefatti e i consensi. L'API Consent Management archivia i dati sensibili relativi al consenso di un utente come ConsentArtifact. Un ConsentArtifact può includere timestamp delle firme e immagini di firme o altri documenti che fungono da "prova" del consenso.

L'API Consent Management archivia i dati sul consenso non sensibili come oggetti Consent. Un Consent include un ID utente opaco, le norme relative al consenso concesse dall'utente e lo stato delle norme relative al consenso.

Poiché i consensi e gli artefatti del consenso hanno percorsi delle risorse distinti, le relative autorizzazioni possono essere impostate in modo indipendente per ridurre al minimo l'accesso ai dati sensibili relativi al consenso negli artefatti del consenso.

I consensi supportano una durata di scadenza che ti consente di configurare quando un consenso scade e non è più valido. La durata della scadenza può essere impostata su una data o un periodo di tempo specifici, ad esempio un anno.

Durante la creazione dell'archivio di consensi, puoi configurare una durata predefinita per la scadenza. Durante la creazione del consenso, puoi configurare una durata del consenso. La durata della scadenza impostata durante la creazione del consenso sostituisce la durata predefinita impostata per l'archivio di consensi.

I consensi possono essere creati in stato ACTIVE o DRAFT. I consensi nello stato ACTIVE vengono utilizzati dall'API Consent Management per determinare le modalità di accesso. I consensi in stato DRAFT vengono utilizzati nelle determinazioni dell'accesso solo se specificato in una richiesta di determinazione dell'accesso. Puoi cambiare lo stato da DRAFT a ACTIVE o REJECTED aggiornando il consenso.

Per registrare il consenso di un utente, crea un artefatto per il consenso utilizzando il metodo projects.locations.datasets.consentStores.consentArtifacts.create e poi collegalo a un artefatto per il consenso creato utilizzando il metodo projects.locations.datasets.consentStores.consents.create.

Gli esempi in questa pagina presuppongono che tu abbia creato un archivio di consensi e configurato le norme relative al consenso.

Creazione di un artefatto del consenso

Un artefatto per il consenso archivia i dati sensibili relativi al consenso di un utente. Un artefatto per il consenso può includere le informazioni di contatto di un utente, i timestamp delle firme e immagini delle firme o altri documenti che fungono da "prova" del consenso.

Per creare un artefatto del consenso, utilizza il metodo projects.locations.datasets.consentStores.consentArtifacts.create. Effettua una richiesta POST e specifica le seguenti informazioni nella richiesta:

Il nome dell'archivio di consensi principale.
Un ID utente univoco e opaco che rappresenta l'utente che ha fornito il consenso.
La firma dell'utente, inclusi facoltativamente l'immagine della firma, il timestamp e altri metadati. Questa immagine può essere specificata come posizione dell'immagine in Cloud Storage o come stringa di byte non elaborati.
Una firma facoltativa di un tutore o di un testimone.
Immagini o documenti facoltativi che fungono da "prova" del consenso, ad esempio un'immagine della firma, immagini che acquisiscono le schermate di un flusso di consenso mobile o un documento PDF firmato. Queste immagini possono essere specificate come posizione in Cloud Storage o come stringa di byte non elaborati.
Un identificatore per le informazioni sul consenso mostrate all'utente.
Metadati facoltativi relativi al consenso dell'utente.
Un token di accesso.

Il seguente esempio 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 "{
       'user_id': 'USER_ID',
       'user_signature' : {
         'user_id': 'USER_ID',
         'image': {
           'gcs_uri': 'gs://IMG_URI' },
         'signature_time': {
           'seconds': EPOCH_SECONDS },
      },
       'consent_content_screenshots': [
         { 'raw_bytes': 'BASE_64_IMAGE' }],
       'consent_content_version': 'v1',
       'metadata': {'client': 'mobile'}
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts"

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/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_RESOURCE_ID",
  "userId": "USER_ID",
  "userSignature": {
    "userId": "USER_ID",
    "signatureTime": "SIGNATURE_TIME"
  },
  "consentContentVersion": "v1",
  "metadata": {
    "client": "mobile"
  }
}

Il seguente esempio mostra una richiesta POST mediante 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 "{
       'user_id': 'USER_ID',
       'user_signature' : {
         'user_id': 'USER_ID',
         'image': {
           'gcs_uri': 'gs://IMG_URI' },
         'signature_time': {
           'seconds': EPOCH_SECONDS }
      },
       'consent_content_screenshots': [
         { 'raw_bytes': 'BASE_64_IMAGE' }],
       'consent_content_version': 'v1',
       'metadata': {'client': 'mobile'}
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_RESOURCE_ID",
  "userId": "USER_ID",
  "userSignature": {
    "userId": "USER_ID",
    "signatureTime": "SIGNATURE_TIME"
  },
  "consentContentVersion": "v1",
  "metadata": {
    "client": "mobile"
  }
}

Creare un consenso

Un consenso archivia dati non sensibili, inclusi gli ID utente opachi, le norme sul consenso concesse dagli utenti e se queste ultime sono attualmente valide.

Per creare un consenso, usa il metodo projects.locations.datasets.consentStores.consents.create. Effettua una richiesta POST e specifica le seguenti informazioni nella richiesta:

Il nome dell'archivio di consensi principale.
Un ID utente univoco e opaco che rappresenta l'utente che ha fornito il consenso.
Fino a 10 criteri di consenso, ciascuno con un insieme di valori degli attributi RESOURCE e una regola di autorizzazione espressa in Common Expression Language (CEL) che descrive l'intenzione dell'utente con le definizioni degli attributi create in precedenza. Si applicano le seguenti limitazioni al CEL:
- Puoi definire solo un massimo di 10 operatori logici per criterio.
- Puoi utilizzare solo gli operatori AND (&&), OR (||) e IN.
Il percorso REST dell'artefatto per il consenso corrispondente (restituito al momento della creazione dell'artefatto per il consenso).
Uno stato del consenso facoltativo, DRAFT o ACTIVE. Se non specifichi lo stato, il consenso viene creato nello stato ACTIVE.
Una durata di scadenza facoltativa per il consenso, definita come data o periodo di tempo. Questo valore deve essere specificato in secondi e come suffisso con la lettera s. Ad esempio, 86000s. Questo valore sostituisce la durata della scadenza configurata per l'archivio di consensi. Se non configuri una scadenza, la risorsa eredita la durata predefinita della scadenza dall'archivio di consensi. Se non è specificata una durata di scadenza per la risorsa o per l'archivio, la risorsa di consenso non scade.
Un token di accesso.

Il seguente esempio 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 "{
       \"user_id\": \"USER_ID\",
       \"policies\": [{
         \"resource_attributes\": [{
           \"attribute_definition_id\": \"data_identifiable\",
           \"values\": [\"identifiable\"]
         }],
         \"authorization_rule\": {
           \"expression\": \"requester_identity == 'clinical-admin'\",
        }
       },
       {
         \"resource_attributes\": [{
           \"attribute_definition_id\": \"data_identifiable\",
           \"values\": [\"de-identified\"]
         }],
         \"authorization_rule\": {
           \"expression\": \"requester_identity in ['internal-researcher', 'external-researcher']\"
          }
       }],
       \"consent_artifact\": \"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID\",
       \"ttl\": \"EXPIRATION_DURATION\"
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents"

Se la richiesta ha esito positivo, il server restituisce una risposta simile all'esempio seguente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
  "userId": "USER_ID",
  "policies": [
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "identifiable"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity == 'clinical-admin'"
      }
    },
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "de-identified"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
      }
    }
  ],
  "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
  "state": "CONSENT_STATE",
  "stateChangeTime": "STATE_CHANGE_TIME",
  "expireTime": "EXPIRE_TIME"
}

Il seguente esempio mostra una richiesta POST mediante 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 "{
       'user_id': 'USER_ID',
       'policies': [{
         'resource_attributes': [{
           'attribute_definition_id': 'data_identifiable',
           'values': ['identifiable']
         }],
         'authorization_rule': {
           'expression': 'requester_identity == \'clinical-admin\'',
        }
       },{
         'resource_attributes': [{
           'attribute_definition_id': 'data_identifiable',
           'values': ['de-identified']
         }],
         'authorization_rule': {
           'expression': 'requester_identity in [\'internal-researcher\', \'external-researcher\']'
          }
       }],
       'consent_artifact': 'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID',
       'ttl': 'EXPIRATION_DURATION'
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents" | Select-Object -Expand Content

Se la richiesta ha esito positivo, il server restituisce una risposta simile all'esempio seguente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
  "userId": "USER_ID",
  "policies": [
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "identifiable"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity == 'clinical-admin'"
      }
    },
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "de-identified"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
      }
    }
  ],
  "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
  "state": "CONSENT_STATE",
  "stateChangeTime": "STATE_CHANGE_TIME",
  "expireTime": "EXPIRE_TIME"
}

Ottenere un consenso

I seguenti esempi mostrano come ottenere un consenso. Per maggiori informazioni, consulta projects.locations.datasets.consentStores.consents.get.

Per ottenere un consenso, effettua una richiesta GET e specifica le seguenti informazioni nella richiesta:

Il nome del set di dati padre
Il nome dell'archivio di consensi
Il nome del consenso
Un token di accesso

Il seguente esempio mostra una richiesta GET che utilizza curl:

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/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID"

Se la richiesta ha esito positivo, il server restituisce la risposta in formato JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
  "userId": "USER_ID",
  "policies": [
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "identifiable"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity == 'clinical-admin'"
      }
    },
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "de-identified"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
      }
    }
  ],
  "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
  "state": "CONSENT_STATE",
  "stateChangeTime": "STATE_CHANGE_TIME",
  "revisionCreateTime": "REVISION_CREATE_TIME",
  "expireTime": "EXPIRE_TIME"
}

Il seguente esempio mostra una richiesta GET mediante Windows PowerShell:

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

Invoke-RestMethod `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID" | ConvertTo-Json

Se la richiesta ha esito positivo, il server restituisce la risposta in formato JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
  "userId": "USER_ID",
  "policies": [
    {
      "resourceAttributes": "",
      "authorizationRule": "@{expression=requester_identity == 'clinical-admin'}"
    },
    {
      "resourceAttributes": "",
      "authorizationRule": "@{expression=requester_identity in ['internal-researcher', 'external-researcher']}"
    }
  ],
  "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
  "state": "CONSENT_STATE",
  "stateChangeTime": "STATE_CHANGE_TIME",
  "revisionCreateTime": "REVISION_CREATE_TIME",
  "expireTime": "EXPIRE_TIME"
}

Elencare i consensi in un archivio di consensi

Gli esempi riportati di seguito mostrano come elencare i consensi in un archivio di consensi.

Per elencare i consensi in un archivio di consensi, utilizza il metodo projects.locations.datasets.consentStores.consents.list.

Per elencare i consensi in un archivio di consensi, effettua una richiesta GET e specifica le seguenti informazioni:

Il nome dell'archivio di consensi principale
Un filtro di ricerca facoltativo per recuperare i consensi in base a ID utente, stato, ora di creazione o artefatto del consenso
Un token di accesso

Il seguente esempio mostra una richiesta GET che utilizza curl.

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/consentStores/CONSENT_STORE_ID/consents"

Se la richiesta ha esito positivo, il server restituisce la risposta in formato JSON:

{
  "consents": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
      "userId": "USER_ID",
      "policies": [
        {
          "resourceAttributes": [
            {
              "attributeDefinitionId": "data_identifiable",
              "values": [
                "identifiable"
              ]
            }
          ],
          "authorizationRule": {
            "expression": "requester_identity == 'clinical-admin'"
          }
        },
        {
          "resourceAttributes": [
            {
              "attributeDefinitionId": "data_identifiable",
              "values": [
                "de-identified"
              ]
            }
          ],
          "authorizationRule": {
            "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
          }
        }
      ],
      "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
      "state": "CONSENT_STATE",
      "stateChangeTime": "STATE_CHANGE_TIME",
      "revisionCreateTime": "REVISION_CREATE_TIME",
      "expireTime": "EXPIRE_TIME"
    },
    {
      ...
    }
  ]
}

Per elencare i consensi in un archivio di consensi, effettua una richiesta GET e specifica le seguenti informazioni:

Il nome del set di dati padre
Un filtro di ricerca facoltativo per recuperare i consensi in base a ID utente, stato, ora di creazione o artefatto del consenso
Un token di accesso

L'esempio seguente mostra una richiesta GET mediante Windows PowerShell.

$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/consentStores/CONSENT_STORE_ID/consents" | Select-Object -Expand Content

Se la richiesta ha esito positivo, il server restituisce la risposta in formato JSON:

{
  "consents": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
      "userId": "USER_ID",
      "policies": [
        {
          "resourceAttributes": [
            {
              "attributeDefinitionId": "data_identifiable",
              "values": [
                "identifiable"
              ]
            }
          ],
          "authorizationRule": {
            "expression": "requester_identity == 'clinical-admin'"
          }
        },
        {
          "resourceAttributes": [
            {
              "attributeDefinitionId": "data_identifiable",
              "values": [
                "de-identified"
              ]
            }
          ],
          "authorizationRule": {
            "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
          }
        }
      ],
      "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
      "state": "CONSENT_STATE",
      "stateChangeTime": "STATE_CHANGE_TIME",
      "revisionCreateTime": "REVISION_CREATE_TIME",
      "expireTime": "EXPIRE_TIME"
    },
    {
      ...
    }
  ]
}

Puoi anche elencare le revisioni di un consenso specifico utilizzando il metodo projects.locations.datasets.consentStores.consents.listRevisions.

Aggiornamento dei consensi

Nel tempo potrebbe essere necessario aggiornare lo stato dei consensi. Per farlo, puoi cambiare lo stato del consenso. Ogni aggiornamento e cambiamento di stato genera una nuova revisione del consenso. Le revisioni precedenti sono accessibili aggiungendo @{revision_id} al nome della risorsa del consenso.

Aggiornamento dei consensi

Per aggiornare i campi userId, policies, consentArtifact o revokeConsentArtifact di un consenso attivo o in bozza, utilizza il metodo projects.locations.datasets.consentStores.consents.patch. Viene eseguito il commit di una nuova revisione con le modifiche e viene impostata sullo stato attuale.

Per aggiornare un consenso, effettua una richiesta PATCH e specifica le seguenti informazioni nella richiesta:

Il percorso REST del consenso da aggiornare
I campi da aggiornare
Una maschera di aggiornamento
Un token di accesso

Il seguente esempio mostra una richiesta PATCH che utilizza curl che aggiorna l'elemento del consenso:

curl -X PATCH \
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
       \"consentArtifact\": \"projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID\"
       }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID?updateMask=consentArtifact"

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/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
  "userId": "USER_ID",
  "policies": [
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "identifiable"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity == 'clinical-admin'"
      }
    },
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "de-identified"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
      }
    }
  ],
  "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
  "state": "ACTIVE",
  "stateChangeTime": "STATE_CHANGE_TIME",
  "revisionCreateTime": "REVISION_CREATE_TIME",
  "expireTime": "EXPIRE_TIME"
}

Il seguente esempio mostra una richiesta PATCH mediante Windows PowerShell che aggiorna l'artefatto per il consenso:

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

Invoke-WebRequest `
  -Method Patch `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
       'consentArtifact': 'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID'
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID?updateMask=consentArtifact" | 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/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
  "userId": "USER_ID",
  "policies": [
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "identifiable"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity == 'clinical-admin'"
      }
    },
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "de-identified"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
      }
    }
  ],
  "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
  "state": "ACTIVE",
  "stateChangeTime": "STATE_CHANGE_TIME",
  "revisionCreateTime": "REVISION_CREATE_TIME",
  "expireTime": "EXPIRE_TIME"
}

Attivazione dei consensi

Per cambiare lo stato di un consenso da DRAFT a ACTIVE dopo che l'utente ha accettato il consenso, utilizza il metodo projects.locations.datasets.consentStores.consents.activateConsent. È stata eseguita il commit di una nuova revisione con lo stato ACTIVE. Quando lo stato del consenso è ACTIVE, il consenso viene incluso nelle richieste di determinazione dell'accesso.

Per attivare un consenso, effettua una richiesta POST e specifica le seguenti informazioni nella richiesta:

Il percorso REST del consenso per l'attivazione
Il percorso REST di un artefatto facoltativo per documentare il motivo per cui il consenso è stato attivato
Un token di accesso

Il seguente esempio 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 "{
       'consent_artifact': 'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/userConsentArtifacts/CONSENT_ARTIFACT_RESOURCE_ID' \
       }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID:activate"

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/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
  "userId": "USER_ID",
  "policies": [
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "identifiable"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity == 'clinical-admin'"
      }
    },
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "de-identified"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
      }
    }
  ],
  "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
  "state": "ACTIVE",
  "stateChangeTime": "STATE_CHANGE_TIME",
  "expireTime": "EXPIRE_TIME"
}

Il seguente esempio mostra una richiesta POST mediante 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 "{
       'consent_artifact': '/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/userConsentArtifacts/CONSENT_ARTIFACT_ID'
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID:activate" | 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/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
  "userId": "USER_ID",
  "policies": [
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "identifiable"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity == 'clinical-admin'"
      }
    },
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "de-identified"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
      }
    }
  ],
  "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
  "state": "ACTIVE",
  "stateChangeTime": "STATE_CHANGE_TIME",
  "expireTime": "EXPIRE_TIME"
}

Revoca e rifiuto dei consensi

Per cambiare lo stato di un consenso da DRAFT a REJECTED, ad esempio, se l'utente indica che il consenso non è accettabile, utilizza il metodo projects.locations.datasets.consentStores.consents.reject. Quando lo stato di un consenso è REJECTED, il consenso non è incluso nelle richieste di determinazione dell'accesso.

Per cambiare lo stato di un consenso da ACTIVE a REVOKED, ad esempio se un utente richiede l'annullamento di un consenso concesso in precedenza, utilizza il metodo projects.locations.datasets.consentStores.consents.revoke. È stata eseguita il commit di una nuova revisione con lo stato REVOKED. I consensi con stato REVOKED non sono inclusi nelle richieste di determinazione dell'accesso. Puoi creare un elemento facoltativo associato al consenso per documentare il motivo per cui il consenso è stato revocato. La revoca di un consenso non elimina il consenso.

Per revocare un consenso, effettua una richiesta POST e specifica le seguenti informazioni nella richiesta:

Il percorso REST del consenso da revocare
Il percorso REST di un artefatto facoltativo per documentare il motivo per cui il consenso è stato revocato
Un token di accesso

Il seguente esempio 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 "{}" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID:revoke"

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/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
  "userId": "USER_ID",
  "policies": [
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "identifiable"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity == 'clinical-admin'"
      }
    },
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "de-identified"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
      }
    }
  ],
  "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
  "state": "REVOKED",
  "stateChangeTime": "STATE_CHANGE_TIME",
  "expireTime": "EXPIRE_TIME"
}

Il seguente esempio mostra una richiesta POST mediante 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 "{}" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID:revoke" | 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/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID",
  "userId": "USER_ID",
  "policies": [
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "identifiable"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity == 'clinical-admin'"
      }
    },
    {
      "resourceAttributes": [
        {
          "attributeDefinitionId": "data_identifiable",
          "values": [
            "de-identified"
          ]
        }
      ],
      "authorizationRule": {
        "expression": "requester_identity in ['internal-researcher', 'external-researcher']"
      }
    }
  ],
  "consentArtifact": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consentArtifacts/CONSENT_ARTIFACT_ID",
  "state": "REVOKED",
  "stateChangeTime": "STATE_CHANGE_TIME",
  "expireTime": "EXPIRE_TIME"
}