本頁面由 Cloud Translation API 翻譯而成。

決定存取權限

本頁面說明如何使用 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

{
  "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"

{
  "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

{
  "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"
}

回應會包含作業名稱。如要追蹤作業狀態，可以使用 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 稽核記錄」。

決定存取權限 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

針對特定資料元素決定同意聲明存取權

curl

PowerShell

判斷使用者所有同意聲明的存取權

curl

PowerShell

決定同意聲明存放區的存取權限

curl

PowerShell

記錄存取權判斷要求和回應

決定存取權限