Como determinar o acesso

Nesta página, descrevemos como fazer determinações de acesso usando a API de consentimento.

Os aplicativos podem solicitar determinações de acesso à API Consent Management para um elemento de dados específico, para todos os elementos de dados associados a um usuário ou para armazenamentos de dados inteiros. Em cada caso, a API Consent Management faz uma determinação de acesso ao avaliar as seguintes informações em relação às informações contidas na solicitação de acesso:

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

Por padrão, as determinações de acesso só avaliam os consentimentos ACTIVE. DRAFT Os consentimentos podem ser incluídos em uma determinação do acesso especificando-os em uma solicitação de determinação do acesso.

As solicitações de determinação do acesso sempre ignoram os consentimentos que foram expirados, revogados ou rejeitados.

É possível solicitar uma determinação de acesso para um elemento de dados específico usando o método projects.locations.datasets.consentStores.checkDataAccess. Esse método retorna uma mensagem indicando se a UserDataMapping especificada tem consentimento válido para o uso proposto.

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

  • É o nome do repositório de consentimento dos responsáveis.
  • 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 solicitante em termos dos atributos REQUEST relevantes e seus valores. Por exemplo, requesterIdentity == external-researcher.
  • Uma sinalização opcional que indica se as determinações de acesso detalhadas serão retornadas. Se essa sinalização for definida como FULL, o método retornará resultados para cada consentimento avaliado. Se essa sinalização for definida como BASIC, ou não for definida, o método retornará apenas se o acesso aos dados especificados for permitido pelos consentimentos avaliados. Esse recurso opcional é usado quando o aplicativo precisa inspecionar como uma determinação de consentimento foi feita.
  • Uma lista opcional de consentimentos ACTIVE ou DRAFT para o método considerar. Se nenhum consentimento for especificado, o método avaliará todos os consentimentos ACTIVE. Esse recurso opcional pode ser usado para testar o comportamento de consentimentos novos ou específicos.
  • Um token de acesso

curl

O exemplo a seguir mostra uma solicitação POST usando 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 a solicitação for bem-sucedida, o servidor retornará uma resposta semelhante à seguinte amostra no formato JSON ou um corpo de resposta vazio se nenhum dado do usuário corresponder ao acesso de dados especificado. A resposta de amostra 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 campos NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY ou HAS_SATISFIED_POLICY.

PowerShell

O exemplo a seguir mostra uma solicitação POST usando o 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 a solicitação for bem-sucedida, o servidor retornará uma resposta semelhante à seguinte amostra no formato JSON ou um corpo de resposta vazio se nenhum dado do usuário corresponder ao acesso de dados especificado. A resposta de amostra 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 campos NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY ou HAS_SATISFIED_POLICY.

Como determinar o acesso de todos os consentimentos de um usuário

É possível solicitar uma determinação de acesso para todos os elementos de dados associados a um usuário usando o método projects.locations.datasets.consentStores.evaluateUserConsents. Esse método retorna todos os elementos de dados associados a um usuário específico que têm o consentimento válido para o uso proposto.

Para solicitar uma determinação de acesso a todos os elementos de dados associados a um usuário, faça uma solicitação POST e especifique as seguintes informações na solicitação:

  • É o nome do repositório de consentimento dos responsáveis.
  • Um ID de usuário que define os elementos de dados e os consentimentos a serem avaliados.
  • Um conjunto opcional de pares de chave-valor que definem os atributos RESOURCE dos elementos de dados a serem avaliados. Por exemplo, dataIdentifiable == de-identified. Se você não definir um conjunto de atributos RESOURCE, todos os elementos de dados serão avaliados.
  • Um conjunto de pares de chave-valor que definem os atributos REQUEST relevantes e os respectivos valores. Por exemplo, requesterIdentity == external-researcher.
  • Uma sinalização opcional que indica se as determinações de acesso detalhadas serão retornadas. Se essa sinalização for definida como FULL, o método retornará resultados para cada consentimento avaliado. Se essa sinalização for definida como BASIC, ou não for definida, o método retornará apenas se o acesso aos dados especificados for permitido pelos consentimentos avaliados. Esse recurso opcional é usado quando o aplicativo precisa inspecionar como uma determinação de consentimento foi feita.
  • Uma lista opcional de consentimentos ACTIVE ou DRAFT para o método considerar. Se nenhum consentimento for especificado, o método avaliará todos os consentimentos ACTIVE. Esse recurso opcional pode ser usado para testar o comportamento de consentimentos novos ou específicos.
  • Um token de acesso

curl

O exemplo a seguir mostra uma solicitação POST usando 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 a solicitação for bem-sucedida, o servidor retornará uma resposta semelhante à seguinte amostra no formato JSON ou um corpo de resposta vazio se nenhum dado do usuário corresponder ao acesso de dados especificado. A resposta de amostra 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

O exemplo a seguir mostra uma solicitação POST usando o 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 a solicitação for bem-sucedida, o servidor retornará uma resposta semelhante à seguinte amostra no formato JSON ou um corpo de resposta vazio se nenhum dado do usuário corresponder ao acesso de dados especificado. A resposta de amostra 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"
        }
      }
    }
  ]
}

É possível solicitar uma determinação de acesso para um repositório de consentimentos inteiro usando o método projects.locations.datasets.consentStores.queryAccessibleData. Esse método retorna todos os elementos de dados em um repositório de consentimentos que tenham consentimento válido.

Para solicitar uma determinação de acesso em todo o repositório de consentimentos, faça uma solicitação POST e especifique as seguintes informações na solicitação:

  • O nome do repositório de consentimentos dos responsáveis
  • Um conjunto de pares de chave-valor que definem os atributos REQUEST relevantes e os respectivos valores. Por exemplo, requesterIdentity == external-researcher.
  • Um conjunto opcional de pares de chave-valor que definem os atributos RESOURCE dos elementos de dados a serem avaliados. Por exemplo, dataIdentifiable == de-identified. Se você não definir um conjunto de atributos RESOURCE, todos os elementos de dados serão avaliados
  • Um destino do Cloud Storage em que a lista de resultados é salva. A conta de serviço da API Cloud Healthcare precisa ter o papel roles/storage.objectAdmin do IAM neste destino. Para mais informações, consulte Permissões de armazenamento do consentimento do Cloud Storage.
  • Um token de acesso

curl

O exemplo a seguir mostra uma solicitação POST usando 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 a solicitação for bem-sucedida, o servidor retornará uma resposta semelhante à seguinte amostra 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 rastrear o status da operação, use o método get de operação:

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 a solicitação for bem-sucedida, o servidor retornará uma resposta com o status 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"
  }
}

Depois que a operação de longa duração for concluída, os resultados serão exibidos em um arquivo de texto na pasta especificada. Para informações sobre operações de longa duração, consulte Como gerenciar operações de longa duração.

PowerShell

O exemplo a seguir mostra uma solicitação POST usando o 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 a solicitação for bem-sucedida, o servidor retornará uma resposta semelhante à seguinte amostra 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 rastrear o status da operação, use o método get de operação:

$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 a solicitação for bem-sucedida, o servidor retornará uma resposta com o status 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"
  }
}

Depois que a operação de longa duração for concluída, os resultados serão exibidos em um arquivo de texto na pasta especificada. Para informações sobre operações de longa duração, consulte Como gerenciar operações de longa duração.

Como gerar registros de solicitações e respostas de determinação de acesso

Quando os registros de auditoria de acesso a dados estão ativados, as solicitações da API Consent Management usam a checkDataAccess, o evaluateUserConsents e queryAccessibleData. Esses registros registram as informações contidas na solicitação, como o UserDataMapping de destino ou os atributos de RESOURCE ou REQUEST especificados. Os registros também contêm a resposta da API, que inclui o resultado da determinação de acesso da API Consent Management. Cada registro inclui a identidade da ferramenta do Google Cloud que fez a solicitação.

Para mais informações sobre como ativar registros de auditoria de acesso a dados, consulte Como configurar registros de auditoria de acesso a dados. Para mais informações sobre registros de auditoria na API Cloud Healthcare, consulte Como visualizar registros de auditoria do Cloud.