本页面介绍如何使用 Consent Management API 进行访问权限判定。
应用可以针对某个数据元素、与某个用户关联的所有数据元素或整个数据存储区从 Consent Management API 请求访问权限判定。在每种情况下，Consent Management API 都会根据访问权限请求中包含的信息评估以下信息，从而做出访问权限判定：
- 用户许可，例如
REQUEST特性的值 - 用户数据映射，例如
RESOURCE特性的值。
默认情况下，访问权限判定仅评估 ACTIVE 许可。如需在访问权限判定中包括 DRAFT 许可，可以在访问权限判定请求中直接指定它们。
访问权限判定请求会始终忽略已过期、已撤消或已拒绝的许可。
针对特定数据元素进行许可访问权限判定
您可以使用 projects.locations.datasets.consentStores.checkDataAccess 方法请求针对特定数据元素进行访问权限判定。此方法会返回一个消息，表明指定的 UserDataMapping 是否具有拟议用途的有效许可。
要请求针对特定数据元素进行访问权限判定，请发出 POST 请求并在请求中指定以下信息：
- 父许可存储区的名称。
- 数据资源 ID，这是对数据元素的描述，例如资源的 REST 路径。
- 一组使用相关
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.objectAdminIAM 角色。如需了解详情，请参阅许可存储区 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"
}
响应包含操作名称。要跟踪操作的状态，您可以使用 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"
如果请求成功，服务器将以 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"
}
响应包含操作名称。要跟踪操作的状态，您可以使用 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
如果请求成功，服务器将以 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"
}
}
长时间运行的操作完成后，结果会显示在指定文件夹中的文本文件中。如需了解长时间运行的操作，请参阅管理长时间运行的操作。
Logging 访问确定请求和响应
启用数据访问审核日志后，Consent Management API 会记录使用 checkDataAccess、evaluateUserConsents 和 queryAccessibleData 方法发出的请求。这些日志会记录请求中包含的信息，例如目标 UserDataMapping 或指定的 RESOURCE 或 REQUEST 特性。日志还包含 API 响应，其中包括 Consent Management API 访问确定结果。每个日志均包含发出请求的 Google Cloud 工具的身份。
如需详细了解如何启用数据访问审核日志，请参阅配置数据访问审核日志。如需详细了解 Cloud Healthcare API 中的审核日志记录，请参阅查看 Cloud Audit Logs。