Tomar decisões de acesso

Esta página descreve como tomar decisões de acesso através da API Consent Management.

As aplicações podem pedir determinações de acesso à API Consent Management para um elemento de dados específico, para todos os elementos de dados associados a um utilizador ou para repositórios de dados completos. Em cada caso, a API Consent Management faz uma determinação de acesso avaliando as seguintes informações em função das informações contidas no pedido de acesso:

  • O consentimento do utilizador, como os valores dos atributos REQUEST
  • Os mapeamentos de dados do utilizador, como os valores dos atributos RESOURCE.

Por predefinição, as determinações de acesso avaliam apenas os consentimentos ACTIVE. Os consentimentos DRAFT podem ser incluídos numa determinação de acesso especificando-os num pedido de determinação de acesso.

Os pedidos de determinação de acesso ignoram sempre os consentimentos expirados, revogados ou rejeitados.

Pode pedir uma determinação de acesso para um elemento de dados específico através do método projects.locations.datasets.consentStores.checkDataAccess. Este método devolve uma mensagem a indicar se o UserDataMapping especificado tem um consentimento válido para a utilização proposta.

Para pedir uma determinação de acesso para um elemento de dados específico, faça um POST pedido e especifique as seguintes informações no pedido:

  • O nome da loja de consentimento parental.
  • Um ID de recurso de dados, que é uma descrição do elemento de dados, como o caminho REST para um recurso.
  • Um conjunto de pares de chave-valor que representam o requerente em termos dos atributos REQUEST relevantes e os respetivos valores. Por exemplo, requesterIdentity == external-researcher.
  • Uma flag opcional que indica se devem ser devolvidas determinações de acesso detalhadas. Se esta flag estiver definida como FULL, o método devolve resultados para cada consentimento avaliado. Se esta flag estiver definida como BASIC ou não estiver definida, o método devolve apenas se o acesso aos dados especificados é permitido pelos consentimentos avaliados. Esta funcionalidade opcional é usada quando a sua aplicação precisa de inspecionar a forma como foi feita uma determinação de consentimento.
  • Uma lista opcional de consentimentos ACTIVE ou DRAFT que o método deve considerar. Se não forem especificados consentimentos, o método avalia todos os consentimentos ACTIVE. Esta funcionalidade opcional pode ser usada para testar o comportamento de consentimentos novos ou específicos.
  • Uma chave de acesso

curl

O exemplo seguinte mostra um pedido POST com 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 o pedido for bem-sucedido, o servidor devolve uma resposta semelhante ao exemplo seguinte no formato JSON ou um corpo de resposta vazio se não existirem dados do utilizador que correspondam ao acesso aos dados especificado. A resposta de exemplo 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 é um dos seguintes valores: NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY ouHAS_SATISFIED_POLICY.

PowerShell

O exemplo seguinte mostra um pedido POST através do 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 o pedido for bem-sucedido, o servidor devolve uma resposta semelhante ao exemplo seguinte no formato JSON ou um corpo de resposta vazio se não existirem dados do utilizador que correspondam ao acesso aos dados especificado. A resposta de exemplo 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 é um dos seguintes valores: NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY ouHAS_SATISFIED_POLICY.

Tomar uma determinação de acesso para todos os consentimentos de um utilizador

Pode pedir uma determinação de acesso para todos os elementos de dados associados a um utilizador através do método projects.locations.datasets.consentStores.evaluateUserConsents. Este método devolve todos os elementos de dados associados a um utilizador específico que tenham um consentimento válido para a utilização proposta.

Para pedir uma determinação de acesso para todos os elementos de dados associados a um utilizador, faça um pedido POST e especifique as seguintes informações no pedido:

  • O nome da loja de consentimento parental.
  • Um ID do utilizador que define os elementos de dados e os consentimentos a avaliar.
  • Um conjunto opcional de pares de chave-valor que definem os RESOURCEatributos dos elementos de dados a avaliar. Por exemplo, dataIdentifiable == de-identified. Se não definir um conjunto de atributos RESOURCE, todos os elementos de dados são avaliados.
  • Um conjunto de pares de chave-valor que definem os atributos relevantes REQUEST e os respetivos valores. Por exemplo, requesterIdentity == external-researcher.
  • Uma flag opcional que indica se devem ser devolvidas determinações de acesso detalhadas. Se esta flag estiver definida como FULL, o método devolve resultados para cada consentimento avaliado. Se esta flag estiver definida como BASIC ou não estiver definida, o método devolve apenas se o acesso aos dados especificados é permitido pelos consentimentos avaliados. Esta funcionalidade opcional é usada quando a sua aplicação precisa de inspecionar a forma como foi feita uma determinação de consentimento.
  • Uma lista opcional de consentimentos ACTIVE ou DRAFT que o método deve considerar. Se não forem especificados consentimentos, o método avalia todos os consentimentos ACTIVE. Esta funcionalidade opcional pode ser usada para testar o comportamento de consentimentos novos ou específicos.
  • Uma chave de acesso

curl

O exemplo seguinte mostra um pedido POST com 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 o pedido for bem-sucedido, o servidor devolve uma resposta semelhante ao exemplo seguinte no formato JSON ou um corpo de resposta vazio se não existirem dados do utilizador que correspondam ao acesso aos dados especificado. A resposta de exemplo usa FULL como o 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

O exemplo seguinte mostra um pedido POST através do 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 o pedido for bem-sucedido, o servidor devolve uma resposta semelhante ao exemplo seguinte no formato JSON ou um corpo de resposta vazio se não existirem dados do utilizador que correspondam ao acesso aos dados especificado. A resposta de exemplo usa FULL como o responseView.

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

Pode pedir uma determinação de acesso para uma loja de consentimento inteira através do método projects.locations.datasets.consentStores.queryAccessibleData. Este método devolve todos os elementos de dados num armazenamento de consentimento que tenham um consentimento válido.

Para solicitar uma determinação de acesso numa loja de consentimento completa, faça um pedido POST e especifique as seguintes informações no pedido:

  • O nome da loja de consentimento parental
  • Um conjunto de pares de chave-valor que definem os atributos relevantes REQUEST e os respetivos valores. Por exemplo, requesterIdentity == external-researcher.
  • Um conjunto opcional de pares de chave-valor que definem os RESOURCEatributos dos elementos de dados a avaliar. Por exemplo, dataIdentifiable == de-identified. Se não definir um conjunto de atributos RESOURCE, todos os elementos de dados são avaliados
  • Um destino do Cloud Storage onde a lista de resultados é guardada. A conta de serviço da API Cloud Healthcare tem de ter a função do IAM neste destino.roles/storage.objectAdmin Para mais informações, consulte o artigo Autorizações do Cloud Storage da loja de consentimento.
  • Uma chave de acesso

curl

O exemplo seguinte mostra um pedido POST com 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 o pedido for bem-sucedido, o servidor devolve uma resposta semelhante ao exemplo seguinte no formato JSON:

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

A resposta contém um nome de operação. Para acompanhar o estado da operação, pode usar o método Operation 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 o pedido for bem-sucedido, o servidor devolve uma resposta com o estado da operação no 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"
  }
}

Após a conclusão da operação de longa duração, os resultados aparecem num ficheiro de texto na pasta que especificou. Para obter informações sobre operações de longa duração, consulte o artigo Gerir operações de longa duração.

PowerShell

O exemplo seguinte mostra um pedido POST através do 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 o pedido for bem-sucedido, o servidor devolve uma resposta semelhante ao exemplo seguinte no formato JSON:

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

A resposta contém um nome de operação. Para acompanhar o estado da operação, pode usar o método Operation 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 o pedido for bem-sucedido, o servidor devolve uma resposta com o estado da operação no 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"
  }
}

Após a conclusão da operação de longa duração, os resultados aparecem num ficheiro de texto na pasta que especificou. Para obter informações sobre operações de longa duração, consulte o artigo Gerir operações de longa duração.

Registar pedidos e respostas de determinação de acesso

Quando os registos de auditoria de acesso aos dados estão ativados, a API Consent Management regista os pedidos feitos através dos métodos checkDataAccess, evaluateUserConsents e queryAccessibleData. Estes registos gravam as informações contidas no pedido, como o destino UserDataMapping ou os atributos RESOURCE ou REQUEST especificados. Os registos também contêm a resposta da API, que inclui o resultado da determinação do acesso à API Consent Management. Cada registo inclui a identidade da Google Cloud ferramenta que faz o pedido.

Para mais informações sobre como ativar os registos de auditoria de acesso a dados, consulte o artigo Configurar registos de auditoria de acesso a dados. Para mais informações sobre o registo de auditoria na Cloud Healthcare API, consulte o artigo Ver registos de auditoria do Cloud.