액세스 권한 결정

이 페이지에서는 Consent Management API를 사용하여 액세스를 결정하는 방법을 설명합니다.

애플리케이션은 특정 데이터 요소, 사용자와 관련된 모든 데이터 요소 또는 전체 데이터 저장소에 대한 Consent Management API에서 액세스 결정을 요청할 수 있습니다. 각각의 경우 Consent Management API는 액세스 요청에 포함된 정보에 대해 다음 정보를 평가하여 액세스 권한을 철회합니다.

  • 사용자 동의(예: REQUEST 속성 값)
  • 사용자 데이터 매핑(예: RESOURCE 속성 값)

기본적으로 액세스 결정은 ACTIVE 동의만 평가합니다. DRAFT 동의는 액세스 결정 요청에 지정하여 액세스 결정에 포함될 수 있습니다.

액세스 결정 요청은 만료, 취소 또는 거부된 동의를 항상 무시합니다.

projects.locations.datasets.consentStores.checkDataAccess 메서드를 사용하여 특정 데이터 요소에 대한 액세스 결정을 요청할 수 있습니다. 이 메서드는 지정된 UserDataMapping에 제안된 사용에 대한 유효한 동의가 있는지 나타내는 메시지를 반환합니다.

특정 데이터 요소에 대한 액세스 결정을 요청하려면 POST 요청을 수행하고 요청에 다음 정보를 지정합니다.

  • 부모 동의 저장소 이름
  • 리소스의 REST 경로와 같은 데이터 요소를 설명하는 데이터 리소스 ID
  • 관련 REQUEST 속성 및 해당 값의 측면에서 요청자를 나타내는 키-값 쌍 세트 예: requesterIdentity == external-researcher
  • 세부 액세스 결정을 반환해야 하는지 여부를 나타내는 선택적 플래그입니다. 이 플래그를 FULL로 설정하면 메서드는 평가된 모든 동의 결과를 반환합니다. 이 플래그가 BASIC으로 설정되거나 정의되지 않은 경우, 이 메서드는 평가된 동의에서 지정된 데이터에 대한 액세스를 허용할지만 반환합니다. 이 선택 기능은 애플리케이션이 동의 결정이 이루어진 방식을 조사해야 하는 경우에 사용합니다.
  • 고려할 메서드에 대한 ACTIVE 또는 DRAFT 동의 목록으로, 선택사항입니다. 동의를 지정하지 않으면 메서드가 모든 ACTIVE 동의를 평가합니다. 이 선택 기능을 사용하여 새로운 동의 또는 특정 동의 동작을 테스트할 수 있습니다.
  • 액세스 토큰

curl

다음 샘플은 curl을 사용하는 POST 요청을 보여줍니다.

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"

요청이 성공하면 서버는 JSON 형식의 다음 샘플과 비슷한 응답을 반환하거나 지정된 데이터 액세스와 일치하는 사용자 데이터가 없는 경우 빈 응답 본문을 반환합니다. 샘플 응답은 FULL을 responseView로 사용합니다.

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

EVALUATION_RESULT는 NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY 또는 HAS_SATISFIED_POLICY 중 하나입니다.

PowerShell

다음 샘플은 Windows PowerShell을 사용한 POST 요청을 보여줍니다.

$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

요청이 성공하면 서버는 JSON 형식의 다음 샘플과 비슷한 응답을 반환하거나 지정된 데이터 액세스와 일치하는 사용자 데이터가 없는 경우 빈 응답 본문을 반환합니다. 샘플 응답은 FULL을 responseView로 사용합니다.

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

EVALUATION_RESULT는 NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY 또는 HAS_SATISFIED_POLICY 중 하나입니다.

사용자의 모든 동의에 대한 액세스 권한 결정

projects.locations.datasets.consentStores.evaluateUserConsents 메서드를 사용하여 사용자와 연결된 모든 데이터 요소에 대한 액세스 결정을 요청할 수 있습니다. 이 메서드는 제안된 사용에 대해 유효한 동의를 받은 특정 사용자와 관련된 모든 데이터 요소를 반환합니다.

사용자와 연결된 모든 데이터 요소에 대한 액세스 결정을 요청하려면 POST 요청을 수행하고 요청에 다음 정보를 지정합니다.

  • 부모 동의 저장소 이름
  • 데이터 요소와 평가할 동의를 정의하는 사용자 ID
  • 평가할 데이터 요소의 RESOURCE 속성을 정의하는 선택적 키-값 쌍 조합. 예를 들면 dataIdentifiable == de-identified입니다. RESOURCE 속성 집합을 정의하지 않으면 모든 데이터 요소가 평가됩니다.
  • 관련 REQUEST 속성과 그 값을 정의하는 키-값 쌍 세트입니다. 예를 들면 requesterIdentity == external-researcher입니다.
  • 세부 액세스 결정을 반환해야 하는지 여부를 나타내는 선택적 플래그입니다. 이 플래그를 FULL로 설정하면 메서드는 평가된 모든 동의 결과를 반환합니다. 이 플래그가 BASIC으로 설정되거나 정의되지 않은 경우, 이 메서드는 평가된 동의에서 지정된 데이터에 대한 액세스를 허용할지만 반환합니다. 이 선택 기능은 애플리케이션이 동의 결정이 이루어진 방식을 조사해야 하는 경우에 사용합니다.
  • 고려할 메서드에 대한 ACTIVE 또는 DRAFT 동의 목록으로, 선택사항입니다. 동의를 지정하지 않으면 메서드가 모든 ACTIVE 동의를 평가합니다. 이 선택 기능을 사용하여 새로운 동의 또는 특정 동의 동작을 테스트할 수 있습니다.
  • 액세스 토큰

curl

다음 샘플은 curl을 사용하는 POST 요청을 보여줍니다.

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"

요청이 성공하면 서버는 JSON 형식의 다음 샘플과 비슷한 응답을 반환하거나 지정된 데이터 액세스와 일치하는 사용자 데이터가 없는 경우 빈 응답 본문을 반환합니다. 샘플 응답은 FULL을 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

다음 샘플은 Windows PowerShell을 사용한 POST 요청을 보여줍니다.

$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

요청이 성공하면 서버는 JSON 형식의 다음 샘플과 비슷한 응답을 반환하거나 지정된 데이터 액세스와 일치하는 사용자 데이터가 없는 경우 빈 응답 본문을 반환합니다. 샘플 응답은 FULL을 responseView로 사용합니다.

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

projects.locations.datasets.consentStores.queryAccessibleData 메서드를 사용하여 전체 동의 저장소에 대한 액세스 결정을 요청할 수 있습니다. 이 메서드는 유효한 동의가 있는 동의 저장소 내의 모든 데이터 요소를 반환합니다.

전체 동의 저장소에 대한 액세스 결정을 요청하려면 POST 요청을 수행하고 요청에 다음 정보를 지정합니다.

  • 부모 동의 저장소 이름
  • 관련 REQUEST 속성과 그 값을 정의하는 키-값 쌍 세트입니다. 예를 들면 requesterIdentity == external-researcher입니다.
  • 평가할 데이터 요소의 RESOURCE 속성을 정의하는 선택적 키-값 쌍 조합. 예를 들면 dataIdentifiable == de-identified입니다. RESOURCE 속성 집합을 정의하지 않으면 모든 데이터 요소가 평가됩니다.
  • 결과 목록이 저장되는 Cloud Storage 대상. Cloud Healthcare API 서비스 계정에는 이 대상에 대한 roles/storage.objectAdmin IAM 역할이 있어야 합니다. 자세한 내용은 동의 저장소 Cloud Storage 권한을 참조하세요.
  • 액세스 토큰

curl

다음 샘플은 curl을 사용하는 POST 요청을 보여줍니다.

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"

요청이 성공하면 서버는 다음 샘플과 비슷한 응답을 JSON 형식으로 반환합니다.

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

응답에 작업 이름이 포함됩니다. 작업 상태를 추적하려면 작업 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"

요청이 성공하면 서버는 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"
  }
}

장기 실행 작업이 완료되면 지정한 폴더의 텍스트 파일에 결과가 나타납니다. 장기 실행 작업에 대한 자세한 내용은 장기 실행 작업 관리를 참조하세요.

PowerShell

다음 샘플은 Windows PowerShell을 사용한 POST 요청을 보여줍니다.

$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

요청이 성공하면 서버는 다음 샘플과 비슷한 응답을 JSON 형식으로 반환합니다.

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

응답에 작업 이름이 포함됩니다. 작업 상태를 추적하려면 작업 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

요청이 성공하면 서버는 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"
  }
}

장기 실행 작업이 완료되면 지정한 폴더의 텍스트 파일에 결과가 나타납니다. 장기 실행 작업에 대한 자세한 내용은 장기 실행 작업 관리를 참조하세요.

로깅 액세스 결정 요청 및 응답

데이터 액세스 감사 로그가 사용 설정된 경우 checkDataAccess, evaluateUserConsents, queryAccessibleData 메서드를 사용하여 Consent Management API 로그 요청이 수행됩니다. 이러한 로그는 대상 UserDataMapping 또는 지정된 RESOURCE 또는 REQUEST 속성과 같이 요청에 포함된 정보를 기록합니다. 또한 로그에는 Consent Management API 액세스 결정의 결과를 포함하는 API 응답이 포함됩니다. 각 로그에는 요청을 수행하는 Google Cloud 도구의 ID가 포함됩니다.

데이터 액세스 감사 로그 사용 설정에 대한 자세한 내용은 데이터 액세스 감사 로그 구성을 참조하세요. Cloud Healthcare API의 감사 로깅에 대한 자세한 내용은 Cloud 감사 로그 보기를 참조하세요.