本頁面說明如何設定同意聲明政策和屬性。
同意聲明管理 API 會使用同意聲明政策,代表使用者或透過機構指南授予的同意聲明。同意聲明政策是consent
資源的構成要素。每個 consent
資源最多可包含 10 項同意聲明政策。同意聲明政策包含 RESOURCE
屬性 (說明政策適用對象) 和 REQUEST
屬性 (定義授權規則,決定政策生效條件)。如要進一步瞭解同意聲明政策,請參閱政策表示法。
Consent Management API 會使用屬性定義同意聲明和隱私權分類,讓同意聲明儲存區能夠瞭解。屬性是用來描述儲存的同意聲明和管理的資料。存取權判斷要求也會使用屬性來描述提出的要求。
attributeDefinition
資源是同意聲明存放區中的資源,可決定 Consent Management API 可處理哪些同意聲明屬性。同意聲明存放區最多可包含 200 個屬性定義資源。每個屬性定義都具有下列其中一種屬性類型:
RESOURCE
屬性是指值是由資料或動作的屬性決定的屬性。例如資料是否經過去識別化或可識別。這類屬性用於說明同意聲明政策的適用對象、說明向user data mappings
註冊的資料,以及將部分存取權判斷要求的範圍縮小至特定類別的資源。REQUEST
屬性是指值由要求者的身分或目的決定的屬性。例如,經同意可使用這類資料的專業人員,像是研究人員或照護人員。這類屬性可用於編寫同意聲明政策的授權規則,以及在存取權判斷要求中指定建議用途。
attributeDefinition
資源代表單一屬性,最多可有 500 個屬性值。屬性值代表屬性可能的值。如需範例,請參閱「政策表示法」。
隨著時間推移,您可以為屬性定義新增其他屬性值,但無法移除。系統會強制執行屬性定義的參照完整性,因為這與 consent
資源相關。也就是說,如果同意聲明資源的最新修訂版本參照屬性定義,則無法變更或刪除屬性定義的部分欄位。
下圖顯示在新同意聲明存放區中建立同意聲明屬性的程序:
如要建立同意聲明和隱私權分類所需的全部屬性定義,請重複「建立 RESOURCE
屬性定義」和「建立 REQUEST
屬性定義」中顯示的程序。
建立 RESOURCE
屬性定義
如要建立 RESOURCE
屬性定義,請使用 projects.locations.datasets.consentStores.attributeDefinitions.create
方法。提出 POST
要求,並在要求中指定下列資訊:
- 父項同意商店的名稱。
- 屬性定義的名稱,在父項同意聲明存放區中不得重複。 名稱可包含任何大小寫字母、數字和底線,不得為一般運算語言 (CEL) 中的保留關鍵字。
- 屬性類別,在本例中為
RESOURCE
- 這項屬性可能代表的值
- 存取權杖
curl
以下範例顯示使用 curl
的 POST
要求,該要求會建立名為 data_identifiable
的 RESOURCE
屬性,並包含 identifiable
和 de-identified
值:
curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/consent+json; charset=utf-8" \ --data "{ 'description': 'whether the data is identifiable', 'category': 'RESOURCE', 'allowed_values': [ 'identifiable', 'de-identified' ], }" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=data_identifiable"
如果要求成功,伺服器會以 JSON 格式傳回類似以下範例的回應:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/data_identifiable", "description": "whether the data is identifiable", "category": "RESOURCE", "allowedValues": [ "identifiable", "de-identified" ] }
PowerShell
以下範例顯示使用 Windows PowerShell 的 POST
要求,該要求會建立名為 data_identifiable
的 RESOURCE
屬性,並包含 identifiable
和 de-identified
值:
$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 "{ 'description': 'whether the data is identifiable', 'category': 'RESOURCE', 'allowed_values': [ 'identifiable', 'de-identified' ] }" ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=data_identifiable" | Select-Object -Expand Content
如果要求成功,伺服器會以 JSON 格式傳回類似以下範例的回應:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/data_identifiable", "description": "whether the data is identifiable", "category": "RESOURCE", "allowedValues": [ "identifiable", "de-identified" ] }
Python
建立 REQUEST
屬性定義
如要建立 REQUEST
屬性定義,請使用 projects.locations.datasets.consentStores.attributeDefinitions.create
方法。提出 POST
要求,並在要求中指定下列資訊:
- 父項同意商店的名稱。
- 屬性定義的名稱,在父項同意聲明存放區中不得重複。 名稱可以是 1 到 256 個字元的任何 Unicode 字串,包含數字、字母、底線、破折號和半形句號,但開頭不得為數字。
- 屬性類別,在本例中為
REQUEST
。 - 這個屬性可能代表的值。
- 這組預設值可套用至同意聲明政策 (選用)。為這個欄位設定值後,如果同意聲明政策未指定這項屬性,同意聲明儲存空間就會假設政策包含這項屬性和值。只有在您的用途特別需要時,才應設定這個欄位。
- 存取權杖。
curl
以下範例顯示使用 curl
的 POST
要求,該要求會建立名為 requester_identity
的 REQUEST
屬性:
curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/consent+json; charset=utf-8" \ --data "{ 'description': 'what groups are consented for access', 'category': 'REQUEST', 'allowed_values': ['internal-researcher', 'external-researcher', 'clinical-admin'], }" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=requester_identity"
如果要求成功,伺服器會以 JSON 格式傳回類似以下範例的回應:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/requester_identity", "description": "what groups are consented for access", "category": "REQUEST", "allowedValues": [ "internal-researcher", "external-researcher", "clinical-admin" ] }
PowerShell
下列範例顯示如何使用 Windows PowerShell 提出 POST
要求,建立名為 requester_identity
的 REQUEST
屬性:
$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 "{ 'description': 'what groups are consented for access', 'category': 'REQUEST', 'allowed_values': ['internal-researcher', 'external-researcher', 'clinical-admin'] }" ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions?attribute_definition_id=requester_identity" | Select-Object -Expand Content
如果要求成功,伺服器會以 JSON 格式傳回類似以下範例的回應:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/requester_identity", "description": "what groups are consented for access", "category": "REQUEST", "allowedValues": [ "internal-researcher", "external-researcher", "clinical-admin" ] }
Python
編輯屬性定義
REST
使用任何要求資料之前,請先替換以下項目:
- PROJECT_ID:您的 Google Cloud 專案 ID
- LOCATION:資料集位置
- DATASET_ID:資料集 ID
- CONSENT_STORE_ID:同意聲明商店 ID
- ATTRIBUTE_DEFINITION_ID:屬性定義 ID
- DESCRIPTION:屬性的說明
JSON 要求主體:
{ "description": "DESCRIPTION" }
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 request.json
的檔案中。
在終端機中執行下列指令,在目前目錄中建立或覆寫這個檔案:
cat > request.json << 'EOF' { "description": "DESCRIPTION" } EOF
接著,請執行下列指令來傳送 REST 要求:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/ATTRIBUTE_DEFINITION_ID?updateMask=description"
PowerShell
將要求主體儲存在名為 request.json
的檔案中。
在終端機中執行下列指令,在目前目錄中建立或覆寫這個檔案:
@' { "description": "DESCRIPTION" } '@ | Out-File -FilePath request.json -Encoding utf8
接著,請執行下列指令來傳送 REST 要求:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/ATTRIBUTE_DEFINITION_ID?updateMask=description" | Select-Object -Expand Content
APIs Explorer
複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求內文貼到這項工具中,並填妥其他必填欄位,然後按一下「Execute」(執行)。
您應該會收到如下的 JSON 回應:
Python
取得屬性定義
REST
使用任何要求資料之前,請先替換以下項目:
- PROJECT_ID:您的 Google Cloud 專案 ID
- LOCATION:資料集位置
- DATASET_ID:資料集 ID
- CONSENT_STORE_ID:同意聲明商店 ID
- ATTRIBUTE_DEFINITION_ID:屬性定義 ID
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/ATTRIBUTE_DEFINITION_ID"
PowerShell
執行下列指令:
$cred = gcloud auth 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/consentStores/CONSENT_STORE_ID/attributeDefinitions/ATTRIBUTE_DEFINITION_ID" | Select-Object -Expand Content
APIs Explorer
開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位,然後按一下「執行」。
您應該會收到如下的 JSON 回應:
Python
列出屬性定義
REST
使用任何要求資料之前,請先替換以下項目:
- PROJECT_ID:您的 Google Cloud 專案 ID
- LOCATION:資料集位置
- DATASET_ID:資料集 ID
- CONSENT_STORE_ID:同意聲明商店 ID
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions"
PowerShell
執行下列指令:
$cred = gcloud auth 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/consentStores/CONSENT_STORE_ID/attributeDefinitions" | Select-Object -Expand Content
APIs Explorer
開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位,然後按一下「執行」。
您應該會收到如下的 JSON 回應:
Python
刪除屬性定義
REST
使用任何要求資料之前,請先替換以下項目:
- PROJECT_ID:您的 Google Cloud 專案 ID
- LOCATION:資料集位置
- DATASET_ID:資料集 ID
- CONSENT_STORE_ID:同意聲明商店 ID
- ATTRIBUTE_DEFINITION_ID:屬性定義 ID
如要傳送要求,請選擇以下其中一個選項:
curl
執行下列指令:
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/ATTRIBUTE_DEFINITION_ID"
PowerShell
執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/attributeDefinitions/ATTRIBUTE_DEFINITION_ID" | Select-Object -Expand Content
APIs Explorer
開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位,然後按一下「執行」。
您應該會收到如下的 JSON 回應: