本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 什麼是 AWS Clean Rooms？ AWS Clean Rooms 可協助您和合作夥伴分析和協作您的集合資料集，以獲得新的洞見，而無需向彼此揭露基礎資料。 AWS Clean Rooms 是一個安全的協作工作區，您可以在幾分鐘內建立自己的無塵室，只需幾個步驟即可分析集合資料集。您可以選擇要與其合作的合作夥伴、選取其資料集，並為這些合作夥伴設定隱私權增強控制。 透過 AWS Clean Rooms，您可以與數千家已使用 的公司協作 AWS。協同合作不需要將資料移出 AWS 或載入至其他雲端服務供應商。當您執行查詢或任務時， 會從該資料的原始位置 AWS Clean Rooms 讀取資料，並套用內建分析規則，以協助您維持對該資料的控制。 AWS Clean Rooms 提供您可以設定的內建資料存取控制和稽核支援控制。這些控制項包括： + 限制 SQL 查詢並提供輸出限制的[分析規則](analysis-rules.md)。 + [密碼編譯運算 Clean Rooms](crypto-computing.md)可保持資料加密，即使處理查詢也一樣，以符合嚴格的資料處理政策。 + [分析日誌](query-logs.md)以檢閱 中的查詢和任務 AWS Clean Rooms ，並協助支援稽核。 + 防止使用者識別嘗試的不同[隱私權](differential-privacy.md)。 AWS Clean Rooms 差異隱私權是一種全受管功能，可透過數學支援的技術和直覺式控制來保護使用者的隱私權，只需幾個步驟即可套用。 + [AWS Clean Rooms ML](machine-learning.md) 允許雙方在其資料中識別類似的使用者，而無需彼此共用其資料。第一方會從訓練資料建立和設定類似模型。然後，種子資料會帶入協同合作，以建立類似訓練資料的外觀客群。 以下影片會詳細說明 AWS Clean Rooms。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/0S6icreVCO0/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/0S6icreVCO0) ## 您是第一次 AWS Clean Rooms 使用嗎？ 如果您是第一次使用 AWS Clean Rooms，建議您先閱讀以下章節： + [AWS Clean Rooms 運作方式](#how-it-works) + [存取 AWS Clean Rooms](#accessing-service) + [設定 AWS Clean Rooms](setting-up.md) + [AWS Clean Rooms 詞彙表](glossary.md) ## AWS Clean Rooms 運作方式 在 中 AWS Clean Rooms，您可以建立協同合作並新增要邀請 AWS 帳戶 的 ，或建立成員資格來加入您獲邀請的協同合作。然後，您可以連結使用案例所需的資料資源：為事件資料設定的資料表、為 ML 建模設定的模型，或為實體解析設定的 ID 命名空間。您可以選擇建立或核准分析範本，以預先同意您希望在協同合作中允許的確切查詢和任務。最後，您可以透過在設定的資料表上執行 SQL 查詢或 PySpark 任務、在 ID 映射資料表中執行實體解析，或使用 ML 建模來產生外觀相似的受眾客群來分析關節資料。 下圖顯示 AWS Clean Rooms 的運作方式。 ![\[說明如何 AWS Clean Rooms 運作的圖表\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/images/how-it-works.png) ## 相關服務 ### AWS 服務 下列 AWS 服務 與 相關 AWS Clean Rooms： + **Amazon Athena** 協作成員可以將他們帶入的資料儲存 AWS Clean Rooms 為 Amazon Athena 中的 AWS Glue Data Catalog 檢視。如需詳細資訊，請參閱下列主題： 如需詳細資訊，請參閱下列主題： [為 中的查詢準備資料表 AWS Clean Rooms](prepare-data.md) [建立設定的資料表 – Amazon Athena 資料來源](create-config-table-athena.md) 《[Amazon Athena 使用者指南》中的什麼是](https://docs.aws.amazon.com/athena/latest/ug/what-is.html) *Amazon Athena*？ + **CloudFormation** 在 中建立下列資源 CloudFormation：協同合作、設定的資料表、設定的資料表關聯和成員資格 如需詳細資訊，請參閱[使用 建立 AWS Clean Rooms 資源 AWS CloudFormation](creating-resources-with-cloudformation.md)。 + **AWS CloudTrail** 使用 AWS Clean Rooms 搭配 CloudTrail 日誌來增強活動分析 AWS 服務 。 如需詳細資訊，請參閱[使用 記錄 AWS Clean Rooms API 呼叫 AWS CloudTrail](logging-using-cloudtrail.md)。 + **AWS Entity Resolution** 使用 AWS Clean Rooms 搭配 AWS Entity Resolution 來執行實體解析。 如需詳細資訊，請參閱[AWS Entity Resolution 在 中 AWS Clean Rooms](working-with-entity-resolution.md)。 + **AWS Glue** 協作成員可以從 Amazon S3 中的資料建立 AWS Glue 資料表，以便在 中使用 AWS Clean Rooms。 如需詳細資訊，請參閱下列主題： [為 中的查詢準備資料表 AWS Clean Rooms](prepare-data.md) 《AWS Glue 開發人員指南》**中的[什麼是 AWS Glue？](https://docs.aws.amazon.com/glue/latest/dg/what-is-glue.html) + **Amazon Simple Storage Service (Amazon S3)** 協同合作成員可以存放他們在 Amazon S3 AWS Clean Rooms 中帶入的資料。 如需詳細資訊，請參閱下列主題： [為 中的查詢準備資料表 AWS Clean Rooms](prepare-data.md) [建立設定的資料表 – Amazon S3 資料來源](create-config-table-s3.md) 《Amazon Simple Storage Service 使用者指南》**中的[什麼是 Amazon S3？](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) + **AWS Secrets Manager** 協同合作成員可以建立秘密，以存取和讀取存放在 Snowflake 中的資料。 如需詳細資訊，請參閱下列主題： [建立服務角色以從 Snowflake 讀取資料](setting-up-roles.md#create-service-role-third-party) [為 中的查詢準備資料表 AWS Clean Rooms](prepare-data.md) 《AWS Secrets Manager 使用者指南》**中的[什麼是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) ### 第三方服務 下列第三方服務與 相關 AWS Clean Rooms： + **Snowflake** 協同合作成員可以將他們帶入 AWS Clean Rooms Snowflake 倉儲的資料存放。 如需詳細資訊，請參閱下列主題： [為 中的查詢準備資料表 AWS Clean Rooms](prepare-data.md) [建立設定的資料表 – Snowflake 資料來源](create-config-table-snowflake.md) ## 存取 AWS Clean Rooms 您可以透過 AWS Clean Rooms 下列選項存取 ： + 直接透過 AWS Clean Rooms 主控台前往 https：//[https://console.aws.amazon.com/cleanrooms/](https://console.aws.amazon.com/cleanrooms/)。 + 透過 AWS Clean Rooms API 以程式設計方式進行。如需詳細資訊，請參閱 [https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html)。 ## 的定價 AWS Clean Rooms 如需定價資訊，請參閱 [AWS Clean Rooms 定價](https://aws.amazon.com/clean-rooms/pricing/)。 **注意** 對於與存放在 Snowflake 中的資料相關聯的協同合作成員，每次執行使用存放在這些位置的資料的查詢時，都會由其各自的資料倉儲供應商或雲端供應商向您收取資料輸出和運算的費用。 ## 的帳單 AWS Clean Rooms AWS Clean Rooms 讓協同合作建立者能夠指定哪些成員在協同合作中支付查詢或任務運算成本。 在大多數情況下，[可以查詢的成員](glossary.md#glossary-member-who-can-query)和[支付查詢運算成本的成員](glossary.md#glossary-member-paying-for-query-compute)是相同的。不過，如果可以查詢的成員和支付查詢運算成本的成員不同，則當可以查詢的成員根據自己的成員資源執行查詢時，會向支付查詢運算成本的成員的成員成員資源收費。 支付查詢運算成本的成員不會在其 CloudTrail 事件歷史記錄中看到正在執行查詢的任何事件，因為付款人不是執行查詢的人員，也不是執行查詢的資源擁有者。不過，付款人會看到其成員資源針對可在協同合作中執行查詢之成員執行的所有查詢所產生的費用。 如需如何建立協同合作並設定成員支付查詢運算成本的詳細資訊，請參閱 [建立協同合作](create-collaboration.md)。 # 中的分析規則 AWS Clean Rooms 協作成員必須設定*分析規則*，才能在 中使用資料表 AWS Clean Rooms 進行協作分析。 分析規則是每個資料擁有者在已設定的資料表上設定的隱私權增強控制。分析規則決定如何分析設定的資料表。 分析規則是已設定資料表 （帳戶層級資源） 上的帳戶層級控制項，並在已設定資料表相關聯的任何協同合作中強制執行。如果未設定分析規則，則設定的資料表可以與協同合作相關聯，但無法查詢。查詢只能參考具有相同分析規則類型的已設定資料表。 若要設定分析規則，請先選取分析類型，然後指定分析規則。對於這兩個步驟，您應該考慮要啟用的使用案例，以及如何保護基礎資料。 AWS Clean Rooms 在查詢中參考的所有已設定資料表之間強制執行更嚴格的控制。 下列範例說明限制性控制。 **Example 限制性控制：輸出限制** + 協作器 A 的識別符資料欄具有 100 的輸出限制。 + 協作器 B 在識別符資料欄上具有 150 的輸出限制。 參考兩個已設定資料表的彙總查詢在輸出列中至少需要 150 個不同的識別符值，才能顯示在查詢輸出中。查詢輸出不會指出由於輸出限制而移除結果。 **Example 限制性控制：分析範本未核准** + 協作者 A 已允許具有查詢的分析範本，該查詢參考其自訂分析規則中來自協作者 A 和協作者 B 的已設定資料表。 + 協作者 B 不允許分析範本。 由於協作者 B 不允許分析範本，因此可以查詢的成員無法執行該分析範本。 ## 分析規則類型 分析規則有三種類型：[彙總](analysis-rules-aggregation.md)、[列出](analysis-rules-list.md)和[自訂](analysis-rules-custom.md)。下表比較分析規則類型。每種類型都有單獨的區段，描述指定分析規則。 **注意** 有一個稱為 ID 映射表分析規則的分析規則類型。不過，此分析規則是由 管理 AWS Clean Rooms ，無法修改。如需詳細資訊，請參閱[ID 映射表分析規則](analysis-rules-id-mapping-table.md)。 下列各節說明每個分析規則類型的支援使用案例和控制項。 ### 支援的使用案例 下表顯示每個分析規則類型的支援使用案例比較摘要。 | 使用案例 | [彙總](analysis-rules-aggregation.md) | [清單](analysis-rules-list.md) | [Custom (自訂)](analysis-rules-custom.md) | | --- | --- | --- | --- | | 支援的分析 | 使用 COUNT、SUM 和 AVG 函數沿著選用維度彙總統計資料的查詢 | 輸出多個資料表之間重疊之資料列層級清單的查詢 | 只要分析範本或分析建立者已檢閱並允許，任何自訂分析 | | 常見使用案例 | 區段分析、測量、屬性 | 擴充、區段建置 | 第一次接觸歸因、增量分析、受眾探索 | | SQL 建構 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules.html) | 大多數 SQL 函數和 SQL 建構可透過 SELECT 命令使用 | | 子查詢和通用資料表表達式 (CTEs) | 否 | 否 | 是 | | 分析範本 | 否 | 否 | 是 | ### 支援的控制項 下表顯示每個分析規則類型如何保護基礎資料的比較摘要。 | 控制項 | [彙總](analysis-rules-aggregation.md) | [清單](analysis-rules-list.md) | [Custom (自訂)](analysis-rules-custom.md) | | --- | --- | --- | --- | | 控制機制 | 控制如何在查詢中使用資料表中的資料*（例如，允許資料欄 hashed\$1email 的 COUNT 和 SUM。)* | 控制如何在查詢中使用資料表中的資料*（例如，僅允許將資料欄 hashed\$1email 用於聯結。)* | 控制允許在資料表上執行的查詢*（例如，僅允許分析範本「自訂查詢 1」中定義的查詢。)* | | 內建隱私權增強技術 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules.html) | | 檢閱查詢，然後才能執行 | 否 | 否 | 是，使用分析範本 | 如需 中可用分析規則的詳細資訊 AWS Clean Rooms，請參閱下列主題。 + [彙總分析規則](analysis-rules-aggregation.md) + [列出分析規則](analysis-rules-list.md) + [中的自訂分析規則 AWS Clean Rooms](analysis-rules-custom.md) # 彙總分析規則 在 中 AWS Clean Rooms，*彙總分析規則*會沿著選用維度使用 COUNT、SUM 和/或 AVG 函數產生彙總統計資料。當彙總分析規則新增至設定的資料表時，可讓可查詢的成員在設定的資料表上執行查詢。 彙總分析規則支援行銷活動規劃、媒體觸及、頻率測量和歸因等使用案例。 支援的查詢結構和語法在 中定義[彙總查詢結構和語法](#agg-query-structure-syntax)。 中定義的分析規則參數[彙總分析規則 - 查詢控制項](#agg-query-controls)包括查詢控制項和查詢結果控制項。其查詢控制項包含要求已設定資料表加入至少一個由成員擁有且可直接或暫時查詢的已設定資料表的能力。此要求可讓您確保查詢在資料表及其交集 (INNERJOIN) 上執行。 ## 彙總查詢結構和語法 具有彙總分析規則之資料表的查詢必須遵循下列語法。 ``` --select_aggregate_function_expression SELECT aggregation_function(column_name) [[AS] column_alias ] [, ...] --select_grouping_column_expression [, {column_name|scalar_function(arguments)} [[AS] column_alias ]][, ...] --table_expression FROM table_name [[AS] table_alias ] [[INNER] JOIN table_name [[AS] table_alias] ON join_condition] [...] --where_expression [WHERE where_condition] --group_by_expression [GROUP BY {column_name|scalar_function(arguments)}, ...]] --having_expression [HAVING having_condition] --order_by_expression [ORDER BY {column_name|scalar_function(arguments)} [{ASC|DESC}]] [,...]] ``` 下表說明上述語法中列出的每個表達式。 | 表達式 | 定義 | 範例 | | --- | --- | --- | | select\$1aggregate\$1function\$1expression | 逗號分隔清單，其中包含下列表達式： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules-aggregation.html) `select_aggregation_function_expression` 中必須至少有一個 `select_aggregate_expression`。 | `SELECT SUM(PRICE), user_segment` | | select\$1aggregation\$1function\$1expression | 套用到一或多個資料欄的一或多個支援彙總函數。僅允許資料欄做為彙總函數的引數。 `select_aggregation_function_expression` 中必須至少有一個 `select_aggregate_expression`。 | `AVG(PRICE)` `COUNT(DISTINCT user_id)` | | select\$1grouping\$1column\$1expression | 可使用下列項目包含任何表達式的表達式： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules-aggregation.html) `select_aggregate_expression` 可以使用或不使用 `AS` 參數來別名資料欄。如需詳細資訊，請參閱 [AWS Clean Rooms SQL 參考](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference.html)。 | `TRUNC(timestampColumn)` `UPPER(campaignName)` | | table\$1expression | 資料表或資料表聯結，以 連接聯結條件式表達式`join_condition`。 `join_condition` 傳回布林值。 `table_expression` 支援： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules-aggregation.html) | 
FROM consumer_table 
INNER JOIN provider_table
ON
consumer_table.identifier1 = provider_table.identifier1
AND
consumer_table.identifier2 = provider_table.identifier2
| | where\$1expression | 傳回布林值的條件式表達式。它可能包含下列項目： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules-aggregation.html) 支援的比較條件為 (`=, >, <, <=, >=, <>, !=, NOT, IN, NOT IN, LIKE, IS NULL, IS NOT NULL`)。 支援的邏輯運算子為 (`AND, OR`)。 `where_expression` 為選用。 | `WHERE where_condition` `WHERE price > 100` `WHERE TRUNC(timestampColumn) = '1/1/2022'` `WHERE timestampColumn = timestampColumn2 - 14` | | group\$1by\$1expression | 符合 需求的逗號分隔表達式清單`select_grouping_column_expression`。 | `GROUP BY TRUNC(timestampColumn), UPPER(campaignName), segment` | | having\$1expression | 傳回布林值的條件式表達式。它們具有套用至單一資料欄 （例如，`SUM(price)`) 的支援彙總函數，並與數值常值進行比較。 支援的條件為 (`=, >, <, <=, >=, <>, !=`)。 支援的邏輯運算子為 (`AND, OR`)。 `having_expression` 為選用。 | `HAVING SUM(SALES) > 500` | | order\$1by\$1expression | 以逗號分隔的表達式清單，與`select_aggregate_expression`先前定義的相同需求相容。 `order_by_expression` 為選用。 `order_by_expression` 允許 `ASC` 和 `DESC` 參數。如需詳細資訊，請參閱 [AWS Clean Rooms SQL 參考](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference.html)中的 ASC DESC 參數。 | `ORDER BY SUM(SALES), UPPER(campaignName)` | 對於彙總查詢結構和語法，請注意下列事項： + 不支援 以外的 SQL SELECT 命令。 + 不支援子查詢和常用資料表表達式 （例如 WITH)。 + 不支援合併多個查詢的運算子 （例如 UNION)。 + TOP不支援 LIMIT、 和 OFFSET 參數。 ## 彙總分析規則 - 查詢控制項 透過彙總查詢控制項，您可以控制資料表中的資料欄用於查詢資料表的方式。例如，您可以控制哪些資料欄用於聯結、哪些資料欄可以計數，或哪些資料欄可用於 WHERE 陳述式。 以下各節說明每個控制項。 **Topics** + [彙總控制項](#agg-functions) + [聯結控制項](#join-controls) + [維度控制](#dimension-controls) + [純量函數](#scalar-functions) ### 彙總控制項 透過使用*彙總控制項*，您可以定義要允許哪些彙總函數，以及必須套用哪些資料欄。彙總函數可用於 SELECT、 HAVING和 ORDERBY表達式。 | 控制項 | 定義 | Usage | | --- | --- | --- | | aggregateColumns | 您允許在彙總函數中使用的已設定資料表資料欄資料欄。 | `aggregateColumns` 可在 SELECT、 HAVING和 ORDERBY表達式中的彙總函數內使用。 有些 `aggregateColumns`也可以分類為 `joinColumn`（稍後定義）。 指定的 也`aggregateColumn`無法分類為 `dimensionColumn`（稍後定義）。 | | function | 您允許在 上使用的 COUNT、SUM 和 AVG 函數aggregateColumns。 | `function` 可以套用至`aggregateColumns`與其相關聯的 。 | ### 聯結控制項 子`JOIN`句用於根據兩個或多個資料表之間的相關資料欄來結合資料列。 您可以使用*聯結控制項*來控制資料表如何聯結至 中的其他資料表`table_expression`。 AWS Clean Rooms 僅支援 INNER JOIN。 INNERJOIN陳述式只能使用在分析規則`joinColumn`中明確分類為 的資料欄，但需遵守您定義的控制項。 INNER JOIN 必須在`joinColumn`您設定的資料表和協同合作中`joinColumn`另一個設定的資料表的 上操作。您決定資料表中的哪些資料欄可以用作 `joinColumn`。 子ON句中的每個相符條件都需要在兩個資料欄之間使用等式比較條件 (`=`)。 ON 子句中的多個相符條件可以是： + 使用`AND`邏輯運算子合併 + 使用`OR`邏輯運算子分隔 **注意** 所有JOIN相符條件都必須符合 每一端的一列JOIN。由 `OR`或 `AND` 邏輯運算子連接的所有條件也必須遵守此要求。 以下是具有`AND`邏輯運算子的查詢範例。 ``` SELECT some_col, other_col FROM table1 JOIN table2 ON table1.id = table2.id AND table1.name = table2.name ``` 以下是具有`OR`邏輯運算子的查詢範例。 ``` SELECT some_col, other_col FROM table1 JOIN table2 ON table1.id = table2.id OR table1.name = table2.name ``` | 控制項 | 定義 | Usage | | --- | --- | --- | | joinColumns | 您想要允許可在 INNERJOIN陳述式中使用之成員的資料欄 （如果有的話）。 | 特定 `joinColumn`也可以分類為 `aggregateColumn`（請參閱 [彙總控制項](#agg-functions))。 相同的資料欄不能同時使用為 `joinColumn`和 `dimensionColumns`（請參閱下文）。 除非它也被分類為 `aggregateColumn`，否則 `joinColumn` 無法在查詢的任何其他部分中使用INNERJOIN。 | | joinRequired | 控制是否需要INNERJOIN具有可查詢之成員所設定資料表的 。 | 如果您啟用此參數，INNERJOIN則需要 。如果您未啟用此參數， INNERJOIN是選用的。 假設您啟用此參數，可以查詢的成員需要在 INNER 中包含他們擁有的資料表JOIN。他們必須JOIN直接或暫時使用您的資料表 （也就是，將他們的資料表加入另一個資料表，而資料表本身會加入您的資料表）。 | 以下是可轉移性的範例。 ``` ON my_table.identifer = third_party_table.identifier .... ON third_party_table.identifier = member_who_can_query_table.id ``` **注意** 可以查詢的成員也可以使用 `joinRequired` 參數。在這種情況下，查詢必須與至少另一個資料表聯結其資料表。 ### 維度控制 *維度控制項*控制可篩選、分組或彙總彙總資料欄的資料欄。 | 控制項 | 定義 | Usage | | --- | --- | --- | | dimensionColumns | 您允許可在 SELECT、BY、 和 中查詢使用之成員的資料欄 WHERE GROUP （如果有）ORDERBY。 | `dimensionColumn` 可用於 SELECT(`select_grouping_column_expression`)BY、、 WHERE GROUP 和 ORDER BY。 相同的資料欄不能同時是 `dimensionColumn`、 `joinColumn`和/或 `aggregateColumn`。 | ### 純量函數 *純量函數*控制哪些純量函數可用於維度資料欄。 | 控制項 | 定義 | Usage | | --- | --- | --- | | scalarFunctions | 可在查詢`dimensionColumns`中使用的純量函數。 | 指定您允許 （例如，) 套用至 的純量函數 （如果有的話CAST)`dimensionColumns`。 純量函數無法用於其他函數之上或其他函數內。純量函數的引數可以是資料欄、字串常值或數值常值。 | 支援下列純量函數： + 數學函數 – ABS、CEILING、FLOOR、LOG、LN、ROUND、SQRT + 資料類型格式化函數 – CAST, CONVERT, TO\$1CHAR, TO\$1DATE, TO\$1NUMBER, TO\$1TIMESTAMP + 字串函數 – LOWER、UPPER、TRIM、RTRIM、SUBSTRING + 對於 RTRIM，不允許要修剪的自訂字元集。 + 條件式表達式 – COALESCE + 日期函數 – EXTRACT、GETDATE、CURRENT\$1DATE、DATEADD + 其他 函數 – TRUNC 如需詳細資訊，請參閱 [AWS Clean Rooms SQL 參考](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference.html)。 ## 彙總分析規則 - 查詢結果控制 使用彙總查詢結果控制項，您可以透過指定每個輸出資料列必須符合的一或多個條件來控制傳回的結果。 AWS Clean Rooms 支援 形式的彙總限制`COUNT (DISTINCT column) >= X`。此表單要求每一列至少從您設定的資料表彙總 X 個不同的值 （例如，最低數量的不同`user_id`值）。即使提交的查詢本身未使用指定的資料欄，也會自動強制執行此最低閾值。它們會從協同合作中每個成員的已設定資料表，在查詢中的每個已設定資料表中集體強制執行。 每個設定的資料表在其分析規則中必須至少有一個彙總限制。設定的資料表擁有者可以新增多個 `columnName`和相關聯的 `minimum`，而且它們會集體強制執行。 ### 彙總限制 *彙總限制*會控制查詢結果中傳回的資料列。若要傳回，資料列必須符合彙總限制中指定之每個資料欄中指定的相異值下限。即使未在查詢或分析規則的其他部分中明確提及資料欄，此要求也適用。 | 控制項 | 定義 | Usage | | --- | --- | --- | | columnName | `aggregateColumn` 用於每個輸出資料列必須符合的條件的 。 | 可以是已設定資料表中的任何資料欄。 | | minimum | `aggregateColumn` 輸出資料列必須擁有的關聯 （例如 COUNT DISTINCT) 之相異值的最小數量，才能在查詢結果中傳回。 | 值必須至少`minimum`為 2。 | ## 彙總分析規則結構 下列範例顯示彙總分析規則的預先定義結構。 在下列範例中， *`MyTable`*是指您的資料表。您可以將每個*使用者輸入預留位置*取代為您自己的資訊。 ``` { "aggregateColumns": [ { "columnNames": [MyTable column names], "function": [Allowed Agg Functions] }, ], "joinRequired": ["QUERY_RUNNER"], "joinColumns": [MyTable column names], "dimensionColumns": [MyTable column names], "scalarFunctions": [Allowed Scalar functions], "outputConstraints": [ { "columnName": [MyTable column names], "minimum": [Numeric value] }, ] } ``` ## 彙總分析規則 - 範例 下列範例示範兩家公司如何使用彙總分析 AWS Clean Rooms 協作。 A 公司有客戶和銷售資料。A 公司有興趣了解產品退回活動。B 公司是 A 公司的零售商之一，並具有傳回資料。B 公司對客戶也有對 A 公司有用的客群屬性 （例如，購買相關產品、使用零售商的客戶服務）。B 公司不想提供資料列層級的客戶傳回資料和屬性資訊。B 公司只想為 A 公司啟用一組查詢，以最低彙總閾值取得重疊客戶的彙總統計資料。 A 公司和 B 公司決定協同合作，讓 A 公司了解產品退回活動，並在 B 公司和其他管道提供更好的產品。 若要建立協同合作並執行彙總分析，公司會執行下列動作： 1. A 公司建立協同合作並建立成員資格。協同合作讓 B 公司成為協同合作中的另一個成員。公司 A 會在協同合作中啟用查詢記錄，並在其帳戶中啟用查詢記錄。 1. B 公司在協同合作中建立成員資格。它在其帳戶中啟用查詢記錄。 1. 公司 A 會建立銷售設定的資料表。 1. A 公司將下列彙總分析規則新增至銷售設定的資料表。 ``` { "aggregateColumns": [ { "columnNames": [ "identifier" ], "function": "COUNT_DISTINCT" }, { "columnNames": [ "purchases" ], "function": "AVG" }, { "columnNames": [ "purchases" ], "function": "SUM" } ], "joinColumns": [ "hashedemail" ], "dimensionColumns": [ "demoseg", "purchasedate", "productline" ], "scalarFunctions": [ "CAST", "COALESCE", "TRUNC" ], "outputConstraints": [ { "columnName": "hashedemail", "minimum": 2, "type": "COUNT_DISTINCT" }, ] } ``` `aggregateColumns` – A 公司想要計算銷售資料和傳回資料之間重疊中的唯一客戶數量。A 公司也想要加總`purchases`要與 數目比較的 數目`returns`。 `joinColumns` – 公司 A 想要使用 `identifier` 來比對客戶從銷售資料到客戶從傳回資料。這將有助於公司 A 配對傳回正確的購買。它還有助於公司 A 區段重疊的客戶。 `dimensionColumns` – A 公司使用 依特定產品`dimensionColumns`篩選、比較購買和在特定期間內傳回、確保傳回日期晚於產品日期，以及協助分割重疊的客戶。 `scalarFunctions` – A 公司會根據設定的資料表 A 與協同合作的關聯，視需要選取`CAST`純量函數以協助更新資料類型格式。它還會新增純量函數，以在需要時協助格式化資料欄。 `outputConstraints` – 公司 A 設定最小輸出限制。它不需要限制結果，因為允許分析師查看其銷售資料表中的資料列層級資料 **注意** A 公司不包含在分析規則`joinRequired`中。它為分析師提供了單獨查詢銷售資料表的靈活性。 1. B 公司會建立傳回設定的資料表。 1. B 公司將下列彙總分析規則新增至傳回設定的資料表。 ``` { "aggregateColumns": [ { "columnNames": [ "identifier" ], "function": "COUNT_DISTINCT" }, { "columnNames": [ "returns" ], "function": "AVG" }, { "columnNames": [ "returns" ], "function": "SUM" } ], "joinColumns": [ "hashedemail" ], "joinRequired": [ "QUERY_RUNNER" ], "dimensionColumns": [ "state", "popularpurchases", "customerserviceuser", "productline", "returndate" ], "scalarFunctions": [ "CAST", "LOWER", "UPPER", "TRUNC" ], "outputConstraints": [ { "columnName": "hashedemail", "minimum": 100, "type": "COUNT_DISTINCT" }, { "columnName": "producttype", "minimum": 2, "type": "COUNT_DISTINCT" } ] } ``` `aggregateColumns` – 公司 B 可讓公司 A 的總和`returns`與購買次數進行比較。它們至少有一個彙總資料欄，因為它們正在啟用彙總查詢。 `joinColumns` – 公司 B 可讓公司 A 加入 `identifier` ，以比對客戶從銷售資料傳回給客戶的資料。 `identifier`資料特別敏感，並將它做為 ，`joinColumn`以確保資料永遠不會在查詢中輸出。 `joinRequired` – B 公司要求對傳回資料的查詢與銷售資料重疊。他們不希望讓 A 公司查詢其資料集中的所有個人。他們在協同合作協議中也同意該限制。 `dimensionColumns` – 公司 B 可讓公司 A 依 `state`、 `popularpurchases`和 進行篩選和分組`customerserviceuser`，這些是可協助進行公司 A 分析的唯一屬性。公司 B 可讓公司 A 使用 `returndate`篩選 之後`returndate`發生的輸出`purchasedate`。透過此篩選，輸出對於評估產品變更的影響更為準確。 `scalarFunctions` – B 公司啟用下列項目： + 日期的 TRUNC + LOWER 和 UPPER，以防在其資料中以不同的格式`producttype`輸入 + CAST 如果 A 公司需要將銷售中的資料類型轉換為與傳回中的資料類型相同 A 公司不會啟用其他純量函數，因為他們不認為查詢需要它們。 `outputConstraints` – B 公司設定 的最低輸出限制`hashedemail`，以協助降低重新識別客戶的能力。它也會在 上新增最低輸出限制`producttype`，以減少重新識別傳回之特定產品的能力。根據輸出的維度 （例如，)，某些產品類型可能更具優勢`state`。無論 A 公司為其資料新增的輸出限制，一律都會強制執行其輸出限制。 1. A 公司建立與協同合作的銷售資料表關聯。 1. B 公司會建立與協同合作的傳回資料表關聯。 1. 公司 A 會執行查詢，例如下列範例，相較於 2022 年位置的總購買量，更了解公司 B 中的傳回數量。 ``` SELECT companyB.state, SUM(companyB.returns), COUNT(DISTINCT companyA.hashedemail) FROM sales companyA INNER JOIN returns companyB ON companyA.identifier = companyB.identifier WHERE companyA.purchasedate BETWEEN '2022-01-01' AND '2022-12-31' AND TRUNC(companyB.returndate) > companyA.purchasedate GROUP BY companyB.state; ``` 1. 公司 A 和公司 B 會檢閱查詢日誌。B 公司會驗證查詢是否符合協同合作協議中同意的內容。 ## 對彙總分析規則問題進行故障診斷 當您使用彙總分析規則時，請使用此處的資訊來協助您診斷和修正常見問題。 **Topics** + [我的查詢未傳回任何結果](#query-no-results) ### 我的查詢未傳回任何結果 當沒有相符的結果，或相符的結果不符合一或多個最小彙總閾值時，就會發生這種情況。 如需最低彙總閾值的詳細資訊，請參閱 [彙總分析規則 - 範例](#agg-analysis-rule-example)。 # 列出分析規則 在 中 AWS Clean Rooms，*清單分析規則*會輸出其新增至的已設定資料表與可查詢之成員的已設定資料表之間的重疊資料列層級清單。可查詢的成員會執行包含清單分析規則的查詢。 清單分析規則類型支援使用擴充和對象建置等案例。 如需此分析規則預先定義查詢結構和語法的詳細資訊，請參閱 [列出分析規則預先定義的結構](#intersection-list-params-template)。 中定義的清單分析規則參數[列出分析規則 - 查詢控制項](#parameters-list-query-controls)具有查詢控制項。其查詢控制項包含選取可在輸出中列出的資料欄的功能。查詢需要至少有一個與成員所設定資料表的聯結，該成員可以直接或暫時進行查詢。 沒有像[彙總分析規則](analysis-rules-aggregation.md)一樣的查詢結果控制項。 清單查詢只能使用數學運算子。他們無法使用其他函數 （例如彙總或純量）。 **Topics** + [列出查詢結構和語法](#list-query-controls) + [列出分析規則 - 查詢控制項](#parameters-list-query-controls) + [列出分析規則預先定義的結構](#intersection-list-params-template) + [列出分析規則 - 範例](#list-example) ## 列出查詢結構和語法 具有清單分析規則之資料表的查詢必須遵循下列語法。 ``` --select_list_expression SELECT DISTINCT column_name [[AS] column_alias ] [, ...] --table_expression FROM table_name [[AS] table_alias ] [[INNER] JOIN table_name [[AS] table_alias] ON join_condition] [...] --where_expression [WHERE where_condition] --limit_expression [LIMIT number] ``` 下表說明上述語法中列出的每個表達式。 | 表達式 | 定義 | 範例 | | --- | --- | --- | | select\$1list\$1expression | 以逗號分隔的清單，包含至少一個資料表資料欄名稱。 需要 `DISTINCT` 參數。 `select_list_expression` 可以使用或不使用 `AS` 參數來別名資料欄。 如需詳細資訊，請參閱 [AWS Clean Rooms SQL 參考](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference.html)。 | `SELECT DISTINCT segment` | | table\$1expression | 資料表或資料表的聯結，`join_condition`搭配 將其連接到 `join_condition`。 `join_condition` 傳回布林值。 `table_expression` 支援： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules-list.html) | 
FROM consumer_table 
INNER JOIN provider_table
ON
consumer_table.identifier1 = provider_table.identifier1
AND
consumer_table.identifier2 = provider_table.identifier2
| | where\$1expression | 傳回布林值的條件式表達式。它可以包含下列項目：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/analysis-rules-list.html)支援的比較條件為 (`=, >, <, <=, >=, <>, !=, NOT, IN, NOT IN, LIKE, IS NULL, IS NOT NULL`)。支援的邏輯運算子為 (`AND, OR`)。`where_expression` 為選用。 | `WHERE state + '_' + city = 'NY_NYC'` `WHERE timestampColumn = timestampColumn2 - 14` | | limit\$1expression | 此表達式必須採用正整數。 `limit_expression` 為選用。 | `LIMIT 100` | 對於清單查詢結構和語法，請注意下列事項： + 不支援 SELECT 以外的 SQL 命令。 + 不支援子查詢和常用資料表表達式 （例如 WITH) + 不支援 HAVINGBY、 GROUP 和 ORDER BY子句 + 不支援 OFFSET 參數 ## 列出分析規則 - 查詢控制項 透過清單查詢控制項，您可以控制資料表中的資料欄用於查詢資料表的方式。例如，您可以控制哪些資料欄用於聯結，或哪些資料欄可用於 SELECT 陳述式和WHERE子句。 以下各節說明每個控制項。 **Topics** + [聯結控制項](#list-controls-join-controls) + [列出控制項](#list-controls) ### 聯結控制項 使用*聯結控制項*，您可以控制資料表如何聯結至 **table\$1expression** 中的其他資料表。 AWS Clean Rooms 僅支援 INNER JOIN。在清單分析規則中，至少需要一個 INNER JOIN，而且可以查詢的成員需要在 INNER JOIN 中包含他們擁有的資料表。這表示他們必須直接或暫時加入您的資料表。 以下是可轉移性的範例。 ``` ON my_table.identifer = third_party_table.identifier .... ON third_party_table.identifier = member_who_can_query_table.id ``` INNER JOIN 陳述式只能使用在您的分析規則`joinColumn`中明確歸類為 的資料欄。 INNER JOIN 必須在`joinColumn`您設定的資料表和協同合作中`joinColumn`另一個設定的資料表的 上操作。您可以決定資料表中的哪些資料欄可以用作 `joinColumn`。 子ON句中的每個相符條件都需要使用兩個資料欄之間的相等比較條件 (`=`)。 ON 子句中的多個相符條件可以是： + 使用`AND`邏輯運算子合併 + 使用`OR`邏輯運算子分隔 **注意** 所有JOIN相符條件都必須符合 每一端的一列JOIN。由 `OR`或 `AND` 邏輯運算子連接的所有條件也必須遵守此要求。 以下是具有`AND`邏輯運算子的查詢範例。 ``` SELECT some_col, other_col FROM table1 JOIN table2 ON table1.id = table2.id AND table1.name = table2.name ``` 以下是具有`OR`邏輯運算子的查詢範例。 ``` SELECT some_col, other_col FROM table1 JOIN table2 ON table1.id = table2.id OR table1.name = table2.name ``` | 控制項 | 定義 | Usage | | --- | --- | --- | | joinColumns | 您要允許可在 INNER JOIN 陳述式中查詢使用之成員的資料欄。 | 相同的資料欄無法同時歸類為 `joinColumn`和 `listColumn`（請參閱 [列出控制項](#list-controls))。 `joinColumn` 無法用於 INNER JOIN 以外的任何其他查詢部分。 | ### 列出控制項 *清單控制項*控制可在查詢輸出中列出的資料欄 （即 SELECT 陳述式中使用的資料欄） 或用於篩選結果 （即WHERE陳述式中使用的資料欄）。 | 控制項 | 定義 | Usage | | --- | --- | --- | | listColumns | 您允許可在 SELECT 和 中查詢使用之成員的資料欄 WHERE | listColumn 可用於 SELECT 和 WHERE。相同的資料欄無法同時做為 `listColumn`和 使用`joinColumn`。 | ## 列出分析規則預先定義的結構 下列範例包含預先定義的結構，示範如何完成清單分析規則。 在下列範例中， *`MyTable`*是指您的資料表。您可以將每個*使用者輸入預留位置*取代為您自己的資訊。 ``` { "joinColumns": [MyTable column name(s)], "listColumns": [MyTable column name(s)], } ``` ## 列出分析規則 - 範例 下列範例示範兩家公司如何使用 AWS Clean Rooms 清單分析協作。 A 公司有客戶關係管理 (CRM) 資料。A 公司想要取得客戶的其他客群資料，以進一步了解他們的客戶，並可能使用屬性做為其他分析的輸入。B 公司擁有區段資料，其中包含他們根據第一方資料建立的唯一區段屬性。公司 B 只希望在其資料與公司 A 資料之間重疊的客戶上，提供唯一的客群屬性給公司 A。 公司決定協同合作，讓 A 公司可以充實重疊的資料。A 公司是可以查詢的成員，而 B 公司是參與者。 若要建立協同合作並在協同合作中執行清單分析，公司會執行下列動作： 1. A 公司建立協同合作並建立成員資格。協同合作讓 B 公司成為協同合作的另一個成員。A 公司在協同合作中啟用查詢記錄，並在其帳戶中啟用查詢記錄。 1. B 公司在協同合作中建立成員資格。它在其帳戶中啟用查詢記錄。 1. 公司 A 會建立 CRM 設定的資料表 1. A 公司將分析規則新增至客戶設定的資料表，如下列範例所示。 ``` { "joinColumns": [ "identifier1", "identifier2" ], "listColumns": [ "internalid", "segment1", "segment2", "customercategory" ] } ``` `joinColumns` – A 公司想要使用 `hashedemail` 和/或 `thirdpartyid`（從身分廠商取得），將客戶從 CRM 資料比對到客戶從客群資料。這將有助於確保 A 公司符合適當客戶的豐富資料。它們有兩個 joinColumns可能改善分析的比對率。 `listColumns` – 公司 A 使用 在自己的系統中`internalid`使用 以外的 `listColumns`來取得富集的資料欄。它們會新增 `segment1`、 `segment2`和 `customercategory` ，以透過在篩選條件中使用特定客群來限制擴充。 1. B 公司會建立區段設定的資料表。 1. B 公司將分析規則新增至區段設定的資料表。 ``` { "joinColumns": [ "identifier2" ], "listColumns": [ "segment3", "segment4" ] } ``` `joinColumns` – B 公司可讓 A 公司加入 `identifier2`，將客戶從客群資料配對至 CRM 資料。A 公司和 B 公司與身分廠商合作，以取得`identifier2`符合此協同合作的項目。他們沒有新增其他 `joinColumns`，因為他們認為 `identifier2`提供最高且最準確的配對率，而查詢不需要其他識別符。 `listColumns` – B 公司可讓 A 公司使用 `segment3`和 `segment4` 屬性來擴充其資料，這些屬性是他們在 （與客戶 A) 上建立、收集和對齊的唯一屬性，成為資料擴充的一部分。他們希望 A 公司在資料列層級取得重疊的這些區段，因為這是資料擴充協作。 1. A 公司建立與協同合作的 CRM 資料表關聯。 1. B 公司建立與協同合作的區段資料表關聯。 1. A 公司執行查詢，例如下列查詢，以豐富重疊的客戶資料。 ``` SELECT companyA.internalid, companyB.segment3, companyB.segment4 INNER JOIN returns companyB ON companyA.identifier2 = companyB.identifier2 WHERE companyA.customercategory > 'xxx' ``` 1. 公司 A 和公司 B 會檢閱查詢日誌。B 公司會驗證查詢是否符合協同合作協議中同意的內容。 # 中的自訂分析規則 AWS Clean Rooms 在 中 AWS Clean Rooms，*自訂分析規則*是一種新的分析規則類型，允許自訂查詢在設定的資料表上執行。自訂 SQL 查詢仍然限制為只有 SELECT命令，但可以使用比[彙總](analysis-rules-aggregation.md#agg-query-controls)和[清單](analysis-rules-list.md#list-query-controls)查詢更多的 SQL 建構 （例如，視窗函數、OUTER JOIN、CTEs 或子查詢；如需完整清單，請參閱 [AWS Clean Rooms SQL 參考](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference.html))。自訂 SQL 查詢不需要遵循查詢結構，例如[彙總](analysis-rules-aggregation.md#agg-query-structure-syntax)和[列出](analysis-rules-list.md#list-query-controls)查詢。 自訂分析規則支援比彙總和列出分析規則所支援更進階的使用案例，例如自訂屬性分析、基準化、增量分析和對象探索。這是彙總和列出分析規則所支援之使用案例的超集。 自訂分析規則也支援差異隱私權。差異隱私權是資料隱私權保護的數學嚴格架構。如需詳細資訊，請參閱[AWS Clean Rooms 差異隱私權](differential-privacy.md)。當您建立分析範本時， AWS Clean Rooms 差異隱私權會檢查範本，以判斷它是否與 AWS Clean Rooms 差異隱私權的一般用途查詢結構相容。此驗證可確保您不會建立不允許使用差異隱私權保護資料表的分析範本。 若要設定自訂分析規則，資料擁有者可以選擇允許儲存在[分析範本](create-analysis-template.md)中的特定自訂查詢在其設定的資料表上執行。資料擁有者會檢閱分析範本，再將其新增至自訂分析規則中允許的分析控制項。分析範本僅在建立它們的協同合作中可用和可見 （即使資料表與其他協同合作相關聯），並且只能由可在該協同合作中查詢的成員執行。 或者，成員可以選擇允許其他成員 （查詢提供者） 建立查詢，而無需檢閱。成員在自訂分析規則中新增允許查詢提供者控制的查詢提供者帳戶。如果查詢提供者是可以查詢的成員，他們可以直接在設定的資料表上執行任何查詢。查詢提供者也可以透過建立[分析範本來建立](create-analysis-template.md)查詢。查詢提供者建立的任何查詢都會自動允許在 AWS 帳戶 存在 且與資料表相關聯的所有協同合作中，於資料表上執行。 資料擁有者只能允許分析範本或帳戶建立查詢，不能同時建立兩者。如果資料擁有者將其保留空白，可以查詢的成員就無法在設定的資料表上執行查詢。 **Topics** + [自訂分析規則預先定義的結構](#custom-predefined-structure) + [自訂分析規則範例](#custom-example) + [具有差異隱私權的自訂分析規則](#custom-diff-privacy) ## 自訂分析規則預先定義的結構 下列範例包含預先定義的結構，說明如何在開啟差異隱私權的情況下完成自訂分析規則。`userIdentifier` 值是可唯一識別使用者的欄，例如 *user\$1id*。當您在協同合作中開啟了兩個或多個具有差異隱私權的資料表時， AWS Clean Rooms 會要求您在兩個分析規則中設定與使用者識別符資料欄相同的資料欄，以維持資料表之間使用者的一致定義。 ``` { "allowedAnalyses": ["ANY_QUERY"] | string[], "allowedAnalysisProviders": [], "differentialPrivacy": { "columns": [ { "name": "userIdentifier" } ] } } ``` 您可擇一方法： + 將分析範本 ARNs新增至允許的分析控制項。在此情況下，不包含`allowedAnalysisProviders`控制項。 ``` { allowedAnalyses: string[] } ``` + 將 AWS 帳戶 IDs新增至`allowedAnalysisProviders`控制項。在此情況下，您會將 `ANY_QUERY`新增至`allowedAnalyses`控制項。 ``` { allowedAnalyses: ["ANY_QUERY"], allowedAnalysisProviders: string[] } ``` ## 自訂分析規則範例 下列範例示範兩家公司如何使用自訂分析規則 AWS Clean Rooms 在 中協作。 A 公司有客戶和銷售資料。A 公司有興趣了解 B 公司網站上的廣告行銷活動銷售增量。B 公司具有對公司有用的瀏覽資料和客群屬性 （例如，檢視廣告時所使用的裝置）。 A 公司有他們想要在協同合作中執行的特定增量查詢。 若要建立協同合作並在協同合作中執行自訂分析，公司會執行下列動作： 1. A 公司建立協同合作並建立成員資格。協同合作讓 B 公司成為協同合作的另一個成員。A 公司在協同合作中啟用查詢記錄，並在其帳戶中啟用查詢記錄。 1. B 公司在協同合作中建立成員資格。它在其帳戶中啟用查詢記錄。 1. 公司 A 會建立 CRM 設定的資料表 1. A 公司將空的自訂分析規則新增至銷售設定的資料表。 1. A 公司將銷售設定的資料表與協同合作建立關聯。 1. B 公司會建立檢視設定資料表。 1. B 公司將空的自訂分析規則新增至檢視器設定的資料表。 1. B 公司將檢視設定資料表與協同合作建立關聯。 1. 公司 A 檢視與協同合作相關聯的銷售資料表和檢視器資料表，並建立分析範本，新增行銷活動月份的增量查詢和參數。 ``` { "analysisParameters": [ { "defaultValue": "" "type": "DATE" "name": "campaign_month" } ], "description": "Monthly incrementality query using sales and viewership data" "format": "SQL" "name": "Incrementality analysis" "source": "WITH labeleddata AS ( SELECT hashedemail, deviceid, purchases, unitprice, purchasedate, CASE WHEN testvalue IN ('value1', 'value2', 'value3') THEN 0 ELSE 1 END AS testgroup FROM viewershipdata ) SELECT labeleddata.purchases, provider.impressions FROM labeleddata INNER JOIN salesdata ON labeleddata.hashedemail = provider.hashedemail WHERE MONTH(labeleddata.purchasedate) > :campaignmonth AND testgroup = :group " } ``` 1. A 公司將其帳戶 （例如 444455556666) 新增至自訂分析規則中允許的分析提供者控制項。他們使用允許的分析提供者控制項，因為他們想要允許他們建立的任何查詢在其銷售設定的資料表上執行。 ``` { "allowedAnalyses": [ "ANY_QUERY" ], "allowedAnalysisProviders": [ "444455556666" ] } ``` 1. B 公司會在協同合作中看到建立的分析範本，並檢閱其內容，包括查詢字串和參數。 1. B 公司判斷分析範本達到增量使用案例，並符合其檢視設定資料表如何查詢的隱私權要求。 1. B 公司將分析範本 ARN 新增至檢視器資料表自訂分析規則中允許的分析控制項。他們使用允許的分析控制項，因為他們只想要允許增量查詢在其檢視器設定的資料表上執行。 ``` { "allowedAnalyses": [ "arn:aws:cleanrooms:us-east-1:111122223333:membership/41327cc4-bbf0-43f1-b70c-a160dddceb08/analysistemplate/1ff1bf9d-781c-418d-a6ac-2b80c09d6292" ] } ``` 1. A 公司執行分析範本，並使用參數值 `05-01-2023`。 ## 具有差異隱私權的自訂分析規則 在 中 AWS Clean Rooms，自訂分析規則支援差異隱私權。差異隱私權是一種數學上嚴格的資料隱私權保護架構，可協助您保護資料免於重新識別嘗試。 差異隱私權支援彙總分析，例如廣告行銷活動規劃、post-ad-campaign測量、金融機構協會中的基準測試，以及醫療保健研究的 A/B 測試。 支援的查詢結構和語法在 中定義[查詢結構和語法](#dp-query-structure-syntax)。 ### 具有差異隱私權的自訂分析規則範例 **注意** AWS Clean Rooms 差異隱私權僅適用於資料存放在 Amazon S3 中的協同合作。 請考慮上一節中呈現的[自訂分析規則範例](#custom-example)。此範例示範如何使用差異隱私權來保護資料免於重新識別嘗試，同時讓合作夥伴從資料中學習關鍵業務洞見。假設擁有檢視器資料的 B 公司想要使用差異隱私權來保護其資料。若要完成差異隱私權設定，B 公司會完成下列步驟： 1. 公司 B 會開啟差異隱私權，同時將自訂分析規則新增至檢視器設定的資料表。B 公司會選取 `viewershipdata.hashedemail`做為使用者識別符欄。 1. B 公司在協同合作中[新增了差異性隱私權政策](configure-differential-privacy.md)，讓其瀏覽資料資料表可供查詢。B 公司會選取預設政策以快速完成設定。 A 公司想要了解 B 公司網站上的廣告行銷活動銷售增量，執行分析範本。由於查詢與 AWS Clean Rooms 差異隱私權的一般用途[查詢結構](#dp-query-structure-syntax)相容，因此查詢會成功執行。 ### 查詢結構和語法 包含至少一個已開啟差異隱私權的資料表的查詢必須遵循下列語法。 ``` query_statement: [cte, ...] final_select cte: WITH sub_query AS ( inner_select [ UNION | INTERSECT | UNION_ALL | EXCEPT/MINUS ] [ inner_select ] ) inner_select: SELECT [user_id_column, ] expression [, ...] FROM table_reference [, ...] [ WHERE condition ] [ GROUP BY user_id_column[, expression] [, ...] ] [ HAVING condition ] final_select: SELECT [expression, ...] | COUNT | COUNT_DISTINCT | SUM | AVG | STDDEV FROM table_reference [, ...] [ WHERE condition ] [ GROUP BY expression [, ...] ] [ HAVING COUNT | COUNT_DISTINCT | SUM | AVG | STDDEV | condition ] [ ORDER BY column_list ASC | DESC ] [ OFFSET literal ] [ LIMIT literal ] expression: column_name [, ...] | expression AS alias | aggregation_functions | window_functions_on_user_id | scalar_function | CASE | column_name math_expression [, expression] window_functions_on_user_id: function () OVER (PARTITION BY user_id_column, [column_name] [ORDER BY column_list ASC|DESC]) ``` **注意** 對於差異隱私權查詢結構和語法，請注意下列事項： 不支援子查詢。 如果資料表或 CTEs 涉及受差異隱私權保護的資料，通用資料表表達式 (CTE) 應該發出使用者識別符資料欄。篩選、分組和彙總應在使用者層級完成。 Final\$1select 允許 COUNT DISTINCT、COUNT、SUM、AVG 和 STDDEV 彙總函數。 如需差異隱私權支援哪些 SQL 關鍵字的詳細資訊，請參閱 [AWS Clean Rooms 差異隱私權的 SQL 功能](dp-sql-capabilities.md)。 # ID 映射表分析規則 在 中 AWS Clean Rooms，*ID 映射資料表分析規則*不是獨立的分析規則。這種類型的分析規則由 管理 AWS Clean Rooms ，用於聯結不同的身分資料，以方便查詢。它會自動新增至 ID 映射表，而且無法編輯。只要這些分析規則是同質的，就會繼承協同合作中其他分析規則的行為。 ID 映射表分析規則會對 ID 映射表強制執行安全性。它限制協作成員使用 ID 映射表直接選取或檢查兩個成員的資料集之間的非重疊人口。ID 映射表分析規則用於隱含在其他分析規則的查詢中使用時，保護 ID 映射表中的敏感資料。 使用 ID 映射表分析規則， 會在擴展的 SQL 中 AWS Clean Rooms 強制執行 ID 映射表兩側的重疊。這可讓您執行下列任務： + 在 JOIN陳述式中使用 ID 映射表的重疊。 AWS Clean Rooms 允許 ID 映射資料表上的 INNER、 LEFT或 RIGHT聯結，如果其遵守重疊。為了保護敏感映射資訊，ID 映射表必須一律位於任何JOIN操作的「inner」端。例如，下列JOIN操作有效： + table LEFT JOIN id\$1mapping\$1table + id\$1mapping\$1table RIGHT JOIN table + table INNER JOIN id\$1mapping\$1table 下列JOIN操作無效： + id\$1mapping\$1table LEFT JOIN table + table RIGHT JOIN id\$1mapping\$1table 這可防止您的資料集中沒有對應相符項目的映射記錄暴露。允許此類操作可能會洩露有關其他協同合作成員資料映射的敏感資訊。 + 在 JOIN陳述式中使用映射表資料欄。 您無法在下列陳述式中使用映射表欄：SELECT、GROUP BY、、 WHERE HAVING或 ORDER BY（除非在來源 ID 命名空間關聯或目標 ID 命名空間關聯上修改保護）。 + 在擴展的 SQL 中， AWS Clean Rooms 也支援 OUTER JOIN、隱含 JOIN和 CROSS JOIN。這些聯結無法滿足重疊要求。反之， AWS Clean Rooms 使用 `requireOverlap` 來指定必須加入哪些資料欄。 支援的查詢結構和語法在 中定義[ID 映射表查詢結構和語法](#id-mapping-table-query-controls)。 中定義的分析規則參數[ID 映射表分析規則查詢控制項](#parameters-id-mapping-query-controls)包括查詢控制項和查詢結果控制項。其查詢控制項包含要求 JOIN陳述式中 ID 映射資料表重疊的功能 （即 `requireOverlap`)。 **Topics** + [ID 映射表查詢結構和語法](#id-mapping-table-query-controls) + [ID 映射表分析規則查詢控制項](#parameters-id-mapping-query-controls) + [ID 映射表分析規則預先定義的結構](#id-mapping-table-predefined-structure) + [ID 映射表分析規則 – 範例](#id-mapping-table-example) ## ID 映射表查詢結構和語法 對具有 ID 映射資料表分析規則的資料表進行查詢必須遵循下列語法。 ``` --select_list_expression SELECT provider.data_col, consumer.data_col --table_expression FROM provider JOIN idMappingTable idmt ON provider.id = idmt.sourceId JOIN consumer ON consumer.id = idmt.targetId ``` ### 協同合作資料表 下表代表協同 AWS Clean Rooms 合作中存在的已設定資料表。**cr\$1drivers\$1license** 和 **cr\$1management** 資料表中的 **ID** 資料欄代表要與 ID 映射資料表相符的資料欄。 **cr\$1drivers\$1license** | | | | | --- |--- |--- | | id | driver\$1name | state\$1of\$1registration | | 1 | Eduard | TX | | 2 | Dana | MA | | 3 | Gweneth | IL | **cr\$1 保險** | | | | | --- |--- |--- | | id | policyholder\$1email | policy\$1number | | a | eduardo@internal.company.com | 17f9d04e-f5be-4426-bdc4-250ed59c6529 | | b | gwen@internal.company.com | 3f0092db-2316-48a8-8d44-09cf8f6e6c64 | | c | rosa@internal.company.com | d7692e84-3d3c-47b8-b46d-a0d5345f0601 | ### ID 映射表 下表代表與 **cr\$1drivers\$1license** 和 **cr\$1management** 資料表相符的現有 ID 映射資料表。並非所有項目都有兩個協同合作資料表IDs。 | | | | --- |--- | | cr\$1drivers\$1license\$1id | cr\$1insurance\$1id | | 1 | a | | 2 | null | | 3 | b | | null | c | ID 映射資料表分析規則僅允許在一組重疊資料上執行查詢，如下所示： | | | | | | | | --- |--- |--- |--- |--- |--- | | cr\$1drivers\$1license\$1id | cr\$1insurance\$1id | driver\$1name | state\$1of\$1registration | policyholder\$1email | policy\$1number | | 1 | a | Eduard | TX | eduardo@internal.company.com | 17f9d04e-f5be-4426-bdc4-250ed59c6529 | | 3 | b | Gweneth | IL | gwen@internal.company.com | 3f0092db-2316-48a8-8d44-09cf8f6e6c64 | ### 查詢範例 下列範例顯示 ID 映射資料表聯結的有效位置： ``` -- Single ID mapping table SELECT [ select_items ]FROM cr_drivers_license cr_dl [ INNER | LEFT ] JOIN cr_identity_mapping_table idmt ON idmt.cr_drivers_license_id = cr_dl.id [ INNER | RIGHT ] JOIN cr_insurance cr_in ON idmt.cr_insurance_id = cr_in.id ; -- Single ID mapping table (Subquery) SELECT [ select_items ]FROM ( SELECT [ select_items ] FROM cr_drivers_license cr_dl [ INNER | LEFT ] JOIN cr_identity_mapping_table idmt ON idmt.cr_drivers_license_id = cr_dl.id [ INNER | RIGHT ] JOIN cr_insurance cr_in ON idmt.cr_insurance_id = cr_in.id ) ; -- Single ID mapping table (CTE) WITH matched_ids AS ( SELECT [ select_items ] FROM cr_drivers_license cr_dl [ INNER | LEFT ] JOIN cr_identity_mapping_table idmt ON idmt.cr_drivers_license_id = cr_dl.id [ INNER | RIGHT ] JOIN cr_insurance cr_in ON idmt.cr_insurance_id = cr_in.id )SELECT [ select_items ]FROM matched_ids ; ``` ### 考量事項 對於 ID 映射資料表查詢結構和語法，請注意下列事項： + 您無法編輯它。 + 根據預設，它會套用至 ID 映射表。 + 它在協同合作中使用來源和目標 ID 命名空間關聯。 + 根據預設，ID 映射表會設定為為來自 ID 命名集的資料欄提供預設保護。您可以修改此組態，以便在查詢中的任何位置允許來自 ID 命名空間 ( `sourceID`或 `targetID`) 的資料欄。如需詳細資訊，請參閱[中的 ID 命名空間 AWS Clean Rooms](working-with-id-namespaces.md)。 + ID 映射資料表分析規則會繼承協同合作中其他分析規則的 SQL 限制。 ## ID 映射表分析規則查詢控制項 使用 ID 映射資料表查詢控制項， AWS Clean Rooms 控制資料表中的資料欄如何用於查詢資料表。例如，它會控制哪些資料欄用於聯結，以及哪些資料欄需要重疊。ID 映射資料表分析規則也包含的功能可讓您允許投影 `sourceID`、 `targetID`或兩者，而無需 JOIN。 下表說明每個控制項。 | 控制項 | 定義 | Usage | | --- | --- | --- | | joinColumns | 可以查詢的成員可以在 INNER JOIN 陳述式中使用的資料欄。 | 除了 INNER JOIN 之外，您無法joinColumns在查詢的任何其他部分中使用 。如需詳細資訊，請參閱[聯結控制項](analysis-rules-aggregation.md#join-controls)。 | | dimensionColumns | 可在 SELECT 和 GROUP BY 陳述式中查詢的成員可以使用的資料欄 （如果有）。 | `dimensionColumn` 可用於 SELECT和 GROUP BY。 `dimensionColumn` 可以顯示為 `joinKeys`。 只有在括號`dimensionColumns`中指定 JOIN 子句時，才能在 JOIN 子句中使用 。 | | queryContraints:RequireOverlap | ID 映射表中必須聯結的資料欄，才能執行查詢。 | 這些資料欄必須用來加入 ID 映射資料表和協同合作資料表。 | ## ID 映射表分析規則預先定義的結構 ID 映射表分析規則的預先定義結構隨附套用到 `sourceID`和 的預設保護`targetID`。這表示在查詢中必須使用套用保護的 欄。 您可以透過下列方式設定 ID 映射表分析規則： + `sourceID` 和 皆`targetID`受保護 在此組態中， `sourceID`和 `targetID` 無法同時投影。參考 ID 映射表時， `sourceID`和 `targetID` 必須在 JOIN 中使用。 + 僅`targetID`受保護 在此組態中， `targetID` 無法投影。參考 ID 映射表時，`targetID`必須在 JOIN 中使用 。`sourceID` 可用於查詢。 + 僅`sourceID`受保護 在此組態中， `sourceID` 無法投影。參考 ID 映射表時，`sourceID`必須在 JOIN 中使用 。`targetID` 可用於查詢。 + 既不`sourceID`受保護也不`targetID`受保護 在此組態中，ID 映射表不受可在查詢中使用的任何特定強制執行約束。 下列範例顯示 ID 映射資料表分析規則的預先定義結構，其預設保護會套用至 `sourceID`和 `targetID`。在此範例中，ID 映射資料表分析規則僅允許資料`sourceID`欄和`targetID`資料欄上的 INNER JOIN。 ``` { "joinColumns": [ "source_id", "target_id" ], "queryConstraints": [ { "requireOverlap": { "columns": [ "source_id", "target_id" ] } } ], "dimensionColumns": [] // columns that can be used in SELECT and JOIN } ``` 下列範例顯示 ID 映射資料表分析規則的預先定義結構，其中包含套用至 的保護`targetID`。在此範例中，ID 映射資料表分析規則僅允許資料`sourceID`欄上的 INNER JOIN。 ``` { "joinColumns": [ "source_id", "target_id" ], "queryConstraints": [ { "requireOverlap": { "columns": [ "target_id" ] } } ], "dimensionColumns": [ "source_id" ] } ``` 下列範例顯示 ID 映射資料表分析規則的預先定義結構，其中包含套用至 的保護`sourceID`。在此範例中，ID 映射資料表分析規則僅允許資料`targetID`欄上的 INNER JOIN。 ``` { "joinColumns": [ "source_id", "target_id" ], "queryConstraints": [ { "requireOverlap": { "columns": [ "source_id" ] } } ], "dimensionColumns": [ "target_id" ] } ``` 下列範例顯示未將保護套用至 `sourceID`或 的 ID 映射資料表分析規則的預先定義結構`targetID`。在此範例中，ID 映射資料表分析規則允許資料`sourceID`欄和`targetID`資料欄上的 INNER JOIN。 ``` { "joinColumns": [ "source_id", "target_id" ], "queryConstraints": [ { "requireOverlap": { "columns": [] } } ], "dimensionColumns": [ "source_id", "target_id" ] } ``` ## ID 映射表分析規則 – 範例 例如，公司可以使用 ID 映射表分析規則來使用多方 LiveRamp 轉碼，而不是撰寫參考個人身分識別資訊 (PII) 的長瀑布陳述式。下列範例示範如何使用 ID AWS Clean Rooms 映射資料表分析規則在 中協作。 A 公司是擁有客戶和銷售資料的廣告商，將用作來源。A 公司也會代表合作中的各方執行轉碼，並帶來 LiveRamp 登入資料。 B 公司是具有事件資料的發佈者，將用作目標。 **注意** A 公司或 B 公司都可以提供 LiveRamp 轉碼登入資料並執行轉碼。 若要建立協同合作以啟用協同合作 ID 映射表分析，公司會執行下列動作： 1. A 公司建立協同合作並建立成員資格。它新增了 B 公司，該公司也會在協同合作中建立成員資格。 1. 公司 A 關聯現有的 ID 命名空間來源，或使用 AWS Clean Rooms 主控台 AWS Entity Resolution 在 中建立新的 ID 命名空間來源。 公司 A 會建立已設定的資料表及其銷售資料，並在 ID 映射資料表`sourceId`中建立索引鍵為 的資料欄。 ID 命名空間來源提供要轉碼的資料。 1. B 公司會關聯現有的 ID 命名空間目標，或使用 AWS Clean Rooms 主控台 AWS Entity Resolution 在 中建立新的 ID 命名空間目標。 B 公司會建立已設定的資料表，其中包含其事件資料，以及 ID 映射資料表`targetId`中索引鍵為 的資料欄。 ID 命名空間目標不提供要轉碼的資料，僅提供 LiveRamp 組態周圍的中繼資料。 1. A 公司探索與協同合作相關聯的兩個 ID 命名空間，並建立和填入 ID 映射表。 1. A 公司透過加入 ID 映射表，跨兩個資料集執行查詢。 ``` --- this would be valid for Custom or List SELECT provider.data_col, consumer.data_col FROM provider JOIN idMappingTable-123123123123-myMappingWFName idmt ON provider.id = idmt.sourceId JOIN consumer ON consumer.id = idmt.targetId ``` # AWS Clean Rooms 差異隱私權 AWS Clean Rooms 差異隱私權可協助您透過數學支援的技巧來保護使用者的隱私權，只需按幾下滑鼠，即可透過直覺式控制實作。作為全受管功能，不需要先前的差異隱私權體驗來協助您防止使用者重新識別。 AWS Clean Rooms 會自動新增仔細校正的雜訊量，以在執行時間查詢結果，以協助保護您的個人層級資料。 AWS Clean Rooms 差異隱私權支援各種分析查詢，非常適合各種使用案例，其中查詢結果中的少量錯誤不會影響分析的實用性。有了它，您的合作夥伴就可以產生有關廣告行銷活動、投資決策、臨床研究等的業務關鍵洞見，而不需要您合作夥伴的任何額外設定。 AWS Clean Rooms 差異隱私權可防止以惡意方式使用純量函數或數學運算子符號的溢位或無效轉換錯誤。 如需 AWS Clean Rooms 差異隱私權的詳細資訊，請參閱下列主題。 **Topics** + [差異隱私權](#dp-overview) + [中的差異隱私權如何 AWS Clean Rooms 運作](#dp-how-it-works) + [差異性隱私權政策](dp-settings.md) + [AWS Clean Rooms 差異隱私權的 SQL 功能](dp-sql-capabilities.md) + [不同的隱私權查詢秘訣和範例](dp-query-tips-examples.md) + [AWS Clean Rooms 差異性隱私權的限制](dp-limitations.md) ## 差異隱私權 差異隱私權僅允許彙總洞見，並混淆這些洞見中任何個人資料的貢獻。差異隱私權可保護協作資料，使其不會收到了解特定個人的結果。如果沒有差異隱私權，可以接收結果的成員可以嘗試透過新增或移除有關個人的記錄來推斷個別使用者資料，並觀察查詢結果的差異。 開啟差異隱私權時，指定的雜訊量會新增至查詢結果，以混淆個別使用者的貢獻。如果可接收結果的成員在從資料集中移除有關個人的記錄後嘗試觀察查詢結果的差異，查詢結果的變異性有助於防止識別個人的資料。 AWS Clean Rooms 差異隱私權使用 [SampCert](https://github.com/leanprover/SampCert) 採樣器，這是一種經過驗證的正確採樣器實作，由 開發 AWS。 ## 中的差異隱私權如何 AWS Clean Rooms 運作 在 中開啟差異隱私權[的工作流程，在完成工作流程 AWS Clean Rooms](what-is.md#how-it-works)時 AWS Clean Rooms 需要下列額外步驟： 1. 您可以在新增[自訂分析規則](analysis-rules-custom.md)時開啟差異隱私權。 1. [您可以為協同合作設定差異隱私權政策](configure-differential-privacy.md)，以使用差異隱私權來保護資料表以供查詢。 完成這些步驟後，可以查詢的成員可以開始對差異隱私權保護的資料執行查詢。 AWS Clean Rooms 會傳回符合差異隱私權政策的結果。 AWS Clean Rooms 差異隱私權會追蹤您可以執行的剩餘查詢預估數量，類似於顯示車輛目前油位的汽車氣位表。可以查詢的成員可以執行的查詢數量受限於 中設定的每個查詢參數的**隱私權預算**和新增的雜訊[差異性隱私權政策](dp-settings.md)。 **** ### 考量事項 在 中使用差異隱私權時 AWS Clean Rooms，請考慮下列事項： + 可以接收結果的成員無法使用差異隱私權。他們將針對其設定的資料表，設定關閉差異隱私權的自訂分析規則。 + 當兩個或多個資料提供者都開啟差異隱私權時，可以查詢的成員無法聯結來自兩個或多個資料提供者的資料表。 # 差異性隱私權政策 差異隱私權政策控制在協同合作中允許可查詢的成員執行多少彙總函數。**隱私權預算**定義了一個常見的有限資源，可套用協同合作中的所有資料表。**每個查詢新增的雜訊**會管理耗盡隱私權預算的速率。 需要差異隱私權政策，才能讓您的差異隱私權受保護資料表可供查詢。這是協作中的一次性步驟，包含兩個輸入： + **隱私權預算** – 根據 epsilon 量化，隱私權預算控制隱私權保護的層級。這是常見的有限資源，適用於在協同合作中受到差異隱私權保護的所有資料表，因為目標是保留使用者隱私，其資訊可以存在於多個資料表中。 每次在資料表上執行查詢時，都會耗用**隱私權預算**。當隱私權預算用盡時，可以查詢的協同合作成員在增加或重新整理之前無法執行其他查詢。透過設定更大的隱私權預算，可以接收結果的成員可以減少他們對資料中個人的不確定性。選擇在諮詢業務決策者之後，平衡協同合作需求與隱私權需求的隱私權預算。 如果您打算定期將新資料帶入協同合作，您可以選取**每月重新整理隱私權預算**，以每月自動建立新的隱私權預算。選擇此選項可在跨重新整理重複查詢時，顯示有關資料列的任意資訊量。如果在隱私權預算重新整理之間重複查詢相同的資料列，請避免選擇此選項。 + **每個查詢新增的雜訊**是根據您要隱藏貢獻的使用者數量來衡量。此值會管理耗盡隱私權預算的速率。較大的雜訊值可減少耗盡隱私權預算的速率，因此允許對資料執行更多查詢。不過，這應與發佈不準確的資料洞見相平衡。設定此值時，請考慮協作洞察所需的準確性。 您可以使用預設差異隱私權政策，根據您的使用案例快速完成設定或自訂差異隱私權政策。 AWS Clean Rooms 差異隱私權提供直覺式控制來設定政策。 AWS Clean Rooms 差異隱私權可讓您根據資料上所有查詢中可能的彙總數目預覽公用程式，並預估在資料協同合作中可以執行多少查詢。 您可以使用互動式範例，了解每個查詢新增的不同**隱私權預算**和雜訊值如何影響不同類型的 SQL 查詢的結果。 ****一般而言，您需要平衡隱私權需求與要允許的查詢數量，以及這些查詢的準確性。每個查詢新增的較小**隱私權預算**或較大雜訊可以更好地保護使用者隱私權，但為您的協作合作夥伴提供較不有意義的洞見。 **** 如果您增加**隱私權預算**，同時保持**每個查詢參數新增的雜訊**相同，則可以查詢的成員可以在協同合作中的資料表上執行更多彙總。您可以在協同合作期間隨時增加**隱私權預算**。如果您減少**隱私權預算**，同時保持**每個查詢參數新增的雜訊**相同，可以查詢的成員可以執行較少的彙總。在可以查詢的成員開始分析您的資料之後，您無法減少**隱私權預算**。 如果您增加**每個查詢新增的雜訊**，同時保持**隱私權預算**輸入相同，則可以查詢的成員可以在協同合作中對資料表執行更多彙總。如果您減少**每個查詢新增的雜訊**，同時保持**隱私權預算**輸入相同，可以查詢的成員可以執行較少的彙總。您可以在協同合作期間隨時增加或減少**每個查詢新增的雜訊**。 差異隱私權政策是由隱私權預算範本 API 動作管理。 # AWS Clean Rooms 差異隱私權的 SQL 功能 AWS Clean Rooms 差異隱私權使用一般用途查詢結構來支援複雜的 SQL 查詢。根據此結構驗證自訂分析範本，以確保它們可以在受差異隱私權保護的資料表上執行。下表指出支援哪些 函數。如需詳細資訊，請參閱[查詢結構和語法](analysis-rules-custom.md#dp-query-structure-syntax)。 | Category | Spark 分析引擎支援的 SQL 建構 | 常見資料表表達式 (CTEs) | 最終 SELECT 子句 | | --- |--- |--- |--- | | Aggregate functions | ANY\$1VALUE 函數 APPROXIMATE PERCENTILE\$1DISC 函數 AVG 函數 COUNT 和 COUNT DISTINCT 函數 MAX 函數 MEDIAN 函數 MIN 函數 PERCENTILE\$1CONT 函數 STDDEV\$1SAMP 和 STDDEV\$1POP 函數 SUM 和 SUM DISTINCT 函數 VAR\$1SAMP 和 VAR\$1POP 函數 | Supported with the condition that CTEs using differential privacy protected tables must result in data with user-level records. You should write the SELECT expression in those CTEs using `SELECT userIdentifierColumn...' format. | Supported aggregations: AVG, COUNT, COUNT DISTINCT, STDDEV, and SUM. | | CTEs | WITH clause, WITH clause subquery | Supported with the condition that CTEs using differential privacy protected tables must result in data with user-level records. You should write the SELECT expression in those CTEs using `SELECT userIdentifierColumn...' format. | N/A | | Subqueries | SELECT HAVING JOIN JOIN 條件 FROM WHERE | You can have any subquery that doesn't reference differential privacy relations in these constructs. You can have any subquery that references differential privacy relations in a FROM and JOIN clause only. | | Join clauses | INNER JOIN LEFT JOIN 左半聯結 左 ANTI 加入 RIGHT JOIN 完整加入 【JOIN】 OR 運算子 CROSS JOIN | 支援的條件是，在使用者識別符資料欄上僅支援等同聯結的 JOIN 函數，並且在查詢開啟差異隱私權的兩個或多個資料表時是強制性的。確保強制性的同等加入條件是正確的。確認資料表擁有者已在所有資料表中設定相同的使用者識別符欄，以便使用者的定義在資料表之間保持一致。 在開啟差異隱私權的情況下結合兩個或多個關係時，不支援 CROSS JOIN 函數。 | | Set operators | UNION, UNION ALL, INTERSECT, EXCEPT \$1 MINUS (these are synonyms) | UNION, UNION ALL, INTERSECT, EXCEPT \$1 MINUS (these are synonyms) | Not supported | | Window functions | 彙總函數 AVG 範圍函數 COUNT 範圍函數 CUME\$1DIST 範圍函數 DENSE\$1RANK 範圍函數 FIRST\$1VALUE 範圍函數 LAG 範圍函數 LAST\$1VALUE 範圍函數 LEAD 範圍函數 MAX 視窗函數 MEDIAN 視窗函數 MIN 視窗函數 NTH\$1VALUE 範圍函數 STDDEV\$1SAMP 和 STDDEV\$1POP 視窗函數 (STDDEV\$1SAMP 和 STDDEV 是同義詞） SUM 視窗函數 VAR\$1SAMP 和 VAR\$1POP 視窗函數 (VAR\$1SAMP 和 VARIANCE 是同義詞） 排名函數 DENSE\$1RANK 範圍函數 NTILE 範圍函數 PERCENT\$1RANK 範圍函數 RANK 範圍函數 ROW\$1NUMBER 範圍函數 | All are supported with the condition that the user identifier column in the window function's partition clause is required when you query a relation with differential privacy turned on. | Not supported | | Conditional expressions | CASE 條件表達式 COALESCE 表達式 GREATEST 和 LEAST 函數 NVL 和 COALESCE 函數 NVL2 函數 NULLIF 函數 | All are supported | All are supported | | Conditions | 比較條件 邏輯條件 模式比對條件 BETWEEN 範圍條件 Null 條件 | EXISTS and IN can't be used because they require subqueries. All others are supported. | All are supported | | Date-time functions | 交易中日期與時間函數 串連運算子 ADD\$1MONTHS 函數 CONVERT\$1TIMEZONE 函數 CURRENT\$1DATE 函數 DATEADD 函數 DATEDIFF 函數 DATE\$1PART 函數 DATE\$1TRUNC 函數 EXTRACT 函數 TO\$1TIMESTAMP 函數 日期或時間戳記函數的日期部分 | All are supported | All are supported | | String functions | \$1\$1 （串連） 運算子 BTRIM 函數 CHAR\$1LENGTH 函數 CHARACTER\$1LENGTH 函數 CONCAT 函數 LEFT 和 RIGHT 函數 LEN 函數 LENGTH 函數 LOWER 函數 LPAD 和 RPAD 函數 LTRIM 函數 POSITION 函數 REGEXP\$1COUNT 函數 REGEXP\$1INSTR 函數 REGEXP\$1REPLACE 函數 REGEXP\$1SUBSTR 函數 REPEAT 函數 REPLACE 函數 REVERSE 函數 RTRIM 函數 SPLIT\$1PART 函數 SUBSTRING 函數 TRANSLATE 函數 TRIM 函數 UPPER 函數 | All are supported | All are supported | | Data type formatting functions | CAST 函數 TO\$1CHAR TO\$1DATE 陣列 TO\$1NUMBER 日期時間格式字串 數值格式字串 | All are supported | All are supported | | Hash functions | AES\$1ENCRYPT AES\$1DECRYPT ENCODE DECODE MD5 函數 SHA1 函數 SHA2 函數 XX\$1HASH64 | All are supported | All are supported | | Mathematical operator symbols | \$1, -, \$1, /, %, and @ | All are supported | All are supported | | Math functions | ABS 函數 ACOS 函數 ASIN 函數 ATAN 函數 ATAN2 函數 CBRT 函數 CEILING (或 CEIL) 函數 COS 函數 COT 函數 DEGREES 函數 LTRIM 函數 EXP 函數 FLOOR 函數 LN 函數 LOG 函數 MOD 函數 PI 函數 POWER 函數 RADIANS 函數 RANDOM 函數 ROUND 函數 SIGN 函數 SIN 函數 SQRT 函數 TRUNC 函數 | All are supported | All are supported | | VARBYTE functions | UNHEX、 UNBASE64 HEX HLL\$1SKETCH\$1AGG、 HLL\$1SKETCH\$1ESTIMATE HLL\$1UNION HLL\$1UNION\$1AGG | All are supported | All are supported | | JSON | TO\$1JSON GET\$1JSON\$1OBJECT | All are supported | All are supported | | Array functions | ARRAY\$1CONTAINS ARRAY\$1DISTINCT ARRAY\$1EXCEPT ARRAY\$1INTERSECT ARRAY\$1JOIN ARRAY\$1REMOVE ARRAY\$1SORT ARRAY\$1UNION | Not supported | Not supported | | Extended GROUP BY | GROUPING SETS, ROLLUP, CUBE | Not supported | Not supported | | Sort operation | ORDER BY | Supported with the condition that an ORDER BY clause is only supported in a window function's partition clause when querying tables with differential privacy turned on. | Supported | | Row limits | LIMIT, OFFSET | Not supported in CTEs using differential privacy protected tables | All are supported | | Table and column aliasing | | Supported | Supported | | Math functions on aggregate functions | | Supported | Supported | | Scalar functions within aggregate functions | | Supported | Supported | ## 不支援 SQL 建構的常見替代方案 | Category | SQL 建構 | 備用 | | --- |--- |--- | | 範圍函數 | LISTAGG PERCENTILE\$1CONT PERCENTILE\$1DISC | You can use the equivalent aggregate function with GROUP BY. | | Mathematical operator symbols | \$1column \$1\$1/ 2 \$1column \$1/ 2 \$1column ^ 2 | CBRT SQRT POWER(\$1column， 2) | | Scalar functions | SYSDATE \$1column：：integer convert(type， \$1column) | CURRENT\$1DATE CAST \$1column AS 整數 CAST \$1column AS 類型 | | Literals | INTERVAL ‘1 SECOND' | INTERVAL '1' SECOND | | Row limiting | TOP n | LIMIT n | | Join | USING NATURAL | ON clause should explicitly contain a join criterion. | # 不同的隱私權查詢秘訣和範例 AWS Clean Rooms 差異隱私權使用[一般用途查詢結構](dp-sql-capabilities.md)來支援各種 SQL 建構，例如用於資料準備的通用資料表表達式 (CTEs)，以及常用的彙總函數，例如 `COUNT`、 或 `SUM`。為了透過新增雜訊以在執行時間彙總查詢結果來混淆資料中任何可能使用者的貢獻， AWS Clean Rooms 差異隱私要求最終的彙總函數`SELECT statement`在使用者層級資料上執行。 下列範例使用兩個名為 `socialco_impressions`和 `socialco_users` 的資料表，來自媒體發佈者，他們想要使用差異隱私權保護資料，同時與運動品牌與`athletic_brand_sales`資料協作。媒體發佈者已將資料`user_id`欄設定為使用者識別符資料欄，同時啟用差異隱私權 AWS Clean Rooms。廣告商不需要差異隱私權保護，並想要在合併資料上使用 CTEs執行查詢。由於其 CTE 使用差異隱私保護資料表，廣告商會在 CTE 資料欄清單中包含那些受保護資料表的使用者識別符資料欄，並聯結使用者識別符資料欄上的受保護資料表。 ``` WITH matches_table AS( SELECT si.user_id, si.campaign_id, s.sale_id, s.sale_price FROM socialco_impressions si JOIN socialco_users su ON su.user_id = si.user_id JOIN athletic_brand_sales s ON s.emailsha256 = su.emailsha256 WHERE s.timestamp > si.timestamp UNION ALL SELECT si.user_id, si.campaign_id, s.sale_id, s.sale_price FROM socialco_impressions si JOIN socialco_users su ON su.user_id = si.user_id JOIN athletic_brand_sales s ON s.phonesha256 = su.phonesha256 WHERE s.timestamp > si.timestamp ) SELECT COUNT (DISTINCT user_id) as unique_users FROM matches_table GROUP BY campaign_id ORDER BY COUNT (DISTINCT user_id) DESC LIMIT 5 ``` 同樣地，如果您想要在差異隱私權保護資料表上執行視窗函數，則必須在 `PARTITION BY`子句中包含使用者識別符欄。 ``` ROW_NUMBER() OVER (PARTITION BY conversion_id, user_id ORDER BY match_type, match_age) AS row ``` # AWS Clean Rooms 差異性隱私權的限制 AWS Clean Rooms 差異隱私權不會處理下列情況： 1. AWS Clean Rooms 差異隱私權僅支援使用 Amazon S3 後端 AWS Glue 資料表的查詢。它不支援使用 Snowflake 或 Amazon Athena 資料表進行查詢。 1. AWS Clean Rooms 差異隱私權不會處理計時攻擊。例如，在個別使用者貢獻大量資料列，並新增或移除此使用者會大幅變更查詢運算時間的情況下，這些攻擊是可能的。 1. AWS Clean Rooms 當 SQL 查詢可能因使用特定 SQL 建構而導致執行時間溢位或無效的轉換錯誤時，差異隱私權並不保證差異隱私權。 下表列出一些但並非全部的 SQL 建構，這些建構可能會產生執行時間錯誤，並且應在分析範本中驗證。我們建議您核准分析範本，以將此類執行時間錯誤的機率降至最低，並定期檢閱查詢日誌，以判斷查詢是否符合協同合作協議。 下列 SQL 建構容易發生溢位錯誤： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/dp-limitations.html) 1. CAST 資料類型格式化函數容易發生無效的轉換錯誤。 您可以設定 [CloudWatch 為日誌群組建立指標篩選條件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CreateMetricFilterProcedure.html)，然後在該指標篩選條件上[建立 CloudWatch 警示](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Alarm-On-Logs.html)，以便在遇到潛在溢位或轉換錯誤時接收提醒。 具體而言，您應該監控錯誤代碼 `CastError`、`OverflowError`、`ConversionError`。這些錯誤代碼的存在表示潛在的側通道攻擊，但可能表示錯誤的 SQL 查詢。 如需詳細資訊，請參閱[分析登入 AWS Clean Rooms](query-logs.md)。 # AWS 無塵室 ML AWS Clean Rooms ML 允許兩方或多方對其資料執行機器學習模型，而不需要彼此共用其資料。此服務提供隱私權增強控制，允許資料擁有者保護其資料及其模型 IP。您可以使用 AWS 撰寫的模型或自帶自訂模型。 如需如何運作的詳細說明，請參閱 [跨帳戶任務](ml-behaviors.md#ml-behaviors-cross-account-jobs)。 如需 Clean Rooms ML 模型功能的詳細資訊，請參閱下列主題。 **Topics** + [AWS Clean Rooms ML 術語](#ml-terminology) + [AWS Clean Rooms ML 如何與 AWS 模型搭配使用](#ml-how-it-works) + [AWS Clean Rooms ML 如何與自訂模型搭配使用](#custML-how-it-works) + [AWS Clean Rooms ML 中的模型](aws-models.md) + [Clean Rooms ML 中的自訂模型](custom-models.md) ## AWS Clean Rooms ML 術語 使用 Clean Rooms ML 時，請務必了解下列術語： + *訓練資料提供者* – 提供訓練資料的一方，建立和設定類似模型，然後將類似模型與協同合作建立關聯。 + *種子資料提供者* – 貢獻種子資料、產生外觀客群，以及匯出其外觀客群的一方。 + *訓練資料* – 訓練資料提供者的資料，用於產生類似模型。訓練資料用於測量使用者行為中的相似性。 訓練資料必須包含使用者 ID、項目 ID 和時間戳記欄。或者，訓練資料可以包含數值或分類特徵的其他互動。互動的範例包括觀看的影片、購買的項目或文章讀取的清單。 + *種子資料* – 種子資料提供者的資料，用於建立外觀相似的區段。種子資料可以直接提供，也可以來自 AWS Clean Rooms 查詢的結果。類客群輸出是一組來自訓練資料的 使用者，最接近種子使用者。 + *Lookalike 模型* – 訓練資料的機器學習模型，用於在其他資料集中找到類似的使用者。 使用 API 時，*對象模型*一詞會同等用於看起來像模型。例如，您可以使用 [CreateAudienceModel](https://docs.aws.amazon.com/cleanrooms-ml/latest/APIReference/API_CreateAudienceModel.html) API 來建立類似模型。 + *Lookalike 區段* – 訓練資料的子集，最接近種子資料。 使用 API 時，您可以使用 [StartAudienceGenerationJob](https://docs.aws.amazon.com/cleanrooms-ml/latest/APIReference/API_StartAudienceGenerationJob.html) API 建立類似樣的客群。 訓練資料提供者的資料絕不會與種子資料提供者共用，而種子資料提供者的資料也絕不會與訓練資料提供者共用。看起來像區段的輸出會與訓練資料提供者共用，但永遠不會與種子資料提供者共用。 ## AWS Clean Rooms ML 如何與 AWS 模型搭配使用 ![\[AWS Clean Rooms ML 如何與 AWS 模型搭配使用的概觀。\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/images/howItWorksML.png) 使用類似模型需要兩個方，訓練資料提供者和種子資料提供者，依序在 中工作 AWS Clean Rooms ，將他們的資料帶入協同合作。這是訓練資料提供者必須先完成的工作流程： 1. 訓練資料提供者的資料必須存放在使用者項目互動 AWS Glue 的資料目錄資料表中。訓練資料至少必須包含使用者 ID 欄、互動 ID 欄和時間戳記欄。 1. 訓練資料提供者向 註冊訓練資料 AWS Clean Rooms。 1. 訓練資料提供者會建立外觀相似的模型，可與多個種子資料提供者共用。外觀模型是一種深度神經網路，最多可能需要 24 小時才能訓練。它不會自動重新訓練，我們建議您每週重新訓練模型。 1. 訓練資料提供者會設定類似模型，包括是否共用相關性指標和輸出區段的 Amazon S3 位置。訓練資料提供者可以從單一外觀模型建立多個已設定的外觀模型。 1. 訓練資料提供者會將設定的對象模型與與種子資料提供者共用的協同合作建立關聯。 這是種子資料提供者接下來必須完成的工作流程： 1. 種子資料提供者的資料可以存放在 Amazon S3 儲存貯體中，也可以來自查詢結果。 1. 種子資料提供者會開啟他們與訓練資料提供者共用的協同合作。 1. 種子資料提供者會從協作頁面的 Clean Rooms ML 索引標籤建立外觀相似的區段。 1. 如果已共用關聯性指標，則種子資料提供者可以評估它們，並匯出外觀區段以供外部使用 AWS Clean Rooms。 ## AWS Clean Rooms ML 如何與自訂模型搭配使用 透過 Clean Rooms ML，協同合作的成員可以使用存放在 Amazon ECR 中的停駐自訂模型演算法來共同分析其資料。若要這樣做，*模型提供者*必須建立映像並將其存放在 Amazon ECR 中。請遵循 [Amazon Elastic Container Registry 使用者指南](https://docs.aws.amazon.com/AmazonECR/latest/userguide/)中的步驟，建立將包含自訂 ML 模型的私有儲存庫。 協同合作的任何成員都可以是*模型提供者*，只要他們具有正確的許可。協同合作的所有成員都可以為模型提供訓練資料、推論資料或兩者。基於本指南的目的，貢獻資料的成員稱為*資料提供者*。建立協同合作的成員是*協同合作建立*者，而此成員可以是*模型提供者*、其中一個*資料提供者*，或兩者。 在最高層級，以下是執行自訂 ML 建模時必須完成的步驟： 1. 協同合作建立者會建立協同合作，並為每個成員指派適當的成員能力和付款組態。協同合作建立者必須指派成員接收模型輸出或接收推論結果的能力給此步驟中的適當成員，因為它無法在協同合作建立後更新。如需詳細資訊，請參閱[在 AWS Clean Rooms ML 中建立和加入協同合作](create-custom-ml-collaboration.md)。 1. 模型提供者會設定其容器化 ML 模型並將其與協同合作建立關聯，並確保針對匯出的資料設定隱私權限制。如需詳細資訊，請參閱[在 AWS Clean Rooms ML 中設定模型演算法](configure-model-algorithm.md)。 1. 資料提供者將其資料提供給協同合作，並確保已指定其隱私權需求。資料提供者必須允許模型存取其資料。如需詳細資訊，請參閱[在 AWS Clean Rooms ML 中貢獻訓練資料](custom-model-training-data.md)及[在 AWS Clean Rooms ML 中關聯設定的模型演算法](associate-model-algorithm.md)。 1. 協同合作成員會建立 ML 組態，定義模型成品或推論結果的匯出位置。 1. 協同合作成員會建立 ML 輸入通道，提供訓練容器或推論容器的輸入。ML 輸入通道是一種查詢，可定義要在模型演算法內容中使用的資料。 1. 協作成員使用 ML 輸入通道和設定的模型演算法叫用模型訓練。如需詳細資訊，請參閱[在 AWS Clean Rooms ML 中建立訓練過的模型](create-trained-model.md)。 1. （選用） 模型訓練器會叫用模型匯出任務，並將模型成品傳送至模型結果接收者。只有具有有效 ML 組態和能夠接收模型輸出的成員才能接收模型成品。如需詳細資訊，請參閱[從 AWS Clean Rooms ML 匯出模型成品](export-model-artifacts.md)。 1. （選用） 協同合作成員使用 ML 輸入通道、訓練模型 ARN 和推論設定的模型演算法叫用模型推論。推論結果會傳送至推論輸出接收器。只有具有有效 ML 組態和能夠接收推論輸出的成員才能接收推論結果。 以下是*模型提供者*必須完成的步驟： 1. 建立與 SageMaker AI 相容的 Amazon ECR Docker 映像。Clean Rooms ML 僅支援 SageMaker AI 相容 Docker 映像。 1. 建立 SageMaker AI 相容 Docker 映像之後，請將映像推送至 Amazon ECR。遵循 [Amazon Elastic Container Registry 使用者指南](https://docs.aws.amazon.com/AmazonECR/latest/userguide/)中的指示來建立容器訓練映像。 1. 設定模型演算法以用於 Clean Rooms ML。 1. 提供設定模型演算法所需的 Amazon ECR 儲存庫連結和任何引數。 1. 提供服務存取角色，允許 Clean Rooms ML 存取 Amazon ECR 儲存庫。 1. 將設定的模型演算法與協同合作建立關聯。這包括提供隱私權政策，定義容器日誌、故障日誌、CloudWatch 指標的控制，以及可從容器結果匯出多少資料的限制。 以下是*資料提供者*必須完成的步驟，才能與自訂 ML 模型協作： 1. 使用自訂分析規則設定現有 AWS Glue 資料表。這允許一組特定的預先核准查詢或預先核准的帳戶使用您的資料。 1. 將設定的資料表與協同合作建立關聯，並提供可存取 AWS Glue 資料表的服務存取角色。 1. [將協同合作分析規則](add-collaboration-analysis-rule.md)新增至資料表，以允許設定的模型演算法關聯存取設定的資料表。 1. 在 Clean Rooms ML 中關聯和設定模型和資料之後，具有執行查詢功能的成員會提供 SQL 查詢，並選取要使用的模型演算法。 模型訓練完成後，該成員會啟動模型訓練成品或推論結果的匯出。這些成品或結果會傳送給能夠接收訓練模型輸出的成員。結果接收者必須先設定其 ，`MachineLearningConfiguration`才能接收模型輸出。 # AWS Clean Rooms ML 中的模型 AWS Clean Rooms ML 為雙方提供隱私權保護方法，以識別其資料中的類似使用者，而無需彼此共用其資料。第一方將訓練資料帶到 ， AWS Clean Rooms 以便他們可以建立和設定類似模型，並將其與協同合作建立關聯。然後，種子資料會帶入協同合作，以建立類似訓練資料的外觀客群。 如需如何運作的詳細說明，請參閱 [跨帳戶任務](ml-behaviors.md#ml-behaviors-cross-account-jobs)。 下列主題提供如何在 Clean Rooms ML 中建立和設定 AWS 模型的相關資訊。 **Topics** + [AWS Clean Rooms ML 的隱私權保護](ml-privacy.md) + [Clean Rooms ML 的訓練資料需求](ml-training-data-requirements.md) + [Clean Rooms ML 的種子資料需求](ml-seed-data-requirements.md) + [AWS Clean Rooms ML 模型評估指標](ml-metrics.md) # AWS Clean Rooms ML 的隱私權保護 Clean Rooms ML 旨在降低*成員資格推論攻擊*的風險，訓練資料提供者可以了解種子資料中的人物，而種子資料提供者可以了解訓練資料中的人物。採取幾個步驟來防止此攻擊。 首先，種子資料提供者不會直接觀察 Clean Rooms ML 輸出，而訓練資料提供者永遠無法觀察種子資料。種子資料提供者可以選擇在輸出區段中包含種子資料。 接著，從訓練資料的隨機樣本建立外觀模型。此範例包含大量不符合種子受眾的使用者。此程序可讓您更難判斷使用者是否不在資料中，這是成員資格推論的另一個途徑。 此外，多個種子客戶可用於種子特定樣模型訓練的每個參數。這限制了模型可過度擬合的程度，以及可推斷有關使用者的程度。因此，我們建議種子資料的大小下限為 500 個使用者。 最後，使用者層級指標永遠不會提供給訓練資料提供者，這會消除成員資格推論攻擊的另一個途徑。 # Clean Rooms ML 的訓練資料需求 若要成功建立類似模型，您的訓練資料必須符合下列要求： + 訓練資料必須是 Parquet、CSV 或 JSON 格式。 **注意** 不支援 Zstandard (ZSTD) 壓縮 Parquet 資料。 + 您的訓練資料必須編製目錄 AWS Glue。如需詳細資訊，請參閱《 AWS Glue 開發人員指南》中的 [ AWS Glue Data Catalog 入門](https://docs.aws.amazon.com//glue/latest/dg/start-data-catalog.html)。我們建議您使用 AWS Glue 爬蟲程式來建立資料表，因為系統會自動推斷結構描述。 + 包含訓練資料和種子資料的 Amazon S3 儲存貯體位於與其他 Clean Rooms ML 資源相同的 AWS 區域。 + 訓練資料必須至少包含 100，000 個唯一使用者 IDs，每個 ID 至少有兩個項目互動。 + 訓練資料必須至少包含 100 萬筆記錄。 + [CreateTrainingDataset](https://docs.aws.amazon.com/cleanrooms-ml/latest/APIReference/API_CreateTrainingDataset.html) 動作中指定的結構描述必須與建立 AWS Glue 資料表時定義的結構描述相符。 + 在 [CreateTrainingDataset](https://docs.aws.amazon.com/cleanrooms-ml/latest/APIReference/API_CreateTrainingDataset.html) 動作中定義了所提供資料表中定義的必要欄位。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/ml-training-data-requirements.html) + 或者，您可以提供總共最多 10 個分類或數值功能。 以下是 CSV 格式的有效訓練資料集範例 ``` USER_ID,ITEM_ID,TIMESTAMP,EVENT_TYPE(CATEGORICAL FEATURE),EVENT_VALUE (NUMERICAL FEATURE) 196,242,881250949,click,15 186,302,891717742,click,13 22,377,878887116,click,10 244,51,880606923,click,20 166,346,886397596,click,10 ``` # Clean Rooms ML 的種子資料需求 類似模型的種子資料可以直接來自 Amazon S3 儲存貯體或 SQL 查詢的結果。 直接提供的種子資料必須符合下列要求： + 種子資料必須是具有使用者 IDs 清單的 JSON 行格式。 + 種子大小應介於 25 到 500，000 個唯一的使用者 IDs 之間。 + 種子使用者的最小數量必須符合您建立設定的對象模型時指定的最小相符種子大小值。 以下是 CSV 格式的有效訓練資料集範例 ``` {"user_id": "abc"} {"user_id": "def"} {"user_id": "ghijkl"} {"user_id": "123"} {"user_id": "456"} {"user_id": "7890"} ``` # AWS Clean Rooms ML 模型評估指標 Clean Rooms ML 會計算*召回*和*相關性分數*，以判斷模型的效能。Recall 會比較類似資料和訓練資料之間的相似性。相關性分數用於決定受眾應達到多大，而不是模型是否表現良好。 *Recall* 是衡量類似區段與訓練資料相似度的無偏差指標。Recall 是來自訓練資料範例中最相似的使用者百分比 （預設為最相似的 20%)，由受眾產生任務包含在種子受眾中。值範圍介於 0-1 之間，較大的值表示更好的對象。大約等於最大儲存貯體百分比的回收值表示對象模型等同於隨機選取。 我們認為這是比準確性、精確度和 F1 分數更好的評估指標，因為在建置模型時，Clean Rooms ML 沒有準確標記真正的負面使用者。 區段層級*相關性分數*是相似度的指標，其值範圍從 -1 （最不相似） 到 1 （最相似）。Clean Rooms ML 會針對各種客群大小計算一組相關性分數，協助您判斷資料的最佳客群大小。關聯性分數會隨著區段大小的增加而單調減少，因此隨著區段大小的增加，它可能會與種子資料較不相似。當區段層級相關性分數達到 0 時，模型會預測外觀區段中的所有使用者都來自與種子資料相同的分佈。增加輸出大小可能會包含在看起來像區段中的使用者，這些使用者不是來自與種子資料相同的分佈。 關聯性分數會在單一行銷活動中標準化，不應用於跨行銷活動進行比較。關聯性分數不應用作任何業務成果的單一來源證據，因為除了相關性之外，這些分數還受到多個複雜因素的影響，例如庫存品質、庫存類型、廣告時間等。 關聯性分數不應用來判斷種子的品質，而是是否可以增加或減少。請考量下列範例： + 所有正分數 – 這表示預測為類似 的輸出使用者比包含在類似 區段中更多。這對於屬於大型市場一部分的種子資料很常見，例如過去一個月內購買過含括物的每個人。我們建議查看較小的種子資料，例如在過去一個月中購買一次以上的每個消費者。 + 您所需類似區段大小的所有負數分數或負數 – 這表示 Clean Rooms ML 預測所需類似區段大小中沒有足夠的類似使用者。這可能是因為種子資料太具體或市場太小。我們建議將較少的篩選條件套用至種子資料或擴大市場。例如，如果原始種子資料是購買助行器和汽車座位的客戶，您可以將市場擴展到購買多個嬰兒產品的客戶。 訓練資料提供者會判斷是否公開相關性分數，以及計算相關性分數的儲存貯體。 # Clean Rooms ML 中的自訂模型 透過 Clean Rooms ML，協同合作的成員可以使用存放在 Amazon ECR 中的停駐自訂模型演算法來共同分析其資料。若要這樣做，*模型提供者*必須建立映像並將其存放在 Amazon ECR 中。請遵循 [Amazon Elastic Container Registry 使用者指南](https://docs.aws.amazon.com/AmazonECR/latest/userguide/)中的步驟，建立將包含自訂 ML 模型的私有儲存庫。 協同合作的任何成員都可以是*模型提供者*，只要他們具有正確的許可。協同合作的所有成員都可以為模型提供資料。基於本指南的目的，貢獻資料的成員稱為*資料提供者*。建立協同合作的成員是*協同合作建立*者，而此成員可以是*模型提供者*、其中一個*資料提供者*，或兩者。 下列主題說明建立自訂 ML 模型所需的資訊 **Topics** + [自訂 ML 建模先決條件](custom-model-prerequisites.md) + [訓練容器的模型撰寫準則](custom-model-guidelines.md) + [推論容器的模型撰寫準則](inference-model-guidelines.md) + [接收模型日誌和指標](custom-model-logs.md) # 自訂 ML 建模先決條件 在執行自訂 ML 建模之前，您應該考慮下列事項： + 判斷是否將在協同合作中對訓練模型執行模型訓練和推論。 + 決定每個協同合作成員將執行的角色，並將適當的能力指派給他們。 + 將`CAN_QUERY`功能指派給將訓練模型並在訓練模型上執行推論的成員。 + `CAN_RECEIVE_RESULTS` 將 指派給至少一位協同合作的成員。 + 將 `CAN_RECEIVE_MODEL_OUTPUT`或 `CAN_RECEIVE_INFERENCE_OUTPUT` 功能指派給將分別接收訓練模型匯出或推論輸出的成員。如果您的使用案例需要這兩種功能，您可以選擇使用這兩種功能。 + 決定您將允許匯出的訓練模型成品或推論結果的大小上限。 + 我們建議所有使用者將 `CleanrooomsFullAccess`和 `CleanroomsMLFullAccess`政策連接到其角色。使用自訂 ML 模型需要使用 AWS Clean Rooms 和 AWS Clean Rooms ML SDKs。 + 請考慮下列有關 IAM 角色的資訊。 + 所有資料提供者都必須具有服務存取角色， AWS Clean Rooms 允許 從其 AWS Glue 目錄和資料表以及基礎 Amazon S3 位置讀取資料。這些角色類似於 SQL 查詢所需的角色。這可讓您使用 `CreateConfiguredTableAssociation`動作。如需詳細資訊，請參閱[建立服務角色以建立設定的資料表關聯](ml-roles.md#ml-roles-custom-configure-table)。 + 所有想要接收指標的成員都必須具有服務存取角色，允許他們撰寫 CloudWatch 指標和日誌。Clean Rooms ML 使用此角色，在模型訓練和推論 AWS 帳戶 期間將所有模型指標和日誌寫入成員的 。我們也提供隱私權控制，以判斷哪些成員可以存取指標和日誌。這可讓您使用 `CreateMLConfiguration`動作。如需詳細資訊，請參閱 [建立自訂 ML 建模的服務角色 - ML 組態](ml-roles.md#ml-roles-custom-configure)。 接收結果的成員必須為服務存取角色提供寫入其 Amazon S3 儲存貯體的許可。此角色允許 Clean Rooms ML 將結果 （訓練過的模型成品或推論結果） 匯出至 Amazon S3 儲存貯體。這可讓您使用 `CreateMLConfiguration`動作。如需詳細資訊，請參閱[建立自訂 ML 建模的服務角色 - ML 組態](ml-roles.md#ml-roles-custom-configure)。 + 模型提供者必須為服務存取角色提供讀取其 Amazon ECR 儲存庫和映像的許可。這可讓您使用 `CreateConfigureModelAlgorithm`動作。如需詳細資訊，請參閱[建立服務角色以提供自訂 ML 模型](ml-roles.md#ml-roles-custom-model-provider)。 + 建立 `MLInputChannel` 以產生資料集以進行訓練或推論的成員必須提供服務存取角色，允許 Clean Rooms ML 在其中執行 SQL 查詢 AWS Clean Rooms。這可讓您使用 `CreateTrainedModel`和 `StartTrainedModelInferenceJob`動作。如需詳細資訊，請參閱[建立服務角色以查詢資料集](ml-roles.md#ml-roles-custom-query-dataset)。 + 模型作者應遵循 [訓練容器的模型撰寫準則](custom-model-guidelines.md)和 [推論容器的模型撰寫準則接收模型日誌和指標](inference-model-guidelines.md)，以確保模型輸入和輸出依預期進行設定 AWS Clean Rooms。 # 訓練容器的模型撰寫準則 本節詳細說明模型提供者在為 Clean Rooms ML 建立自訂 ML 模型演算法時應遵循的準則。 + 使用適當的 SageMaker AI 訓練支援的容器基礎映像，如 [SageMaker AI 開發人員指南](https://docs.aws.amazon.com/sagemaker/latest/dg-ecr-paths/sagemaker-algo-docker-registry-paths.html)中所述。下列程式碼可讓您從公有 SageMaker AI 端點提取支援的容器基礎映像。 ``` ecr_registry_endpoint='763104351884.dkr.ecr.$REGION.amazonaws.com' base_image='pytorch-training:2.3.0-cpu-py311-ubuntu20.04-sagemaker' aws ecr get-login-password --region $REGION | docker login --username AWS --password-stdin $ecr_registry_endpoint docker pull $ecr_registry_endpoint/$base_image ``` + 在本機編寫模型時，請確保下列事項，以便您可以在本機、開發執行個體、 中的 SageMaker AI Training AWS 帳戶和 Clean Rooms ML 上測試模型。 + 我們建議您撰寫訓練指令碼，透過各種環境變數存取有關訓練環境的實用屬性。Clean Rooms ML 使用以下引數來調用模型程式碼的訓練：`SM_MODEL_DIR`、`SM_CHANNEL_TRAIN`、 `SM_OUTPUT_DIR`和 `FILE_FORMAT`。Clean Rooms ML 使用這些預設值，在自己的執行環境中使用來自各方的資料來訓練 ML 模型。 + Clean Rooms ML 可讓您透過 Docker 容器中的`/opt/ml/input/data/channel-name`目錄使用訓練輸入通道。每個 ML 輸入通道都會根據其在`CreateTrainedModel`請求中`channel_name`提供的對應進行映射。 ``` parser = argparse.ArgumentParser()# Data, model, and output directories parser.add_argument('--model_dir', type=str, default=os.environ.get('SM_MODEL_DIR', "/opt/ml/model")) parser.add_argument('--output_dir', type=str, default=os.environ.get('SM_OUTPUT_DIR', "/opt/ml/output/data")) parser.add_argument('--train_dir', type=str, default=os.environ.get('SM_CHANNEL_TRAIN', "/opt/ml/input/data/train")) parser.add_argument('--train_file_format', type=str, default=os.environ.get('FILE_FORMAT', "csv")) ``` + 確保您能夠根據模型程式碼中使用的協作器結構描述產生合成或測試資料集。 + 在建立模型演算法與協同合作的 AWS Clean Rooms 關聯 AWS 帳戶 之前，請確定您可以自行執行 SageMaker AI 訓練任務。 下列程式碼包含與本機測試、SageMaker AI Training 環境測試和 Clean Rooms ML 相容的範例 Docker 檔案 ``` FROM 763104351884.dkr.ecr.us-west-2.amazonaws.com/pytorch-training:2.3.0-cpu-py311-ubuntu20.04-sagemaker MAINTAINER $author_name ENV PYTHONDONTWRITEBYTECODE=1 \ PYTHONUNBUFFERED=1 \ LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib" ENV PATH="/opt/ml/code:${PATH}" # this environment variable is used by the SageMaker PyTorch container to determine our user code directory ENV SAGEMAKER_SUBMIT_DIRECTORY /opt/ml/code # copy the training script inside the container COPY train.py /opt/ml/code/train.py # define train.py as the script entry point ENV SAGEMAKER_PROGRAM train.py ENTRYPOINT ["python", "/opt/ml/code/train.py"] ``` + 為了最佳監控容器故障，基於故障原因，我們建議您匯出日誌和偵錯。在`GetTrainedModel`回應中，Clean Rooms ML 會在 下傳回此檔案的前 1024 個字元`StatusDetails`。 + 完成任何模型變更，並準備好在 SageMaker AI 環境中進行測試後，請依提供的順序執行下列命令。 ``` export ACCOUNT_ID=xxx export REPO_NAME=xxx export REPO_TAG=xxx export REGION=xxx docker build -t $ACCOUNT_ID.dkr.ecr.us-west-2.amazonaws.com/$REPO_NAME:$REPO_TAG # Sign into AWS $ACCOUNT_ID/ Run aws configure # Check the account and make sure it is the correct role/credentials aws sts get-caller-identity aws ecr create-repository --repository-name $REPO_NAME --region $REGION aws ecr describe-repositories --repository-name $REPO_NAME --region $REGION # Authenticate Doker aws ecr get-login-password --region $REGION | docker login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com # Push To ECR Images docker push $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com$REPO_NAME:$REPO_TAG # Create Sagemaker Training job # Configure the training_job.json with # 1. TrainingImage # 2. Input DataConfig # 3. Output DataConfig aws sagemaker create-training-job --cli-input-json file://training_job.json --region $REGION ``` SageMaker AI 任務完成且您對模型演算法感到滿意後，您就可以向 AWS Clean Rooms ML 註冊 Amazon ECR 登錄檔。使用 `CreateConfiguredModelAlgorithm`動作來註冊模型演算法，並使用 `CreateConfiguredModelAlgorithmAssociation` 將其與協同合作建立關聯。 # 推論容器的模型撰寫準則 本節詳細說明模型提供者在為 Clean Rooms ML 建立推論演算法時應遵循的準則。 + 使用適當的 SageMaker AI 推論支援的容器基礎映像，如 [SageMaker AI 開發人員指南](https://docs.aws.amazon.com/sagemaker/latest/dg-ecr-paths/sagemaker-algo-docker-registry-paths.html)中所述。下列程式碼可讓您從公有 SageMaker AI 端點提取支援的容器基礎映像。 ``` ecr_registry_endpoint='763104351884.dkr.ecr.$REGION.amazonaws.com' base_image='pytorch-inference:2.3.0-cpu-py311-ubuntu20.04-sagemaker' aws ecr get-login-password --region $REGION | docker login --username AWS --password-stdin $ecr_registry_endpoint docker pull $ecr_registry_endpoint/$base_image ``` + 在本機編寫模型時，請確保下列事項，以便您可以在本機、開發執行個體、 中的 SageMaker AI Batch Transform AWS 帳戶和 Clean Rooms ML 上測試模型。 + Clean Rooms ML 透過 Docker 容器中的 `/opt/ml/model`目錄，讓您的推論模型成品可供推論程式碼使用。 + Clean Rooms ML 會依行分割輸入、使用`MultiRecord`批次策略，並在每個轉換的記錄結尾新增換行字元。 + 確保您能夠根據模型程式碼中使用的協作者結構描述產生合成或測試推論資料集。 + 在建立模型演算法與協同合作的 AWS Clean Rooms 關聯 AWS 帳戶 之前，請確定您可以自行執行 SageMaker AI 批次轉換任務。 下列程式碼包含與本機測試、SageMaker AI 轉換環境測試和 Clean Rooms ML 相容的範例 Docker 檔案 ``` FROM 763104351884.dkr.ecr.us-east-1.amazonaws.com/pytorch-inference:1.12.1-cpu-py38-ubuntu20.04-sagemaker ENV PYTHONUNBUFFERED=1 COPY serve.py /opt/ml/code/serve.py COPY inference_handler.py /opt/ml/code/inference_handler.py COPY handler_service.py /opt/ml/code/handler_service.py COPY model.py /opt/ml/code/model.py RUN chmod +x /opt/ml/code/serve.py ENTRYPOINT ["/opt/ml/code/serve.py"] ``` + 完成任何模型變更，並準備好在 SageMaker AI 環境中進行測試後，請依提供的順序執行下列命令。 ``` export ACCOUNT_ID=xxx export REPO_NAME=xxx export REPO_TAG=xxx export REGION=xxx docker build -t $ACCOUNT_ID.dkr.ecr.us-west-2.amazonaws.com/$REPO_NAME:$REPO_TAG # Sign into AWS $ACCOUNT_ID/ Run aws configure # Check the account and make sure it is the correct role/credentials aws sts get-caller-identity aws ecr create-repository --repository-name $REPO_NAME --region $REGION aws ecr describe-repositories --repository-name $REPO_NAME --region $REGION # Authenticate Docker aws ecr get-login-password --region $REGION | docker login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com # Push To ECR Repository docker push $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com$REPO_NAME:$REPO_TAG # Create Sagemaker Model # Configure the create_model.json with # 1. Primary container - # a. ModelDataUrl - S3 Uri of the model.tar from your training job aws sagemaker create-model --cli-input-json file://create_model.json --region $REGION # Create Sagemaker Transform Job # Configure the transform_job.json with # 1. Model created in the step above # 2. MultiRecord batch strategy # 3. Line SplitType for TransformInput # 4. AssembleWith Line for TransformOutput aws sagemaker create-transform-job --cli-input-json file://transform_job.json --region $REGION ``` 在 SageMaker AI 任務完成且您對批次轉換感到滿意之後，您就可以向 AWS Clean Rooms ML 註冊 Amazon ECR 登錄檔。使用 `CreateConfiguredModelAlgorithm`動作來註冊模型演算法，並使用 `CreateConfiguredModelAlgorithmAssociation` 將其與協同合作建立關聯。 # 接收模型日誌和指標 若要從自訂模型訓練或推論接收日誌和指標，成員必須使用提供必要 CloudWatch 許可的有效角色[來建立 ML 組態](https://docs.aws.amazon.com/clean-rooms/latest/userguide/create-custom-ml-collaboration.html) （請參閱[建立自訂 ML 模型的服務角色 - ML 組態](https://docs.aws.amazon.com/clean-rooms/latest/userguide/ml-roles.html#ml-roles-custom-configure))。 **系統指標** 訓練和推論的系統指標，例如 CPU 和記憶體使用率，都會發佈給與有效 ML 組態協作的所有成員。這些指標可以隨著任務進度，分別透過 `/aws/cleanroomsml/TrainedModels`或 `/aws/cleanroomsml/TrainedModelInferenceJobs` 命名空間中的 CloudWatch 指標進行檢視。 **模型日誌** 每個設定模型演算法的隱私權組態政策都會提供對模型日誌的存取。模型作者在將設定的模型演算法 （透過主控台或 `CreateConfiguredModelAlgorithmAssociation` API) 與協同合作建立關聯時，會設定隱私權組態政策。設定隱私權組態政策可控制哪些成員可以接收模型日誌。 此外，模型作者可以在隱私權組態政策中設定篩選模式，以篩選日誌事件。模型容器傳送至 `stdout`或 `stderr`以及符合篩選條件模式 （如果設定） 的所有日誌都會傳送至 Amazon CloudWatch Logs。模型日誌`/aws/cleanroomsml/TrainedModelInferenceJobs`分別在 CloudWatch 日誌群組`/aws/cleanroomsml/TrainedModels`或 中提供。 **自訂定義的指標** 當您設定模型演算法 （透過主控台或 `CreateConfiguredModelAlgorithm` API) 時，模型作者可以提供特定的指標名稱和 regex 陳述式，以便在輸出日誌中搜尋。當任務透過 `/aws/cleanroomsml/TrainedModels` 命名空間中的 CloudWatch Metrics 進行時，可以檢視這些項目。關聯設定的模型演算法時，模型作者可以在指標隱私權組態中設定選用的雜訊層級，以避免輸出原始資料，同時仍提供自訂指標趨勢的可見性。如果設定雜訊層級，則指標會在任務結束時發佈，而不是即時發佈。 # 的加密運算 Clean Rooms Clean Rooms (C3R) 密碼編譯運算是 中的功能 AWS Clean Rooms ，除了[分析規則](analysis-rules.md)之外，還可以使用此功能。透過 C3R，組織可以將敏感資料結合在一起，從資料分析中衍生新洞見，同時以密碼編譯方式限制流程中的任一方可以學習的內容。C3R 可供想要與其敏感資料協作，但只需要在雲端中使用加密資料的兩個或多個方使用。 C3R 加密用戶端是一種用戶端加密工具，可用來[加密](glossary.md#glossary-encryption)資料以搭配 使用 AWS Clean Rooms。當您使用 C3R 加密用戶端時，資料在 AWS Clean Rooms 協同合作中使用時仍會受到密碼編譯保護。如同定期 AWS Clean Rooms 協同合作，輸入資料是關聯式資料庫資料表，而運算會以 SQL 查詢表示。不過，C3R 僅支援加密資料上有限的 SQL 查詢子集。 具體而言，C3R 支援密碼編譯受保護資料的 SQL JOIN和 SELECT陳述式。輸入資料表中的每個資料欄只能用於下列其中一個 SQL 陳述式類型： + 受密碼編譯保護以用於 JOIN 陳述式的資料欄稱為 資料**fingerprint欄**。 + 受密碼編譯保護以用於 SELECT 陳述式的資料欄稱為 資料**sealed欄**。 + 未受密碼編譯保護的資料欄可用於 JOIN或 SELECT陳述式，稱為資料**cleartext欄**。 在某些情況下，資料fingerprint欄支援 GROUP BY陳述式。如需詳細資訊，請參閱[Fingerprint 資料欄](crypto-computing-column-types.md#fingerprint-columns)。目前，C3R 不支援在加密資料上使用其他 SQL 建構，例如子WHERE句或彙總函數，例如 SUM和 AVERAGE，即使相關分析規則允許這些函數。 C3R 旨在保護資料表個別儲存格中的資料。使用 C3R 的預設組態，客戶透過協同合作提供給第三方的基礎資料會在 內使用內容時保持加密 AWS Clean Rooms。C3R 對所有sealed資料欄使用業界標準的 AES-GCM 加密，以及稱為雜湊型訊息驗證碼 (HMAC) 的業界標準虛擬隨機函數來保護資料fingerprint欄。 雖然 C3R 會加密資料表中的資料，但仍可能推論下列資訊： + 資料表本身的相關資訊，包括資料表中的資料欄數、資料欄名稱和資料列數。 + 如同大多數標準形式的加密，C3R 不會嘗試隱藏加密值的長度。C3R 確實提供填補加密值的功能，以隱藏純文字的確切長度。不過，每個資料欄中純文字長度的上限仍然可以向另一方公開。 + 記錄層級資訊，例如將特定資料列新增至加密 C3R 資料表的時間。 如需 C3R 的詳細資訊，請參閱下列主題。 **Topics** + [針對 使用密碼編譯運算時的考量事項 Clean Rooms](crypto-computing-considerations.md) + [適用於 的密碼編譯運算中支援的檔案和資料類型 Clean Rooms](crypto-computing-file-types.md) + [的密碼編譯運算中的資料欄名稱 Clean Rooms](crypto-computing-column-names.md) + [適用於 的密碼編譯運算中的資料欄類型 Clean Rooms](crypto-computing-column-types.md) + [密碼編譯運算參數](crypto-computing-parameters.md) + [適用於 的密碼編譯運算中的選用旗標 Clean Rooms](crypto-computing-optional-flags.md) + [適用於 的加密運算查詢 Clean Rooms](crypto-computing-queries.md) + [C3R 加密用戶端的準則](crypto-computing-guidelines.md) # 針對 使用密碼編譯運算時的考量事項 Clean Rooms 適用於 Clean Rooms(C3R) 的加密運算力力求將資料保護最大化。不過，某些使用案例可能受益於較低層級的資料保護，以換取額外的功能。您可以從最安全的組態修改 C3R，藉此做出這些特定的權衡。身為客戶，您應該了解這些權衡，並判斷它們是否適合您的使用案例。要考慮的權衡包括下列項目： **Topics** + [允許資料表中的混合cleartext和加密資料](#allow-mixed-plaintext-and-encrypted-data) + [允許資料fingerprint欄中的重複值](#allow-repeated-values) + [解除資料fingerprint欄命名方式的限制](#loose-restrictions-on-join-column-names) + [決定NULL值的呈現方式](#determine-null-values) 如需如何設定這些案例參數的詳細資訊，請參閱 [密碼編譯運算參數](crypto-computing-parameters.md)。 ## 允許資料表中的混合cleartext和加密資料 所有資料都經過用戶端加密，可提供最大的資料保護。不過，這會限制特定類型的查詢 （例如SUM彙總函數）。允許cleartext資料的風險是，任何有權存取加密資料表的人都可以推斷一些有關加密值的資訊。這可以透過對 cleartext和相關聯的資料執行統計分析來完成。 例如，假設您有 `City`和 的資料欄`State`。資料`City`欄為 cleartext，且資料`State`欄已加密。當您`Chicago`在 `City`欄中看到 值時，這可協助您以高機率判斷 `State`為 `Illinois`。相反地，如果一個資料欄是 `City`，另一個資料欄是 `EmailAddress`，則 cleartext `City` 不太可能顯示有關加密 的任何內容`EmailAddress`。 如需此案例參數的詳細資訊，請參閱 [允許cleartext資料欄參數](crypto-computing-parameters.md#parameter-allowcleartext)。 ## 允許資料fingerprint欄中的重複值 為了最安全的方法，我們假設任何fingerprint資料欄只包含一個變數的執行個體。fingerprint 欄中不可重複任何項目。C3R 加密用戶端會將這些cleartext值映射到與隨機值不區分的唯一值。因此，無法cleartext從這些隨機值推斷有關 的資訊。 資料fingerprint欄中重複值的風險是重複值將導致重複的隨機顯示值。因此，任何有權存取加密資料表的人，理論上都可以對可能顯示cleartext值資訊的fingerprint欄執行統計分析。 同樣地，假設資料fingerprint欄是 `State`，且資料表的每一列都對應至美國家庭。透過執行頻率分析，可以推斷哪個狀態為 `California` ，以及哪個狀態`Wyoming`為高機率。這種推論是可能的，因為 `California` 的居民比 多`Wyoming`。相反地，假設資料fingerprint欄位於家庭識別符上，而且每個家庭在數百萬個項目的資料庫中出現 1 到 4 次。頻率分析不太可能顯示任何有用的資訊。 如需此案例參數的詳細資訊，請參閱 [允許重複參數](crypto-computing-parameters.md#parameter-allowduplicates)。 ## 解除資料fingerprint欄命名方式的限制 根據預設，我們假設當兩個資料表使用加密資料fingerprint欄聯結時，這些資料欄在每個資料表中具有相同的名稱。此結果的技術原因是，根據預設，我們會衍生不同的密碼編譯金鑰來加密每個fingerprint資料欄。該金鑰衍生自協同合作的共用私密金鑰和資料欄名稱的組合。如果我們嘗試使用不同的資料欄名稱聯結兩個資料欄，我們會衍生不同的金鑰，而且無法計算有效的聯結。 若要解決此問題，您可以關閉從每個資料欄名稱衍生索引鍵的功能。然後，C3R 加密用戶端對所有fingerprint資料欄使用單一衍生金鑰。風險是可以進行另一種可能顯示資訊的頻率分析。 讓我們再次使用 `City`和 `State` 範例。如果我們為每個fingerprint資料欄衍生相同的隨機值 （透過不合併資料欄名稱）。 在 `City`和 資料`State`欄中`New York`具有相同的隨機值。紐約是美國少數幾個城市之一，其`City`名稱與`State`名稱相同。相反地，如果您的資料集在每個資料欄中具有完全不同的值，則不會洩漏任何資訊。 如需此案例參數的詳細資訊，請參閱 [允許具有不同名稱參數JOIN的資料欄](crypto-computing-parameters.md#parameter-allowjoin)。 ## 決定NULL值的呈現方式 您可用的選項是是否像任何其他NULL值一樣，以密碼編譯方式處理 （加密和 HMAC) 值。如果您不像任何其他NULL值一樣處理值，可能會顯示資訊。 例如，假設 NULL 的 `Middle Name`欄中的 cleartext表示沒有中間名的人員。如果您不加密這些值，則會洩漏加密資料表中哪些資料列用於沒有中間名的人員。該資訊可能是某些人口中某些人的識別訊號。但是，如果您以密碼編譯方式處理NULL值，某些 SQL 查詢的運作方式會有所不同。例如，GROUP BY子句不會將fingerprint資料欄中fingerprintNULL的值分組在一起。 如需此案例參數的詳細資訊，請參閱 [保留NULL值參數](crypto-computing-parameters.md#parameter-preservenulls)。 # 適用於 的密碼編譯運算中支援的檔案和資料類型 Clean Rooms C3R 加密用戶端會辨識下列檔案類型： + CSV 檔案 + Parquet 檔案 您可以使用 C3R 加密用戶端中的 `--fileFormat`旗標明確指定檔案格式。明確指定時，檔案格式不會由副檔名決定。 **Topics** + [CSV 檔案](#csv-file-type) + [Parquet 檔案](#parquet-file-type) + [加密非字串值](#encrypt-non-string-values) ## CSV 檔案 假設副檔名為 .csv 的檔案為 CSV 格式，並包含 UTF-8 編碼的文字。C3R 加密用戶端會將所有值視為字串。 ### .csv 檔案中支援的屬性 C3R 加密用戶端需要 .csv 檔案具有下列屬性： + 可能或可能不包含可唯一命名每個資料欄的初始標頭列。 + 逗號分隔。（目前不支援自訂分隔符號。) + UTF-8 編碼的文字。 #### 從 .csv 項目裁剪的空格 前置和後置空格都會從 .csv 項目修剪。 #### .csv 檔案的自訂NULL編碼 .csv 檔案可以使用自訂NULL編碼。 使用 C3R 加密用戶端，您可以使用 `--csvInputNULLValue=`旗標為輸入資料中的NULL項目指定自訂編碼。C3R 加密用戶端可以使用 `--csvOutputNULLValue=`旗標，在產生的輸出檔案中針對 NULL 項目使用自訂編碼。 **注意** NULL 項目被視為*缺少*內容，特別是在 SQL 資料表等更豐富的表格格式環境中。雖然 .csv 基於歷史原因未明確支援此特性描述，但一般慣例是將僅包含空格的空白項目視為 NULL。因此，這是 C3R 加密用戶端的預設行為，可以視需要自訂。 ### C3R 如何解譯 .csv 項目 下表提供 .csv 項目如何根據為 `--csvInputNULLValue=`和 `--csvOutputNULLValue=`旗標提供的值 (cleartext如果有的話） 進行封送 ( 到 cleartext 以獲得明確性） 的範例。在 C3R 解譯任何值的意義之前，會修剪引號外部的前後空格。 | `` | `` | 輸入項目 | 輸出項目 | | --- |--- |--- |--- | | None | None | 、AnyProduct、 | 、AnyProduct、 | | None | None | 、AnyProduct、 | 、AnyProduct、 | | None | None | 、"AnyProduct"、 | 、AnyProduct、 | | None | None | 、「AnyProduct」、 | 、AnyProduct、 | | None | None | ,, | ,, | | None | None | , , | ,, | | None | None | ,"", | ,, | | None | None | ," ", | ," ", | | None | None | , " " , | ," ", | | 「AnyProduct」 | 「NULL」 | 、AnyProduct、 | 、NULL、 | | 「AnyProduct」 | 「NULL」 | 、AnyProduct、 | 、NULL、 | | 「AnyProduct」 | 「NULL」 | 、"AnyProduct"、 | 、NULL、 | | 「AnyProduct」 | 「NULL」 | 、「AnyProduct」、 | 、NULL、 | | None | 「NULL」 | ,, | 、NULL、 | | None | 「NULL」 | , , | 、NULL、 | | None | 「NULL」 | ,"", | 、NULL、 | | None | 「NULL」 | ," ", | ," ", | | None | 「NULL」 | , " " , | ," ", | | "" | 「NULL」 | ,, | 、NULL、 | | "" | 「NULL」 | , , | 、NULL、 | | "" | 「NULL」 | ,"", | ,"", | | "" | 「NULL」 | ," ", | ," ", | | "" | 「NULL」 | , " " , | ," ", | | "\$1"\$1"" | 「NULL」 | ,, | ,, | | "\$1"\$1"" | 「NULL」 | , , | ,, | | "\$1"\$1"" | 「NULL」 | ,"", | 、NULL、 | | "\$1"\$1"" | 「NULL」 | ," ", | ," ", | | "\$1"\$1"" | 「NULL」 | , " " , | ," ", | ### 不含標頭的 CSV 檔案 來源 .csv 檔案不需要在第一列中具有唯一命名每個資料欄的標頭。不過，沒有標頭列的 .csv 檔案需要位置加密結構描述。位置加密結構描述是必要的，而不是用於具有標頭列和檔案的 .csv Parquet 檔案的一般映射結構描述。 位置加密結構描述會依位置而非名稱指定輸出資料欄。映射的加密結構描述會將來源資料欄名稱映射至目標資料欄名稱。如需詳細資訊，包括這兩種結構描述格式的詳細討論和範例，請參閱 [映射和位置資料表結構描述](create-schema.md#mapped-and-positional-schemas)。 ## Parquet 檔案 假設副.parquet檔名為 的檔案Apache Parquet格式。 ### 支援的Parquet資料類型 C3R 加密用戶端可以處理檔案中Parquet代表 支援之資料類型的任何非複雜 （即基本類型） 資料 AWS Clean Rooms。 不過，只有字串資料欄可用於sealed資料欄。 支援下列 Parquet 資料類型： + `Binary` 具有下列邏輯註釋的基本類型： + 如果`--parquetBinaryAsString`已設定 則無 (`STRING` 資料類型） + `Decimal(scale, precision)` (`DECIMAL` 資料類型） + `String` (`STRING` 資料類型） + `Boolean` 沒有邏輯註釋的基本資料類型 (`BOOLEAN` 資料類型） + `Double` 沒有邏輯註釋的基本資料類型 (`DOUBLE` 資料類型） + `Fixed_Len_Binary_Array` 具有邏輯註釋的基本類型 `Decimal(scale, precision)` (`DECIMAL` 資料類型） + `Float` 沒有邏輯註釋的基本資料類型 (`FLOAT` 資料類型） + `Int32` 具有下列邏輯註釋的基本類型： + 無 (`INT` 資料類型） + `Date` (`DATE` 資料類型） + `Decimal(scale, precision)` (`DECIMAL` 資料類型） + `Int(16, true)` (`SMALLINT` 資料類型） + `Int(32, true)` (`INT` 資料類型） + `Int64` 具有下列邏輯註釋的基本資料類型： + 無 (`BIGINT` 資料類型） + `Decimal(scale, precision)` (`DECIMAL` 資料類型） + `Int(64, true)` (`BIGINT` 資料類型） + `Timestamp(isUTCAdjusted, TimeUnit.MILLIS)` (`TIMESTAMP` 資料類型） + `Timestamp(isUTCAdjusted, TimeUnit.MICROS)` (`TIMESTAMP` 資料類型） + `Timestamp(isUTCAdjusted, TimeUnit.NANOS)` (`TIMESTAMP` 資料類型） ## 加密非字串值 目前，sealed欄僅支援字串值。 對於 .csv 檔案，C3R 加密用戶端會將所有值視為 UTF-8 編碼文字，並且在加密之前不會嘗試以不同的方式解譯這些值。 對於指紋資料欄，類型會分組為等效類別。等效類別是一組資料類型，可透過代表性資料類型明確比較相等性。 對等類別允許將相同的指紋指派給相同的語意值，無論原始表示法為何。不過，兩個等效類別中的相同值不會產生相同的指紋資料欄。 例如，無論該`INTEGRAL`值原本是 `SMALLINT`、 或 `INT`，`42`都會指派相同的指紋`BIGINT`。此外，該`INTEGRAL`值永遠`0`不會符合該`BOOLEAN`值 `FALSE`（以值 表示`0`)。 指紋資料欄支援下列等效類別和對應的 AWS Clean Rooms 資料類型： | 對等類別 | 支援的 AWS Clean Rooms 資料類型 | | --- | --- | | BOOLEAN | BOOLEAN | | DATE | DATE | | INTEGRAL | BIGINT, INT, SMALLINT | | STRING | CHAR, STRING, VARCHAR | # 的密碼編譯運算中的資料欄名稱 Clean Rooms 根據預設，資料欄的名稱在 的加密運算中很重要Clean Rooms。 如果**允許具有不同名稱參數的資料JOIN欄**的值為 **false**，則會在資料欄加密期間使用fingerprint資料欄名稱。因此，根據預設，協作者必須事先協調，並為將在查詢中使用JOIN陳述式的資料使用相同的目標資料欄名稱。根據預設，JOIN以不同名稱加密的 資料欄無法在任何值JOIN上成功。 如果**允許具有不同名稱參數的資料JOIN欄**的值為 **true**，則資料欄之間的JOIN陳述式會加密為資料fingerprint欄成功。使用此參數加密資料可能會允許對cleartext值進行一些推論。例如，如果資料列在`City`資料欄和`State`資料欄中具有相同的雜湊型訊息驗證碼 (HMAC) 值，則該值可能是 `New York`。 ## 資料欄標頭名稱的標準化 資料欄標頭名稱由 C3R 加密用戶端標準化。任何開頭和結尾的空格都會移除，且轉換輸出的資料欄名稱會變成小寫。 標準化會在所有其他運算、計算或可能受到資料欄名稱影響的其他操作之前套用。發出的輸出檔案只包含標準化名稱。 # 適用於 的密碼編譯運算中的資料欄類型 Clean Rooms 本主題提供 密碼編譯運算中資料欄類型的相關資訊Clean Rooms。 **Topics** + [Fingerprint 資料欄](#fingerprint-columns) + [已密封的資料欄](#sealed-columns) + [Cleartext 資料欄](#cleartext-columns) ## Fingerprint 資料欄 *Fingerprint 資料欄*是以密碼編譯方式保護的資料欄，可用於 JOIN陳述式。 資料fingerprint欄的資料無法解密。只有來自密封資料欄的資料才能解密。 Fingerprint 欄只能用於下列 SQL 子句和函數： + JOIN (INNER, OUTER, LEFT, RIGHT, or FULL) 針對其他fingerprint資料欄： + 如果 `allowJoinsOnColumnsWithDifferentNames` 參數的值設定為 `false`，則 的兩個fingerprint資料欄JOIN也必須具有相同的名稱。 + `SELECT COUNT()` + `SELECT COUNT(DISTINCT )` + `GROUP BY` （只有在協同合作已將 `preserveNulls` 參數的值設定為 時，才能使用 `true`。) 違反這些限制條件的查詢可能會導致不正確的結果。 ## 已密封的資料欄 *密封資料欄*是以密碼編譯方式保護的資料欄，可用於 SELECT陳述式。 密封資料欄只能用於下列 SQL 子句和函數： + `SELECT` + `SELECT ... AS` + `SELECT COUNT()` **注意** 不支援 `SELECT COUNT(DISTINCT )`。 違反這些限制條件的查詢可能會導致不正確的結果。 ### 在加密之前填補資料sealed欄的資料 當您指定資料欄應為資料sealed欄時，C3R 會要求您選擇哪種*填補*。在加密之前填補資料是選用的。不使用填補 ( 的鍵盤類型`none`)，加密資料的長度表示 的大小cleartext。在某些情況下， 的大小cleartext可能會公開純文字。使用填補 （鍵盤類型為 `fixed`或 `max`) 時，所有值會先填補至通用大小，然後加密。使用填補時，加密資料的長度不會提供有關原始cleartext長度的資訊，除了在大小上加上上限。 如果您想要填補資料欄，且已知該資料欄中的資料位元組長度上限，請使用`fixed`填補。使用至少與該資料欄中最長`length`值的位元組長度相同的值。 **注意** 如果值超過提供的 ，則發生錯誤且加密失敗`length`。 如果您想要填補資料欄，而且該資料欄中的資料位元組長度上限不明，請使用`max`填補。此填補模式會將所有資料填入最長值加上額外`length`位元組的長度。 **注意** 您可能想要批次加密資料，或定期使用新資料更新資料表。請注意，`max`填補會將項目填補至指定批次中最長純文字項目的長度 `length` （加位元組）。這表示加密文字長度可能因批次而異。因此，如果您知道資料欄的最大位元組長度，則應該使用 `fixed`而非 `max`。 ## Cleartext 資料欄 *Cleartext 資料欄*是未受密碼編譯保護的資料欄，可用於 JOIN或 SELECT陳述式。 Cleartext 資料欄可用於 SQL 查詢的任何部分。 # 密碼編譯運算參數 密碼編譯運算參數可在建立協作時使用 Cryptographic Computing for Clean Rooms(C3R) 進行協作。 [建立協同合作](create-collaboration.md)您可以使用 AWS Clean Rooms 主控台或 `CreateCollaboration` API 操作建立協同合作。在 主控台中，您可以在開啟**支援****密碼編譯運算選項之後，在密碼編譯運算參數**中設定參數的值。如需詳細資訊，請參閱下列主題。 **Topics** + [允許cleartext資料欄參數](#parameter-allowcleartext) + [允許重複參數](#parameter-allowduplicates) + [允許具有不同名稱參數JOIN的資料欄](#parameter-allowjoin) + [保留NULL值參數](#parameter-preservenulls) ## 允許cleartext資料欄參數 在 主控台中，您可以在[建立協同合作](create-collaboration.md)時設定**允許cleartext資料欄**參數，以指定具有加密cleartext資料的資料表中是否允許資料。 下表說明**允許cleartext資料欄**參數的值。 | 參數值 | Description | | --- | --- | | 否 | Cleartext 加密資料表中不允許 欄。所有資料都會受到密碼編譯保護。 | | 是 | Cleartext 加密資料表中允許 欄。 Cleartext 資料欄不受密碼編譯保護，並會包含為 cleartext。您應該記下資料列cleartext的資料在資料表中可能顯示的其他資料。 若要在特定資料欄AVG上執行 SUM或 ，資料欄必須位於 中cleartext。 | 使用 `CreateCollaboration` API 操作，對於 `dataEncryptionMetadata` 參數，您可以將 的值設定為 `allowCleartext``true`或 `false`。如需 API 操作的詳細資訊，請參閱 [AWS Clean Rooms API 參考](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html)。 Cleartext 資料欄對應至資料表特定結構描述cleartext中分類為 的資料欄。這些資料欄中的資料不會加密，而且可以以任何方式使用。如果資料不敏感和/或需要比加密Cleartext資料欄或fingerprint資料欄允許的更多彈性，資料sealed欄可能很有用。 ## 允許重複參數 在 主控台中，您可以在[建立協同合作](create-collaboration.md)時設定**允許重複**參數，以指定為JOIN查詢加密的資料欄是否可以包含重複的非NULL值。 **重要** **允許重複**、[**允許具有不同名稱的資料JOIN欄**](#parameter-allowjoin)，以及[**保留NULL值**](#parameter-preservenulls)參數具有個別但相關的效果。 下表說明 **Allow duplicates** 參數的值。 | 參數值 | Description | | --- | --- | | 否 | 資料fingerprint欄中不允許重複的值。單一資料fingerprint欄中的所有值都必須是唯一的。 | | 是 | 資料fingerprint欄中允許重複的值。 如果您需要使用重複值聯結資料欄，請將此值設定為**是**。當設定為**是**時，C3R 資料表或結果中的資料fingerprint欄中出現的頻率模式可能表示有關cleartext資料結構的一些額外資訊。 | 使用 `CreateCollaboration` API 操作，對於 `dataEncryptionMetadata` 參數，您可以將 的值設定為 `allowDuplicates``true`或 `false`。如需 API 操作的詳細資訊，請參閱 [AWS Clean Rooms API 參考](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html)。 根據預設，如果必須在JOIN查詢中使用加密的資料，C3R 加密用戶端會要求這些資料欄沒有重複的值。這項要求是為了提高資料保護。此行為有助於確保資料中重複的模式無法觀察。不過，如果您想要在JOIN查詢中使用加密的資料，並且不擔心重複值，則**允許重複**參數可以停用此保守檢查。 ## 允許具有不同名稱參數JOIN的資料欄 在 主控台中，您可以在[建立協同](create-collaboration.md)合作時設定**允許具有不同名稱參數JOIN的資料欄**，以指定是否支援不同名稱的資料欄之間的JOIN陳述式。 如需詳細資訊，請參閱[資料欄標頭名稱的標準化](crypto-computing-column-names.md#column-header-names-normalization) 下表說明**使用不同名稱參數JOIN允許資料欄**的值。 | 參數值 | Description | | --- | --- | | 否 | 不支援聯結具有不同名稱的資料fingerprint欄。 JOIN陳述式只會在具有相同名稱的資料欄上提供準確的結果。 **無**值可提高資訊安全，但要求協同合作參與者先前同意資料欄名稱。如果兩個資料欄在加密為fingerprint資料欄時具有不同的名稱，且**允許具有不同名稱JOIN的資料欄**設定為**否**，則這些資料欄上的JOIN陳述式不會產生任何結果。這是因為加密後不會在它們之間共用任何值。 | | 是 | 支援聯結具有不同名稱的資料fingerprint欄。為了提高靈活性，使用者可以將此值設定為**是**，這允許資料欄上的JOIN陳述式，無論其資料欄名稱為何。 如果設定為**是**，C3R 加密用戶端在保護資料欄時不會考慮資料fingerprint欄名稱。因此，可在 C3R 資料表中觀察不同fingerprint資料欄之間的共同值。 例如，如果資料列在`City`資料欄和`State`資料欄中具有相同的加密JOIN值，則推斷該值為 可能是合理的`New York`。 | 使用 `CreateCollaboration` API 操作，對於 `dataEncryptionMetadata` 參數，您可以將 的值設定為 `allowJoinsOnColumnsWithDifferentNames``true`或 `false`。如需 API 操作的詳細資訊，請參閱 [AWS Clean Rooms API 參考](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html)。 根據預設，資料fingerprint欄加密會受到該資料欄`targetHeader`的 影響，在 中設定[步驟 4：產生表格式檔案的加密結構描述](gen-encryption-schema-csv.md)。因此，相同的cleartext值在加密的每個不同資料fingerprint欄中都有不同的加密表示法。 在某些情況下，此參數有助於防止cleartext值推論。例如，在資料fingerprint欄中看到相同的加密值`City`，並`State`可能用於合理推斷該值為 `New York`。不過，此參數的使用需要事先進行額外的協調，因此要加入查詢的所有資料欄都有共用的名稱。 您可以使用**允許具有不同名稱參數JOIN的資料欄**來鬆散此限制。當參數值設定為 時`Yes`，它允許將 加密的任何資料欄一起使用JOIN，無論名稱為何。 ## 保留NULL值參數 在 主控台中，您可以在[建立協同](create-collaboration.md)合作時設定**保留NULL值**參數，以表示該資料欄不存在任何值。 下表說明**保留值參數NULL**的值。 | 參數值 | Description | | --- | --- | | 否 | NULL 值不會保留。 NULL 值不會在加密資料表NULL中顯示為 。 NULL值會在 C3R 資料表中顯示為唯一的隨機值。 | | 是 | NULL 值會保留。 NULL 值會在加密的資料表NULL中顯示為 。如果您需要NULL值的 SQL 語意，您可以將此值設定為是。因此，無論資料欄是否已加密，無論允許重複項目的參數設定為何，NULL項目都會在 C3R 資料表NULL中顯示為 。 | 使用 `CreateCollaboration` API 操作，對於 `dataEncryptionMetadata` 參數，您可以將 的值設定為 `preserveNulls``true`或 `false`。如需 API 操作的詳細資訊，請參閱 [AWS Clean Rooms API 參考](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html)。 協同合作的**保留NULL值**參數設定為**否**時： 1. NULL `cleartext`資料欄中的項目保持不變。 1. NULL 加密資料`fingerprint`欄中的項目會加密為隨機值，以隱藏其內容。在具有資料欄中NULL項目的加密cleartext資料欄上聯結不會產生任何項目的任何相符NULL項目。不會進行任何比對，因為它們都會收到自己的唯一隨機內容。 1. NULL 加密`sealed`欄中的項目會加密。 當**保留NULL值**參數的值針對協同合作設為**是**時，NULL無論資料欄是否加密，所有資料欄NULL的項目都會保持為 。 **保留NULL值**參數在資料擴充等案例中非常有用，其中您想要分享的資訊不足，以 表示NULL。如果您在想要 fingerprint或 的欄中有NULL值，**則保留NULL值**參數在 JOIN或 HMAC 格式中也很有用GROUP BY。 如果**允許重複**和**保留NULL值**參數的值設定為**否**，則fingerprint欄中有一個以上的NULL項目會產生錯誤並停止加密。如果任一參數的值設定為**是**，則不會發生此類錯誤。 # 適用於 的密碼編譯運算中的選用旗標 Clean Rooms 下列各節說明當您使用 C3R 加密用戶端加密[資料](encrypt-data.md)以進行表格式檔案自訂和測試時，可以設定的選用旗標。 **Topics** + [`--csvInputNULLValue` 標記](#optional-flags-CSVinputNullValue) + [`--csvOutputNULLValue` 標記](#optional-flags-CSVoutputNullValue) + [`--enableStackTraces` 標記](#optional-flags-enablestacktraces) + [`--dryRun` 標記](#optional-flags-dry-run) + [`--tempDir` 標記](#optional-flags-working-dir) ## `--csvInputNULLValue` 標記 當您使用 C3R 加密用戶端[加密資料](encrypt-data.md)時，您可以使用 `--csvInputNULLValue`旗標為輸入資料中的NULL項目指定自訂編碼。 下表摘要說明此旗標的用量和參數。 | Usage | Parameters | | --- | --- | | 選用。使用者可以為輸入資料中的NULL項目指定自訂編碼。 | 輸入 CSV 檔案中NULL值的使用者指定編碼 | NULL 項目是視為缺少內容的項目，特別是在 SQL 資料表等更豐富的表格格式環境中。雖然 .csv 基於歷史原因未明確支援此特性描述，但一般慣例是將僅包含空格的空白項目視為 NULL。因此，這是 C3R 加密用戶端的預設行為，可以視需要自訂。 ## `--csvOutputNULLValue` 標記 當您使用 C3R 加密用戶端[加密資料](encrypt-data.md)時，您可以使用 `--csvOutputNULLValue`旗標為輸出資料中的NULL項目指定自訂編碼。 下表摘要說明此旗標的用量和參數。 | Usage | Parameters | | --- | --- | | 選用。使用者可以在產生的輸出檔案中為NULL項目指定自訂編碼。 | 使用者指定的輸出 CSV 檔案中NULL值編碼 | NULL 項目是視為缺少內容的項目，特別是在 SQL 資料表等更豐富的表格格式環境中。雖然 .csv 基於歷史原因未明確支援此特性描述，但一般慣例是將僅包含空格的空白項目視為 NULL。因此，這是 C3R 加密用戶端的預設行為，可以視需要自訂。 ## `--enableStackTraces` 標記 當您使用 C3R 加密用戶端加密[資料](encrypt-data.md)時，請使用 `--enableStackTraces`旗標提供其他內容資訊，以便在 C3R 遇到錯誤時回報錯誤。 AWS 不會收集錯誤。如果您遇到錯誤，請使用堆疊追蹤自行疑難排解錯誤，或將堆疊追蹤傳送至 支援 以取得協助。 下表摘要說明此旗標的用量和參數。 | Usage | Parameters | | --- | --- | | 選用。用於在 C3R 加密用戶端遇到錯誤時提供錯誤報告的其他內容資訊。 | 無 | ## `--dryRun` 標記 [加密](encrypt-data.md)和[解密](decrypt-data.md) C3R 加密用戶端命令包含選用的`--dryRun`旗標。旗標會取得所有使用者提供的引數，並檢查它們的有效性和一致性。 您可以使用 `--dryRun`旗標來檢查您的結構描述檔案是否有效，並與對應的輸入檔案一致。 下表摘要說明此旗標的用量和參數。 | Usage | Parameters | | --- | --- | | 選用。導致 C3R 加密用戶端剖析參數和檢查檔案，但不會執行加密或解密。 | 無 | ## `--tempDir` 標記 您可能想要使用暫時目錄，因為加密的檔案有時可能會大於未加密的檔案，取決於其設定。資料集也必須在每次協同合作時加密，才能正常運作。 當您使用 C3R [加密資料](encrypt-data.md)時，請使用 `--tempDir`旗標指定在處理輸入時可以建立暫存檔案的位置。 下表摘要說明此旗標的用量和參數。 | Usage | Parameters | | --- | --- | | 使用者可以指定在處理輸入時可以建立暫存檔案的位置。 | 預設為系統暫時目錄。 | # 適用於 的加密運算查詢 Clean Rooms 本主題提供使用 Cryptographic Computing for 加密之資料表撰寫查詢的相關資訊Clean Rooms。 **Topics** + [在 上分支的查詢 NULL](#queries-branch-on-null) + [將一個來源資料欄映射至多個目標資料欄](#queries-mapping) + [對 JOIN和 SELECT查詢使用相同的資料](#queries-using-same-data) ## 在 上分支的查詢 NULL 在NULL陳述式上具有查詢分支表示使用語法，例如 `IF x IS NULL THEN 0 ELSE 1`。 查詢一律可以對cleartext資料欄中的NULL陳述式進行分支。 只有在**保留 NULL 值**參數 (`preserveNulls`) 的值設定為 時，查詢才能對sealed資料欄和資料fingerprint欄中的NULL陳述式進行分支`true`。 違反這些限制條件的查詢可能會導致不正確的結果。 ## 將一個來源資料欄映射至多個目標資料欄 一個來源資料欄可以映射到多個目標資料欄。例如，您可能想要在資料欄SELECT上同時使用 JOIN和 。 如需詳細資訊，請參閱[對 JOIN和 SELECT查詢使用相同的資料](#queries-using-same-data)。 ## 對 JOIN和 SELECT查詢使用相同的資料 如果資料欄中的資料不敏感，它可以出現在cleartext目標資料欄中，這允許將其用於任何用途。 如果資料欄中的資料很敏感，且必須同時用於 JOIN和 SELECT查詢，請將該來源資料欄映射到輸出檔案中的兩個目標資料欄。一個資料欄是以 `type` 做為資料fingerprint欄加密，一個資料欄是以 `type`做為密封資料欄加密。C3R 加密用戶端的互動式結構描述產生會建議 `_fingerprint`和 的標頭尾碼`_sealed`。這些標頭尾碼可以是快速區分此類資料欄的實用慣例。 # C3R 加密用戶端的準則 C3R 加密用戶端是一種工具，可讓組織將敏感資料結合在一起，從資料分析中衍生新的洞見。工具以密碼編譯方式限制任何一方和 AWS 程序中可學習的內容。雖然這至關重要，但以密碼編譯方式保護資料的程序可能會在運算和儲存資源方面增加大量額外負荷。因此，請務必了解使用每個設定的權衡，以及如何最佳化設定，同時仍維持所需的密碼編譯保證。本主題著重於 C3R 加密用戶端和結構描述中不同設定的效能影響。 所有 C3R 加密用戶端加密設定都提供不同的密碼編譯保證。協作層級設定預設為最安全。在建立協同合作時啟用其他功能會降低隱私權保證，允許在加密文字上執行頻率分析等活動。如需如何使用這些設定及其影響的詳細資訊，請參閱 [的加密運算 Clean Rooms](crypto-computing.md)。 **Topics** + [資料欄類型的效能影響](#performance-implications) + [對加密文字大小的非預期增加進行故障診斷](#troubleshooting-ciphertext-size) ## 資料欄類型的效能影響 C3R 使用三種資料欄類型：cleartext、 fingerprint和 sealed。每個資料欄類型都提供不同的密碼編譯保證，並有不同的預期用途。在下列各節中，會討論資料欄類型的效能影響，以及每個設定的效能影響。 **Topics** + [Cleartext 資料欄](#cleartext-columns) + [Fingerprint 資料欄](#guidelines-fingerprint-columns) + [Sealed 資料欄](#guidelines-sealed-columns) ### Cleartext 資料欄 Cleartext 資料欄不會從原始格式變更，也不會以任何方式以密碼編譯方式處理。無法設定此資料欄類型，也不會影響儲存或運算效能。 ### Fingerprint 資料欄 Fingerprint 資料欄旨在用於跨多個資料表聯結資料。為此，產生的加密文字大小必須一律相同。不過，這些資料欄會受到協同合作層級設定的影響。 資料Fingerprint欄可能會對輸出檔案大小產生不同程度的影響，取決於輸入中cleartext包含的 。 **Topics** + [fingerprint 資料欄的基本額外負荷](#fingerprint-columns-base-overhead) + [fingerprint 資料欄的協同作業設定](#fingerprint-columns-collab-settings) + [資料fingerprint欄的範例資料](#collab-set-sample-data) + [對fingerprint資料欄進行故障診斷](#fingerprint-columns-troubleshooting) #### fingerprint 資料欄的基本額外負荷 資料fingerprint欄有基本額外負荷。此額外負荷是固定的，並取代cleartext位元組的大小。 資料fingerprint欄中的資料會透過雜湊型訊息驗證碼 (HMAC) 函數以密碼編譯方式處理，將資料轉換為 32 位元組訊息驗證碼 (MAC)。然後，這些資料會透過 base64 編碼器處理，將大約 33% 新增至位元組大小。它預先附加 8 位元組 C3R 指定，以指定資料所屬的資料欄類型，以及產生它的用戶端版本。最終結果為 52 個位元組。然後，此結果會乘以資料列計數，以取得總基本額外負荷 （如果 `preserveNulls` 設為 true，請使用非`null` 值的總數）。 下圖顯示 如何 * `BASE_OVERHEAD = ` ** `C3R_DESIGNATION + ` ** `(MAC * 1.33)` * ![\[資料fingerprint欄的 52 位元組基本額外負荷。\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/images/base-overhead-fingerprint.PNG) fingerprint 欄中的輸出加密文字一律為 52 個位元組。如果輸入cleartext資料平均超過 52 個位元組 （例如完整的街道地址），這可能會大幅減少儲存空間。如果輸入cleartext資料平均小於 52 個位元組 （例如，客戶年齡），這可能會大幅增加儲存空間。 #### fingerprint 資料欄的協同作業設定 ##### `preserveNulls` 設定 當協同合作層級設定為 `preserveNulls` `false`（預設） 時，每個`null`值都會以唯一的隨機 32 個位元組取代，並如同不是 一樣進行處理`null`。結果是每個`null`值現在都是 52 個位元組。相較於此設定為 `true`且`null`值以 傳遞時，這可能會為包含非常稀疏資料的資料表新增重要的儲存需求`null`。 如果您不需要此設定的隱私權保證，並偏好在資料集內保留`null`值，請在建立協同合作時啟用`preserveNulls`設定。建立協同合作之後，就無法變更`preserveNulls`設定。 #### 資料fingerprint欄的範例資料 以下是資料fingerprint欄的輸入和輸出資料集範例，其中包含要重現的設定。其他協作層級設定，例如 `allowCleartext`和 `allowDuplicates`不會影響結果，`false`而且如果嘗試在本機重現，則可以設定為 `true`或 。 **共用秘密範例**： `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` **協作 ID 範例**： `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111` **allowJoinsOnColumnsWithDifferentNames**：`True`此設定不會影響效能或儲存需求。不過，此設定會在重新產生下表中顯示的值時，使資料欄名稱選擇無關。 **範例 1** | | | | --- |--- | | 輸入 | null | | preserveNulls | TRUE | | Output | null | | 確定性 | Yes | | 輸入位元組 | 0 | | 輸出位元組 | 0 | **範例 2** | | | | --- |--- | | 輸入 | null | | preserveNulls | FALSE | | Output | 01:hmac:3lkFjthvV3IUu6mMvFc1a\$1XAHwgw/ElmOq4p3Yg25kk= | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 52 | **範例 3** | | | | --- |--- | | 輸入 | empty string | | preserveNulls | - | | Output | 01:hmac:oKTgi3Gba\$1eUb3JteSz2EMgXUkF1WgM77UP0Ydw5kPQ= | | 確定性 | Yes | | 輸入位元組 | 0 | | 輸出位元組 | 52 | **範例 4** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:hmac:kU/IqwG7FMmzzshr0B9scomE0UJUEE7j9keTctplGww= | | 確定性 | Yes | | 輸入位元組 | 26 | | 輸出位元組 | 52 | **範例 5** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:hmac:ks3htnQbw2vdhCRFF6JNzW5LMndJaHG57uvE26mBtSs= | | 確定性 | Yes | | 輸入位元組 | 62 | | 輸出位元組 | 52 | #### 對fingerprint資料欄進行故障診斷 **為什麼我fingerprint欄中的加密文字比cleartext進去的 大小大上數倍？** 資料fingerprint欄中的加密文字長度一律為 52 個位元組。如果您的輸入資料很小 （例如，客戶的年齡），其大小將會大幅增加。如果`preserveNulls`設定設為 ，也可能發生這種情況`false`。 **為什麼我fingerprint欄中的加密文字比cleartext進去的 大小小數倍？** 資料fingerprint欄中的加密文字長度一律為 52 個位元組。如果您的輸入資料很大 （例如，客戶的完整街道地址），其大小將明顯減少。 **如何知道是否需要 提供的密碼編譯保證`preserveNulls`？** 不幸的是，答案是它取決於 。至少[密碼編譯運算參數](crypto-computing-parameters.md)應檢閱 ，了解`preserveNulls`設定如何保護您的資料。不過，我們建議您參考組織的資料處理需求，以及適用於個別協同合作的任何合約。 **為什麼我必須產生 base64 的額外負荷？** 若要允許 與 CSV 等表格式檔案格式相容，需要 base64 編碼。雖然某些 檔案格式Parquet可能支援資料的二進位表示法，但協同合作中的所有參與者都以相同的方式代表資料，以確保適當的查詢結果。 ### Sealed 資料欄 Sealed 欄旨在用於在協同合作的成員之間傳輸資料。這些資料欄中的加密文字是非確定性的，並根據資料欄的設定方式對效能和儲存體產生重大影響。這些欄可以個別設定，通常對 C3R 加密用戶端的效能和產生的輸出檔案大小有最大的影響。 **Topics** + [sealed 資料欄的基本額外負荷](#sealed-columns-base-overhead) + [sealed 資料欄的協同作業設定](#sealed-columns-collab-settings) + [結構描述設定sealed欄：填補類型](#sealed-collab-pad-type) + [資料sealed欄的範例資料](#sealed-collab-sample-data) + [對sealed資料欄進行故障診斷](#troubleshooting-sealed-columns) #### sealed 資料欄的基本額外負荷 資料sealed欄有基本額外負荷。此額外負荷是固定的，除了 cleartext和填補 （如果有的話） 位元組的大小之外。 在任何加密之前，資料sealed欄中的資料都會預先附加 1 位元組字元，以指定包含的資料類型。如果選取填補，則資料會填入並附加 2 個位元組，說明填補大小。新增這些位元組之後，會使用 AES-GCM 以密碼編譯方式處理資料，並以 IV(12 個位元組）、 nonce (32 個位元組） 和 Auth Tag(16 個位元組） 存放。然後，這些資料會透過 base64 編碼器處理，將大約 33% 新增至位元組大小。資料會加上 7 位元組 C3R 指定，以指定資料所屬的欄類型，以及用於產生它的用戶端版本。最終基本額外負荷為 91 個位元組。然後，此結果可以乘以資料列計數，以取得總基本額外負荷 （如果 `preserveNulls` 設為 true，請使用非空值總數）。 下圖顯示 如何 * `BASE_OVERHEAD = C3R_DESIGNATION + ((NONCE + IV + DATA_TYPE + PAD_SIZE + AUTH_TAG) * 1.33)` * ![\[資料sealed欄的 91 位元組基本額外負荷。\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/userguide/images/base-overhead-sealed.PNG) #### sealed 資料欄的協同作業設定 ##### `preserveNulls` 設定 當協同合作層級設定為 `preserveNulls` `false`（預設） 時，每個`null`值都是唯一的隨機 32 個位元組，並如同不是 一樣進行處理`null`。結果是每個`null`值現在都是 91 個位元組 （如果有填充則更多）。相較於此設定為 `true`且`null`值以 傳遞時，這可能會為包含非常稀疏資料的資料表新增重要的儲存需求`null`。 如果您不需要此設定的隱私權保證，並偏好在資料集內保留`null`值，請在建立協同合作時啟用`preserveNulls`設定。建立協同合作之後，就無法變更`preserveNulls`設定。 #### 結構描述設定sealed欄：填補類型 **Topics** + [的填補類型 `none`](#pad-type-none) + [的填補類型 `fixed`](#pad-type-fixed) + [的填補類型 `max`](#pad-type-max) ##### 的填補類型 `none` 選取 的護墊類型`none`不會將任何填補新增至 ，cleartext也不會為先前所述的基本額外額外負荷新增額外負荷。沒有填補會產生最節省空間的輸出大小。不過，它不提供與 `fixed`和 `max` 填補類型相同的隱私權保證。這是因為基礎 的大小與加密文字的大小cleartext不同。 ##### 的填補類型 `fixed` 選取 的鍵盤類型`fixed`是一種隱私權保留措施，可隱藏資料欄中包含的資料長度。這是在加密`pad_length`之前，將所有 填補cleartext到提供的 。超過該大小的任何資料都會導致 C3R 加密用戶端失敗。 由於填補會在加密cleartext之前新增至 ，AES-GCM 具有 1 對 1 映射cleartext至加密文字位元組。base64 編碼將增加 33%。填補的額外儲存體額外負荷的計算方式是將 的平均長度cleartext從 的值減去`pad_length`，再乘以 1.33。結果是每筆記錄填補的平均額外負荷。然後，此結果可以乘以資料列數，以取得總填補開銷 （如果 `preserveNulls` 設定為 ，請使用非`null` 值的總數`true`)。 `PADDING_OVERHEAD = (PAD_LENGTH - AVG_CLEARTEXT_LENGTH) * 1.33 * ROW_COUNT` 建議您選取包含資料欄中最大值`pad_length`的最小值。例如，如果最大值是 50 個位元組，則 50 `pad_length`的 就已足夠。大於 的值只會增加額外的儲存體額外負荷。 固定填補不會增加任何顯著的運算額外負荷。 ##### 的填補類型 `max` 選取 的鍵盤類型`max`是一種隱私權保留措施，可隱藏資料欄中包含的資料長度。方法是將所有 填入資料欄中cleartext的最大值，加上其他 ，`pad_length`再加密。一般而言，`max`填補提供與單一資料集`fixed`填補相同的保證，同時允許 不知道欄中的最大cleartext值。不過，`max`填補可能無法提供與`fixed`填補跨更新相同的隱私權保證，因為個別資料集中的最大值可能不同。 建議您在使用`max`填補時選取額外的 `pad_length` 0。此長度會將所有值調整為與資料欄中最大值相同的大小。大於 的值只會增加額外的儲存體額外負荷。 如果指定資料欄已知cleartext最大值，建議您改用 `fixed` 鍵盤類型。使用`fixed`填補可在更新後的資料集之間建立一致性。使用`max`填補會導致每個資料子集填充到子集中最大的值。 #### 資料sealed欄的範例資料 以下是資料sealed欄的輸入和輸出資料集範例，其中包含要重現的設定。`allowCleartext`、 `allowJoinsOnColumnsWithDifferentNames`和 等其他協同合作層級設定`allowDuplicates`不會影響結果，`false`而且如果嘗試在本機重現，可以設定為 `true`或 。雖然這些是要重現的基本設定，但資料sealed欄是非確定性的，且值每次都會變更。目標是顯示 中的位元組與傳出的位元組比較。範例`pad_length`值是刻意選擇的。它們顯示`fixed`填補會產生與建議的最小`pad_length`設定`max`或需要額外填補時相同的值。 **共用秘密範例**： `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` **協作 ID 範例**： `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111` **Topics** + [的填補類型 `none`](#sealed-pad-type-none) + [的填補類型 `fixed`（範例 1)](#sealed-pad-type-fixed) + [的填補類型 `fixed`（範例 2)](#sealed-pad-type-fixed-2) + [的填補類型 `max`（範例 1)](#sealed-pad-type-max) + [的填補類型 `max`（範例 2)](#sealed-pad-type-max-2) ##### 的填補類型 `none` **範例 1** | | | | --- |--- | | 輸入 | null | | preserveNulls | TRUE | | Output | null | | 確定性 | Yes | | 輸入位元組 | 0 | | 輸出位元組 | 0 | **範例 2** | | | | --- |--- | | 輸入 | null | | preserveNulls | FALSE | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSPbNIJfG3iXmu6cbCUrizuV | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 91 | **範例 3** | | | | --- |--- | | 輸入 | empty string | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSPEM6qR8DWC2PB2GMlX41YK | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 91 | **範例 4** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9sGL5VLDQeHzh6DmPpyWNuI= | | 確定性 | No | | 輸入位元組 | 26 | | 輸出位元組 | 127 | **範例 5** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnnohrHIGSX54ua\$11/JfcVjc= | | 確定性 | No | | 輸入位元組 | 62 | | 輸出位元組 | 175 | ##### 的填補類型 `fixed`（範例 1) 在此範例中， `pad_length`是 62，最大輸入是 62 個位元組。 **範例 1** | | | | --- |--- | | 輸入 | null | | preserveNulls | TRUE | | Output | null | | 確定性 | Yes | | 輸入位元組 | 0 | | 輸出位元組 | 0 | **範例 2** | | | | --- |--- | | 輸入 | null | | preserveNulls | FALSE | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoNpATs0GzbnLkor4L\$1/aSuA= | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 175 | **範例 3** | | | | --- |--- | | 輸入 | empty string | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoLB53l07VZpA6OwkuXu29CA= | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 175 | **範例 4** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcutBAcO\$1Mb9tuU2KIHH31AWg= | | 確定性 | No | | 輸入位元組 | 26 | | 輸出位元組 | 175 | **範例 5** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnnohrHIGSX54ua\$11/JfcVjc= | | 確定性 | No | | 輸入位元組 | 62 | | 輸出位元組 | 175 | ##### 的填補類型 `fixed`（範例 2) 在此範例中， `pad_length`是 162，最大輸入是 62 個位元組。 **範例 1** | | | | --- |--- | | 輸入 | null | | preserveNulls | TRUE | | Output | null | | 確定性 | Yes | | 輸入位元組 | 0 | | 輸出位元組 | 0 | **範例 2** | | | | --- |--- | | 輸入 | null | | preserveNulls | FALSE | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv/xAySX\$1xcntotL703aBTBb | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 307 | **範例 3** | | | | --- |--- | | 輸入 | empty string | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv84lVaT9Yd\$16oQx65/\$1gdVT | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 307 | **範例 4** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwtX5Hnl\$1WyfO6ks3QMaRDGSf | | 確定性 | No | | 輸入位元組 | 26 | | 輸出位元組 | 307 | **範例 5** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwjkJXQZOgPdeFX9Yr/8alV5i | | 確定性 | No | | 輸入位元組 | 62 | | 輸出位元組 | 307 | ##### 的填補類型 `max`（範例 1) 在此範例中， `pad_length`為 0，最大輸入為 62 個位元組。 **範例 1** | | | | --- |--- | | 輸入 | null | | preserveNulls | TRUE | | Output | null | | 確定性 | Yes | | 輸入位元組 | 0 | | 輸出位元組 | 0 | **範例 2** | | | | --- |--- | | 輸入 | null | | preserveNulls | FALSE | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoNpATs0GzbnLkor4L\$1/aSuA= | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 175 | **範例 3** | | | | --- |--- | | 輸入 | empty string | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoLB53l07VZpA6OwkuXu29CA= | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 175 | **範例 4** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcutBAcO\$1Mb9tuU2KIHH31AWg= | | 確定性 | No | | 輸入位元組 | 26 | | 輸出位元組 | 175 | **範例 5** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnnohrHIGSX54ua\$11/JfcVjc= | | 確定性 | No | | 輸入位元組 | 62 | | 輸出位元組 | 175 | ##### 的填補類型 `max`（範例 2) 在此範例中， `pad_length`是 100，最大輸入是 62 個位元組。 **範例 1** | | | | --- |--- | | 輸入 | null | | preserveNulls | TRUE | | Output | null | | 確定性 | Yes | | 輸入位元組 | 0 | | 輸出位元組 | 0 | **範例 2** | | | | --- |--- | | 輸入 | null | | preserveNulls | FALSE | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv/xAySX\$1xcntotL703aBTBb | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 307 | **範例 3** | | | | --- |--- | | 輸入 | empty string | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv84lVaT9Yd\$16oQx65/\$1gdVT | | 確定性 | No | | 輸入位元組 | 0 | | 輸出位元組 | 307 | **範例 4** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwtX5Hnl\$1WyfO6ks3QMaRDGSf | | 確定性 | No | | 輸入位元組 | 26 | | 輸出位元組 | 307 | **範例 5** | | | | --- |--- | | 輸入 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwjkJXQZOgPdeFX9Yr/8alV5i | | 確定性 | No | | 輸入位元組 | 62 | | 輸出位元組 | 307 | #### 對sealed資料欄進行故障診斷 ** 為什麼我sealed欄中的加密文字比cleartext進去的 大小大上數倍？** 這取決於幾個因素。其中一個資料Cleartext欄中的加密文字長度一律至少為 91 個位元組。如果您的輸入資料很小 （例如，客戶的年齡），其大小將會大幅增加。其次，如果 `preserveNulls` 設定為 `false`且您的輸入資料包含許多`null`值，則每個`null`值都會轉換為 91 個位元組的加密文字。最後，如果您使用填補，則在加密資料之前，依定義，系統會將位元組新增至cleartext資料。 **資料sealed欄中的大部分資料都很小，我需要使用填補。我是否可以移除大值並分別處理它們以節省空間？** 不建議您移除大型值並分別處理。這樣做會變更 C3R 加密用戶端提供的隱私權保證。作為威脅模型，假設觀察者可以看到兩個加密的資料集。如果觀察者發現一個資料子集的資料欄填充量明顯大於或小於另一個子集，他們可以對每個子集中的資料大小進行推論。例如，假設資料`fullName`欄在一個檔案中填入總計 40 個位元組，並在另一個檔案中填入 800 個位元組。觀察者可以假設一個資料集包含世界最長的名稱 747 位元組）。 **使用填補類型時，是否需要提供額外的`max`填補？** 否。使用`max`填補時，我們建議您將 設定為 0`pad_length`，也稱為*超過*資料欄中最大值的額外填補。 **使用`fixed`填補`pad_length`時，我可以直接挑選大型物件，以避免擔心最大值是否合適？** 是，但大型鍵盤長度效率不佳，使用的儲存空間比所需更多。建議您檢查最大值的大小，並將 `pad_length` 設定為該值。 **如何知道是否需要 提供的密碼編譯保證`preserveNulls`？** 不幸的是，答案是它取決於 。至少[的加密運算 Clean Rooms](crypto-computing.md)應檢閱 `preserveNulls`的設定如何保護您的資料。不過，我們建議您參考組織的資料處理需求，以及適用於個別協同合作的任何合約。 **為什麼我必須產生 base64 的額外負荷？** 若要允許 與 CSV 等表格式檔案格式相容，需要 base64 編碼。雖然某些 檔案格式Parquet可能支援資料的二進位表示法，但協同合作中的所有參與者都以相同的方式代表資料，以確保適當的查詢結果。 ## 對加密文字大小的非預期增加進行故障診斷 假設您已加密資料，而產生的資料大小非常大。下列步驟可協助您識別大小增加的位置，以及您可以採取哪些動作。 ### 識別大小增加的位置 您必須先識別大小增加的位置，才能對加密的資料明顯大於cleartext資料的原因進行故障診斷。 資料Cleartext欄可以放心地被忽略，因為它們保持不變。查看其餘 fingerprint和 sealed欄，然後選擇顯示顯著的項目。 ### 識別大小增加的原因 資料fingerprint欄或資料sealed欄可能會導致大小增加。 **Topics** + [大小增加是否來自資料fingerprint欄？](#size-increase-from-fingerprint) + [大小增加是否來自資料sealed欄？](#size-increase-from-sealed) #### 大小增加是否來自資料fingerprint欄？ 如果對增加儲存體貢獻最大的資料欄是資料fingerprint欄，這可能是因為cleartext資料很小 （例如，客戶年齡）。每個產生的fingerprint加密文字長度為 52 個位元組。遺憾的是，無法逐column-by-column處理此問題。如需詳細資訊，請參閱 [fingerprint 資料欄的基本額外負荷](#fingerprint-columns-base-overhead) 以取得此欄的詳細資訊，包括其如何影響儲存需求。 資料fingerprint欄大小增加的另一個可能原因是協同合作設定 `preserveNulls`。如果停用 `preserveNulls` 的協同合作設定 （預設設定），資料fingerprint欄中的所有`null`值都會變成 52 個位元組的加密文字。在目前的協同合作中，無法對此執行任何操作。此`preserveNulls`設定是在建立協同合作時設定，且所有協同合作者必須使用相同的設定，以確保正確的查詢結果。如需`preserveNulls`設定及其如何影響資料隱私權保證的詳細資訊，請參閱 [的加密運算 Clean Rooms](crypto-computing.md)。 #### 大小增加是否來自資料sealed欄？ 如果對儲存體增加貢獻最大的資料欄是資料sealed欄，則有一些詳細資訊可能會導致大小增加。 如果cleartext資料很小 （例如，客戶年齡），則每個產生的sealed加密文字長度至少為 91 個位元組。遺憾的是，此問題無法解決。如需詳細資訊，請參閱 [sealed 資料欄的基本額外負荷](#sealed-columns-base-overhead) 以取得此欄的詳細資訊，包括其如何影響儲存需求。 資料sealed欄儲存增加的第二個主要原因是填補。在加密cleartext之前，填補會將額外的位元組新增至 ，以隱藏資料集中個別值的大小。建議您將填補設定為資料集的最小可能值。至少，`pad_length`對於`fixed`填補，必須設定為包含資料欄中最大的可能值。任何高於 的設定都不會新增額外的隱私權保證。例如，如果您知道欄中最大的可能值可以是 50 個位元組，建議您`pad_length`將 設定為 50 個位元組。不過，如果資料sealed欄使用`max`填補，建議您`pad_length`將 設定為 0 位元組。這是因為`max`填補是指超出資料欄中最大值*的額外*填補。 資料sealed欄大小增加的最終可能原因是協同合作設定 `preserveNulls`。如果停用 `preserveNulls` 的協同合作設定 （預設設定），資料sealed欄中的所有`null`值都會變成 91 個位元組的加密文字。在目前的協同合作中，無法對此執行任何操作。`preserveNulls` 設定是在建立協同合作時設定，且所有協同合作者必須使用相同的設定，以確保正確的查詢結果。如需此設定的詳細資訊，以及啟用它如何影響資料的隱私權保證，請參閱 [的加密運算 Clean Rooms](crypto-computing.md)。