本頁面說明如何使用 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"
}
}
長時間執行的作業完成後，結果會顯示在您指定的資料夾中。如要瞭解長時間執行的作業，請參閱「管理長時間執行的作業」。
記錄存取權判斷要求和回應
啟用資料存取稽核記錄後，Consent Management API 會記錄使用 checkDataAccess、evaluateUserConsents 和 queryAccessibleData 方法提出的要求。這些記錄會記錄要求中包含的資訊，例如目標 UserDataMapping 或指定的 RESOURCE 或 REQUEST 屬性。記錄也會包含 API 回應，其中包含 Consent Management API 存取權判定的結果。每筆記錄都會包含發出要求的 Google Cloud 工具身分。
如要進一步瞭解如何啟用資料存取稽核記錄，請參閱「設定資料存取稽核記錄」一文。如要進一步瞭解 Cloud Healthcare API 中的稽核記錄，請參閱「查看 Cloud 稽核記錄」。