Realizar determinaciones de acceso

En esta página, se describe cómo realizar determinaciones de acceso con la API de administración de consentimientos.

Las aplicaciones pueden solicitar determinaciones de acceso desde la API de administración de consentimientos para un elemento de datos específico, para todos los elementos de datos asociados con un usuario o para almacenes de datos completos. En cada caso, la API de administración de consentimientos toma una determinación de acceso mediante la evaluación de la siguiente información en relación con la información contenida en la solicitud de acceso:

  • El consentimiento del usuario, como los valores de los atributos REQUEST
  • Las asignaciones de datos del usuario, como los valores de los atributos RESOURCE

De forma predeterminada, las determinaciones de acceso solo evalúan los consentimientos de ACTIVE. Los consentimientos DRAFT se pueden incluir en una determinación de acceso. Para esto, se especifican en una solicitud de determinación de acceso.

Las solicitudes de determinación de acceso siempre ignoran los consentimientos vencidos, revocados o rechazados.

Puedes solicitar una determinación de acceso para un elemento de datos específico con el método projects.locations.datasets.consentStores.checkDataAccess. Este método muestra un mensaje que indica si el UserDataMapping especificado tiene un consentimiento válido para el uso propuesto.

Para solicitar una determinación de acceso para un elemento de datos específico, realiza una solicitud POST y especifica la siguiente información en la solicitud:

  • El nombre del almacén del consentimiento principal
  • Un ID de recurso de datos, que es una descripción del elemento de datos, como la ruta de acceso de REST a un recurso
  • Un conjunto de pares clave-valor que representan al solicitante en términos de los atributos REQUEST relevantes y sus valores. Por ejemplo, requesterIdentity == external-researcher
  • Una marca opcional que indica si se deben mostrar determinaciones de acceso detalladas Si esta marca se establece como FULL, el método muestra resultados para cada consentimiento evaluado. Si esta marca se establece en BASIC o no se define, el método solo muestra si los consentimientos evaluados permiten el acceso a los datos especificados. Esta función opcional se usa cuando tu aplicación necesita inspeccionar cómo se tomó una determinación de consentimiento.
  • Una lista opcional de consentimientos ACTIVE o DRAFT para que el método considere. Si no se especifican consentimientos, el método evalúa todos los consentimientos ACTIVE. Esta función opcional se puede usar para probar el comportamiento de consentimientos nuevos o específicos.
  • Un token de acceso

curl

En el siguiente ejemplo, se muestra una solicitud POST mediante 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"

Si la solicitud se realiza correctamente, el servidor muestra una respuesta similar a la siguiente en formato JSON, o bien un cuerpo de respuesta vacío si ningún dato del usuario coincide con el acceso a los datos especificado. La respuesta de muestra usa FULL como responseView.

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

EVALUATION_RESULT: Es uno de NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY o HAS_SATISFIED_POLICY.

PowerShell

En el siguiente ejemplo, se muestra una solicitud 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 "{
       '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

Si la solicitud se realiza correctamente, el servidor muestra una respuesta similar a la siguiente en formato JSON, o bien un cuerpo de respuesta vacío si ningún dato del usuario coincide con el acceso a los datos especificado. La respuesta de muestra usa FULL como responseView.

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

EVALUATION_RESULT: Es uno de NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY o HAS_SATISFIED_POLICY.

Toma una determinación del acceso para todos los consentimientos de un usuario

Puedes solicitar una determinación de acceso para todos los elementos de datos asociados con un usuario mediante el método projects.locations.datasets.consentStores.evaluateUserConsents. Este método muestra todos los elementos de datos asociados con un usuario específico que tienen un consentimiento válido para el uso propuesto.

Para solicitar una determinación de acceso para todos los elementos de datos asociados a un usuario, realiza una solicitud POST y especifica la siguiente información en la solicitud:

  • El nombre del almacén del consentimiento principal
  • Un ID de usuario que define los elementos y los consentimientos de datos que se deben evaluar
  • Un conjunto opcional de pares clave-valor que definen los atributos RESOURCE de los elementos de datos que se deben evaluar Por ejemplo, dataIdentifiable == de-identified. Si no defines un conjunto de atributos RESOURCE, se evalúan todos los elementos de datos.
  • Un conjunto de pares clave-valor que definen los atributos REQUEST relevantes y sus valores. Por ejemplo, requesterIdentity == external-researcher
  • Una marca opcional que indica si se deben mostrar determinaciones de acceso detalladas Si esta marca se establece como FULL, el método muestra resultados para cada consentimiento evaluado. Si esta marca se establece en BASIC o no se define, el método solo muestra si los consentimientos evaluados permiten el acceso a los datos especificados. Esta función opcional se usa cuando tu aplicación necesita inspeccionar cómo se tomó una determinación de consentimiento.
  • Una lista opcional de consentimientos ACTIVE o DRAFT para que el método considere. Si no se especifican consentimientos, el método evalúa todos los consentimientos ACTIVE. Esta función opcional se puede usar para probar el comportamiento de consentimientos nuevos o específicos.
  • Un token de acceso

curl

En el siguiente ejemplo, se muestra una solicitud POST mediante 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"

Si la solicitud se realiza correctamente, el servidor muestra una respuesta similar a la siguiente en formato JSON, o bien un cuerpo de respuesta vacío si ningún dato del usuario coincide con el acceso a los datos especificado. La respuesta de muestra usa FULL como 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

En el siguiente ejemplo, se muestra una solicitud 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 "{
       '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

Si la solicitud se realiza correctamente, el servidor muestra una respuesta similar a la siguiente en formato JSON, o bien un cuerpo de respuesta vacío si ningún dato del usuario coincide con el acceso a los datos especificado. La respuesta de muestra usa FULL como responseView.

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

Puedes solicitar una determinación de acceso para un almacén de consentimientos completo con el método projects.locations.datasets.consentStores.queryAccessibleData. Este método muestra todos los elementos de datos dentro de un almacén de consentimientos que tienen un consentimiento válido.

Para solicitar una determinación de acceso en un almacén de consentimientos completo, realiza una solicitud POST y especifica la siguiente información en la solicitud:

  • El nombre de la tienda de consentimientos principales
  • Un conjunto de pares clave-valor que definen los atributos REQUEST relevantes y sus valores. Por ejemplo, requesterIdentity == external-researcher
  • Un conjunto opcional de pares clave-valor que definen los atributos RESOURCE de los elementos de datos que se deben evaluar Por ejemplo, dataIdentifiable == de-identified. Si no defines un conjunto de atributos RESOURCE, se evalúan todos los elementos de datos.
  • Un destino de Cloud Storage en el que se guarda la lista de resultados. La cuenta de servicio de la API de Cloud Healthcare debe tener la función de IAM roles/storage.objectAdmin en este destino. Para obtener más información, consulta Permisos de Cloud Storage del almacén de consentimientos.
  • Un token de acceso

curl

En el siguiente ejemplo, se muestra una solicitud POST mediante 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"

Si la solicitud tiene éxito, en el servidor se mostrará una respuesta similar a la siguiente muestra en formato JSON:

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

La respuesta contiene un nombre de operación. Para realizar un seguimiento del estado de la operación, puedes usar el método get de la operación:

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"

Si la solicitud es exitosa, el servidor mostrará una respuesta con el estado de la operación en 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"
  }
}

Una vez completada la operación de larga duración, los resultados aparecen en un archivo de texto en la carpeta que especificaste. Para obtener información sobre las operaciones de larga duración, consulta Administra operaciones de larga duración.

PowerShell

En el siguiente ejemplo, se muestra una solicitud 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 "{
       '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

Si la solicitud tiene éxito, en el servidor se mostrará una respuesta similar a la siguiente muestra en formato JSON:

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

La respuesta contiene un nombre de operación. Para realizar un seguimiento del estado de la operación, puedes usar el método get de la operación:

$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

Si la solicitud es exitosa, el servidor mostrará una respuesta con el estado de la operación en 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"
  }
}

Una vez completada la operación de larga duración, los resultados aparecen en un archivo de texto en la carpeta que especificaste. Para obtener información sobre las operaciones de larga duración, consulta Administra operaciones de larga duración.

Cómo registrar solicitudes y respuestas de determinación de acceso

Cuando los registros de auditoría de acceso a los datos están habilitados, la API de Consent Management registra las solicitudes realizadas con checkDataAccess, evaluateUserConsents y queryAccessibleData. Estos registros registran la información que contiene la solicitud, como la UserDataMapping de destino o los atributos RESOURCE o REQUEST especificados. Los registros también contendrán la respuesta de la API, que incluye el resultado de la determinación del acceso a la API de Consent Management. Cada registro incluye la identidad de la herramienta de Google Cloud que realiza la solicitud.

Para obtener más información sobre cómo habilitar los registros de auditoría de acceso a los datos, consulta Configura registros de auditoría de acceso a los datos. Para obtener más información sobre el registro de auditoría en la API de Cloud Healthcare, consulta Visualiza los registros de auditoría de Cloud.