翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # とは AWS Clean Rooms AWS Clean Rooms は、お客様とパートナーが集合データセットを分析して共同作業を行い、基盤となるデータを相互に公開することなく、新しいインサイトを得ることができます。 AWS Clean Rooms は安全なコラボレーションワークスペースであり、独自のクリーンルームを数分で作成し、集合データセットをわずか数ステップで分析できます。コラボレーションするパートナーを選択し、データセットを選択し、それらのパートナーのプライバシー強化コントロールを設定します。 を使用すると AWS Clean Rooms、既に使用している何千もの企業とコラボレーションできます AWS。コラボレーションでは、データを から移動 AWS したり、別のクラウドサービスプロバイダーにロードしたりする必要はありません。クエリまたはジョブを実行すると、 はそのデータの元の場所からデータを AWS Clean Rooms 読み取り、組み込みの分析ルールを適用して、そのデータの制御を維持します。 AWS Clean Rooms には、設定できる組み込みのデータアクセスコントロールと監査サポートコントロールが用意されています。これらの制御には以下が含まれます。 + SQL クエリを制限し、出力制約を提供する[分析ルール](analysis-rules.md)。 + [Cryptographic Computing for Clean Rooms](crypto-computing.md) は、クエリが処理されてもデータを暗号化し、厳格なデータ処理ポリシーに準拠します。 + でクエリとジョブを確認し、監査のサポート AWS Clean Rooms に役立つ[分析ログ](query-logs.md)。 + ユーザー識別の試みから保護するための[差分プライバシー](differential-privacy.md)。 AWS Clean Rooms 差分プライバシーは、数ステップで適用できる数学に基づく手法と直感的なコントロールにより、ユーザーのプライバシーを保護するフルマネージド機能です。 + [AWS Clean Rooms ML](machine-learning.md) を使用すると、2 つの当事者がデータ内の類似ユーザーを識別でき、相互にデータを共有する必要はありません。1 番目の関係者はトレーニングデータから類似モデルを作成し、設定します。次に、トレーニングデータに似た類似セグメントを作成するために、シードデータがコラボレーションに持ち込まれます。 次の動画では、 の詳細について説明します 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/ja_jp/clean-rooms/latest/userguide/images/how-it-works.png) ## 関連サービス ### AWS サービス 以下は AWS のサービス 、 に関連しています AWS Clean Rooms。 + **Amazon Athena** コラボレーションメンバーは、Amazon Athena の AWS Glue Data Catalog ビュー AWS Clean Rooms として取り込むデータを保存できます。詳細については、以下の各トピックを参照してください。 詳細については、以下の各トピックを参照してください。 [でのクエリ用のデータテーブルの準備 AWS Clean Rooms](prepare-data.md) [設定済みテーブルの作成 – Amazon Athena データソース](create-config-table-athena.md) [Amazon Athena ユーザーガイドの「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** CloudTrail ログ AWS Clean Rooms で を使用して、 AWS のサービス アクティビティの分析を強化します。 詳細については、「[を使用した AWS Clean Rooms API コールのログ記録 AWS CloudTrail](logging-using-cloudtrail.md)」を参照してください。 + **AWS Entity Resolution** AWS Clean Rooms で AWS Entity Resolution を使用してエンティティ解決を実行します。 詳細については、「[AWS Entity Resolution in 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** コラボレーションメンバーは、取り込むデータを Snowflake ウェアハウス AWS Clean Rooms に保存できます。 詳細については、以下の各トピックを参照してください。 [でのクエリ用のデータテーブルの準備 AWS Clean Rooms](prepare-data.md) [設定済みテーブルの作成 – Snowflake データソース](create-config-table-snowflake.md) ## アクセス AWS Clean Rooms には、次のオプション AWS Clean Rooms を使用してアクセスできます。 + [https://console.aws.amazon.com/cleanrooms/](https://console.aws.amazon.com/cleanrooms/) の AWS Clean Rooms コンソールから直接。 + AWS Clean Rooms API を使用してプログラムで。詳細については、「[AWS Clean Rooms APIリファレンス**](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 の ID 列には 100 という出力の制約があります。 + コラボレーター B の ID 列には 150 という出力の制約があります。 両方の設定済みテーブルを参照する集約クエリで、クエリ出力に行を表示するには、1 つの出力行に少なくとも 150 個の個別 ID 値が必要です。クエリ出力には、出力の制約により結果が削除されたことは示されません。 **Example 制限に関するコントロール: 未承認の分析テンプレート** + コラボレーター A は、カスタム分析ルールで、コラボレーター A とコラボレーター B の設定済みテーブルを参照するクエリを含む分析テンプレートを許可しました。 + コラボレーター B はこの分析テンプレートを許可していません。 コラボレーター B が分析テンプレートを許可していないため、クエリを実行できるメンバーはその分析テンプレートを実行できません。 ## 分析ルールの種類 分析ルールには、[集計](analysis-rules-aggregation.md)、[リスト](analysis-rules-list.md)、[カスタム](analysis-rules-custom.md)の 3 種類があります。以下の表で、分析ルールの種類を比較しています。各種分析ルールの指定については、それぞれ別のセクションで説明しています。 **注記** ID マッピングテーブル分析ルールと呼ばれる分析ルールタイプがあります。ただし、この分析ルールは によって管理 AWS Clean Rooms され、変更することはできません。詳細については、「[ID マッピングテーブル分析ルール](analysis-rules-id-mapping-table.md)」を参照してください。 以下のセクションでは、各分析ルールタイプでサポートされているユースケースとコントロールについて説明します。 ### 対応するユースケース 次の表は、各種分析ルールで対応しているユースケースの比較をまとめたものです。 | ユースケース | [集計](analysis-rules-aggregation.md) | [リスト](analysis-rules-list.md) | [カスタム](analysis-rules-custom.md) | | --- | --- | --- | --- | | 対応する分析 | COUNT、SUM、および AVG 関数を使用して、任意のディメンションで統計を集約するクエリ | 複数のテーブルが重複している箇所の行レベルのリストを出力するクエリ | 分析テンプレートまたは分析作成者によって確認、許可されている、あらゆるカスタム分析 | | 一般的なユースケース | セグメント分析、測定、アトリビューション | エンリッチメント、セグメント構築 | ファーストタッチアトリビューション、増分分析、オーディエンス発掘 | | SQL 構文 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/clean-rooms/latest/userguide/analysis-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/clean-rooms/latest/userguide/analysis-rules.html) | SELECT コマンドで使用できる SQL 関数と SQL 構文の大部分 | | サブクエリと共通テーブル式 (CTE) | いいえ | いいえ | はい | | 分析テンプレート | いいえ | いいえ | はい | ### 対応するコントロール 次の表は、各分析ルールタイプで基になるデータがどのように保護されるのか、その比較をまとめたものです。 | コントロール | [集計](analysis-rules-aggregation.md) | [リスト](analysis-rules-list.md) | [カスタム](analysis-rules-custom.md) | | --- | --- | --- | --- | | コントロールのメカニズム | テーブル内のデータをクエリでどのように使用してよいかを制御します (hashed\$1email 列の COUNT と SUM を許可するなど)。** | テーブル内のデータをクエリでどのように使用してよいかを制御します (hashed\$1email 列の使用を結合のみで許可するなど)。** | テーブルでどのクエリを実行してよいかを制御します (分析テンプレート「Custom query 1」で定義されたクエリのみを許可するなど)。** | | 組み込みのプライバシー強化機能 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/clean-rooms/latest/userguide/analysis-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/clean-rooms/latest/userguide/analysis-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/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)」で定義されている分析ルールのパラメータには、クエリコントロールとクエリ結果コントロールがあります。クエリコントロールでは、直接または間接的にクエリを実行できるメンバーが所有する 1 つ以上の設定済みテーブルに、1 つの設定済みテーブルを結合することを要求できます。この要求により、クエリを自分のテーブルと相手のテーブルの交差部分 (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/ja_jp/clean-rooms/latest/userguide/analysis-rules-aggregation.html) `select_aggregate_expression` には少なくとも 1 つの `select_aggregation_function_expression` が必要です。 | `SELECT SUM(PRICE), user_segment` | | select\$1aggregation\$1function\$1expression | 1 つ以上の列に適用される、1 つ以上のサポートされている集約関数です。集約関数の引数として指定できるのは列だけです。 `select_aggregate_expression` には少なくとも 1 つの `select_aggregation_function_expression` が必要です。 | `AVG(PRICE)` `COUNT(DISTINCT user_id)` | | select\$1grouping\$1column\$1expression | 以下を使用する任意の式を含めることができる式です。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/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/ja_jp/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/ja_jp/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 | ブール値を返す条件式です。サポートされている集約関数が 1 つの列に適用され (例えば `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)` | 集約クエリの構造と構文については、次の点に注意してください。 + SELECT 以外の SQL コマンドはサポートされていません。 + サブクエリと共通テーブル式 (WITH など) はサポートされていません。 + 複数のクエリを組み合わせる演算子 (UNION など) はサポートされていません。 + TOP、LIMIT、および OFFSET パラメータはサポートされていません。 ## 集計分析ルール - クエリコントロール 集約クエリコントロールを使用すると、テーブル内の列を使用してテーブルにクエリを実行する方法を制御できます。例えば、どの列を結合に使用するか、どの列がカウントされるようにするか、WHERE ステートメントでどの列を使用できるようにするかを制御できます。 以下のセクションでは、それぞれのコントロールについて説明します。 **Topics** + [集約コントロール](#agg-functions) + [結合コントロール](#join-controls) + [ディメンションコントロール](#dimension-controls) + [スカラー関数](#scalar-functions) ### 集約コントロール 集約コントロールを使用すると、どの集約関数を許可し、どの列に適用するかを定義できます。**集約関数は、SELECT、HAVING、および ORDER BY の式で使用できます。 | コントロール | 定義 | 使用方法 | | --- | --- | --- | | aggregateColumns | 集約関数での使用を許可する設定済みテーブル列の列。 | `aggregateColumns` は、SELECT、HAVING、および ORDER BY の式の集約関数で使用できます。 一部の `aggregateColumns` は `joinColumn` としても分類されることがあります (後述)。 特定の `aggregateColumn` は `dimensionColumn` としても分類されることはありません (後述)。 | | function | aggregateColumns で使用できる COUNT 関数、SUM 関数、および AVG 関数。 | `function` は関連付けられている `aggregateColumns` に適用できます。 | ### 結合コントロール `JOIN` 句を使用して、2 つ以上のテーブルの行を、テーブル間の関連する列に基づいて結合します。 *結合コントロール*を使用して、テーブルを の他のテーブルに結合する方法を制御できます`table_expression`。 は INNER AWS Clean Rooms のみをサポートしますJOIN。 INNERJOINステートメントは、定義したコントロールに従って、分析ルール`joinColumn`で として明示的に分類された列のみを使用できます。 INNER JOIN は、自身の設定済みテーブルの `joinColumn` と、コラボレーション内のもう 1 つの設定済みテーブルの `joinColumn` で動作する必要があります。テーブルのどの列を `joinColumn` として使用できるようにするかはテーブルの所有者が決定します。 ON 句内の一致条件ごとに、2 つの列間の等価比較条件 (`=`) を使用する必要があります。 ON 句では次のようにして複数の一致条件を使用できます。 + `AND` 論理演算子を使用して組み合わせる + `OR` 論理演算子を使用して区切る **注記** JOIN の一致条件では、必ず JOIN の各側の 1 つの行が一致しなければなりません。`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 ``` | コントロール | 定義 | 使用方法 | | --- | --- | --- | | joinColumns | クエリを行えるメンバーに INNER JOIN ステートメントでの使用を許可する列 (ある場合)。 | 特定の `joinColumn` は `aggregateColumn` としても分類されることがあります (「[集約コントロール](#agg-functions)」を参照)。 同じ列を `joinColumn` と `dimensionColumns` の両方として使用することはできません (後述)。 `aggregateColumn` としても分類されていない限り、INNER JOIN 以外のクエリの他のどの部分でも `joinColumn` を使用することはできません。 | | joinRequired | クエリを行えるメンバーの設定済みテーブルとの INNER JOIN を必須にするかどうかを制御します。 | このパラメータを有効した場合、INNER JOIN は必須になります。このパラメータを有効にしない場合、INNER JOIN はオプションになります。 このパラメータを有効にすると、クエリを行えるメンバーは、自身が所有するテーブルを INNER JOIN に必ず含めなければなりません。クエリを行えるメンバーは、自身のテーブルを相手のテーブルと直接または間接的 (つまり自分のテーブルを、相手のテーブルと結合されている別のテーブルに結合) に JOIN する必要があります。 | 以下は間接的な結合の例です。 ``` ON my_table.identifer = third_party_table.identifier .... ON third_party_table.identifier = member_who_can_query_table.id ``` **注記** クエリを行えるメンバーが、`joinRequired` パラメータを使用することもできます。その場合、クエリで自分のテーブルを少なくとも 1 つの他のテーブルと結合する必要があります。 ### ディメンションコントロール **ディメンションコントロールは、集約列をフィルタリング、グループ化、または集計する際の基準となる列を制御します。 | コントロール | 定義 | 使用方法 | | --- | --- | --- | | dimensionColumns | クエリを行えるメンバーに SELECT、WHERE、GROUP、BY、および ORDER BY での使用を許可する列 (ある場合)。 | `dimensionColumn` は、SELECT (`select_grouping_column_expression`)、WHERE、GROUP、BY、および ORDER BY で使用できます。 同じ列を `dimensionColumn` と `joinColumn` または `aggregateColumn` の両方として使用することはできません。 | ### スカラー関数 **スカラー関数は、どのスカラー関数をディメンション列に使用できるかを制御します。 | コントロール | 定義 | 使用方法 | | --- | --- | --- | | scalarFunctions | クエリの `dimensionColumns` で使用できるスカラー関数。 | `dimensionColumns` での適用を許可するスカラー関数 (CAST など) を指定します (ある場合)。 スカラー関数を他の関数と重ねて使用したり、他の関数内で使用したりすることはできません。スカラー関数の引数には、列、文字列リテラル、または数値リテラルを使用できます。 | 以下のスカラー関数がサポートされています。 + 数学関数 – 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)」を参照してください。 ## 集計分析ルール - クエリ結果コントロール 集約クエリ結果コントロールでは、返される各出力行が満たす必要がある条件を 1 つ以上指定することで、どの結果を返すかを制御できます。 AWS Clean Rooms では、`COUNT (DISTINCT column) >= X` という形式の集約制約をサポートしています。この形式では、設定済みテーブルから、選択した少なくとも X 個の個別値 (例えば、個別の `user_id` 値の最小数) を各行が集約することになります。送信されたクエリ自体が指定された列を使用しない場合でも、この最小数のしきい値は自動的に適用されます。これらは、コラボレーション内の各メンバーの設定済みテーブルから、クエリ内の各設定済みテーブルにまとめて適用されます。 各設定済みテーブルの分析ルールには、少なくとも 1 つの集約制約が必要です。設定済みテーブルの所有者が複数の `columnName` や関連付けられた `minimum` を追加すると、それらはまとめて適用されます。 ### 集約制約 **集約制約は、クエリ結果のどの行を返すかを制御します。行が返されるには、その行が、集約制約で指定された各列で、指定された個別値の最小数を満たす必要があります。この要件は、クエリや分析ルールの他の部分にその列が明示的に記述されていない場合でも適用されます。 | コントロール | 定義 | 使用方法 | | --- | --- | --- | | 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] }, ] } ``` ## 集計分析ルール - 例 次の例は、2 つの企業が集約分析 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` の数を合計して購入数と比較できるようにします。集約クエリを有効にしているため、少なくとも 1 つは集約列があります。 `joinColumns` – B 社は、A 社が返品データの顧客と売上データの顧客を照合できるよう、`identifier` での結合を有効にします。`identifier` データは特に機密性が高く、`joinColumn` として指定すれば、データがクエリで出力されることはありません。 `joinRequired` – B 社は、返品データと売上データの重複に関するクエリを必須にします。A 社が B 社のデータセット内のすべての個人を照会できるようにはしたくありません。その制限についてはコラボレーション契約でも合意しています。 `dimensionColumns` – B 社 は、A 社が `state`、`popularpurchases`、`customerserviceuser` の属性でフィルタとグループ化を実行できるようにします。これらは A 社の分析に役立つ固有の属性です。B 社 は、A 社 が `returndate` を使用して `purchasedate` の後に発生した `returndate` で出力をフィルタリングできるようにします。このフィルタリングにより、出力がより正確になり、製品変更の影響を評価できるようになります。 `scalarFunctions` – B 社は以下を有効にします。 + 日付の TRUNC + `producttype` が異なる形式でデータに入力された場合の LOWER と UPPER + A 社が売上のデータ型を返品のデータ型と同じものに変換する必要がある場合の CAST A 社は、他のスカラー関数はクエリに必要ではないと考えているため、有効にしていません。 `outputConstraints` – B 社は、顧客の再識別が困難になるように、`hashedemail` に最小数の出力制約を設定します。また、返品された特定の製品の再識別が困難になるように、`producttype` にも最小数の出力制約を設定します。出力のディメンション (`state` など) によっては、特定の製品タイプがより優勢になる可能性があります 。A 社がデータに追加した出力の制約にかかわらず、B 社の出力の制約が常に適用されます。 1. A 社が、売上テーブルとコラボレーションとの関連付けを作成します。 1. B 社が、返品テーブルとコラボレーションとの関連付けを作成します。 1. A 社が、B 社の返品数を 2022 年の場所別の購入総数と比較して詳しく把握するために、次の例のようなクエリを実行します。 ``` 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) ### クエリから何も結果が返されない この問題は、一致する結果がない場合や、一致する結果が最小数の集約しきい値を 1 つ以上満たしていない場合に発生する可能性があります。 最小数の集約しきい値の詳細については、「[集計分析ルール - 例](#agg-analysis-rule-example)」を参照してください。 # リスト分析ルール では AWS Clean Rooms、*リスト分析ルール*は、追加された設定済みテーブルとクエリ可能なメンバーの設定済みテーブルとの重複の行レベルのリストを出力します。クエリを行えるメンバーが、リスト分析ルールを含むクエリを実行します。 リスト分析ルールは、エンリッチメントやオーディエンス構築などのユースケースに対応します。 この分析ルールの事前定義されたクエリ構造と構文の詳細については、「[リスト分析ルールの事前定義された構造](#intersection-list-params-template)」を参照してください。 [リスト分析ルール - クエリコントロール](#parameters-list-query-controls) で定義されているリスト分析ルールのパラメータにはクエリコントロールがあります。クエリコントロールには、出力に表示できる列を選択する機能が含まれています。クエリには、直接または間接的にクエリを実行できるメンバーの設定済みテーブルとの結合が少なくとも 1 つ必要です。 [集計分析ルール](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 | テーブル列名を 1 つ以上含むカンマ区切りリストです。 `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/ja_jp/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/ja_jp/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 など) はサポートされていません。 + HAVING、GROUP BY、および ORDER BY 句はサポートされていません。 + OFFSET パラメータはサポートされていません。 ## リスト分析ルール - クエリコントロール リストクエリコントロールを使用すると、テーブル内の列を使用してテーブルにクエリを実行する方法を制御できます。例えば、どの列を結合に使用するか、SELECT ステートメントや WHERE 句でどの列を使用できるようにするかを制御できます。 以下のセクションでは、それぞれのコントロールについて説明します。 **Topics** + [結合コントロール](#list-controls-join-controls) + [リストコントロール](#list-controls) ### 結合コントロール **結合コントロールを使用することで、テーブルを **table\$1expression** で他のテーブルに結合する方法を制御できます。 AWS Clean Rooms は、INNER JOIN のみをサポートしています。リスト分析ルールでは、少なくとも 1 つの 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` と、コラボレーション内のもう 1 つの設定済みテーブルの `joinColumn` で動作する必要があります。テーブルのどの列を `joinColumn` として使用できるようにするかはテーブルの所有者が決定します。 ON 句内の一致条件ごとに、2 つの列間の等価比較条件 (`=`) を使用する必要があります。 ON 句では次のようにして複数の一致条件を使用できます。 + `AND` 論理演算子を使用して組み合わせる + `OR` 論理演算子を使用して区切る **注記** JOIN の一致条件では、必ず JOIN の各側の 1 つの行が一致しなければなりません。`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 ``` | コントロール | 定義 | 使用方法 | | --- | --- | --- | | joinColumns | クエリを行えるメンバーに INNER JOIN ステートメントでの使用を許可する列。 | 同じ列を `joinColumn` と `listColumn` の両方に分類することはできません (「[リストコントロール](#list-controls)」を参照)。 `joinColumn` は INNER JOIN 以外のクエリのどの部分でも使用できません。 | ### リストコントロール *リストコントロール*は、クエリ出力に一覧表示できる (SELECT ステートメントで使用される) 列や、結果のフィルタリングに使用できる (WHERE ステートメントで使用される) 列を制御します。 | コントロール | 定義 | 使用方法 | | --- | --- | --- | | listColumns | クエリを行えるメンバーに SELECT および WHERE での使用を許可する列。 | listColumn は SELECT と WHERE で使用できます。同じ列を `listColumn` と `joinColumn` の両方として使用することはできません。 | ## リスト分析ルールの事前定義された構造 次の例には、リスト分析ルールを完成させる方法を示す事前定義された構造が含まれています。 次の例では、*`MyTable`* がデータテーブルを表しています。各*ユーザー入力プレースホルダー*は、独自の情報に置き換えることができます。 ``` { "joinColumns": [MyTable column name(s)], "listColumns": [MyTable column name(s)], } ``` ## リスト分析ルール - 例 次の例は、2 つの企業がリスト分析 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` (ID ベンダーから取得) を使用して CRM データの顧客とセグメントデータの顧客を照合したいと考えています。これにより、A 社は適切な顧客のエンリッチメントデータと照合できるようになります。JoinColumns が 2 つあることで、分析の一致率が向上する可能性があります。 `listColumns` – A 社は、`listColumns` を使用して、自社のシステム内で使用している `internalid` に加えてエンリッチメントのための列を取得します。`segment1`、`segment2`、`customercategory` を追加し、フィルタで使用することでエンリッチメントを特定のセグメントに限定できるようにします。 1. B 社が、設定済みセグメントテーブルを作成します。 1. B 社が、分析ルールを設定済みセグメントテーブルに追加します。 ``` { "joinColumns": [ "identifier2" ], "listColumns": [ "segment3", "segment4" ] } ``` `joinColumns` – B 社は、A 社が `identifier2` で結合を実行して、セグメントデータの顧客を CRM データの顧客と照合できるようにします。A 社と B 社は ID ベンダーと協力して、今回のコラボレーションに適していそうな `identifier2` を取得しています。`identifier2` は最も一致率が高く、最も正確で、これ以外の ID はクエリに必要ないと考えられたため、他の `joinColumns` は追加しませんでした。 `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、CTE、サブクエリなど。詳細なリストについては、「[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** のような、ユーザーを一意に識別する列です。コラボレーションで差分プライバシーが有効になっているテーブルが 2 つ以上ある場合は、 AWS Clean Rooms では、テーブル間でユーザーの一貫した定義を維持するために、両方の分析ルールで同じ列をユーザー ID 列として設定する必要があります。 ``` { "allowedAnalyses": ["ANY_QUERY"] | string[], "allowedAnalysisProviders": [], "differentialPrivacy": { "columns": [ { "name": "userIdentifier" } ] } } ``` 次のいずれかを行うことができます。 + 分析テンプレート ARN を許可された分析コントロールに追加します。この場合、`allowedAnalysisProviders` コントロールは含まれません。 ``` { allowedAnalyses: string[] } ``` + AWS アカウント IDsを`allowedAnalysisProviders`コントロールに追加します。この場合は、`ANY_QUERY` を `allowedAnalyses` コントロールに追加します。 ``` { allowedAnalyses: ["ANY_QUERY"], allowedAnalysisProviders: string[] } ``` ## カスタム分析ルールの例 次の例は、2 つの企業がカスタム分析ルール AWS Clean Rooms を使用して でコラボレーションする方法を示しています。 A 社には顧客データと売上データがあります。A 社は、B 社のサイトで実施した広告キャンペーンによる売上の増分を把握したいと考えています。B 社には、A 社にとって有用な閲覧データとセグメント属性 (広告を閲覧する際に使用したデバイスなど) があります。 企業 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 など) をカスタム分析ルールの許可された分析プロバイダーコントロールに追加します。A 社は、作成したすべてのクエリを設定済み販売テーブルで実行できるようにしたいため、許可された分析プロバイダーコントロールを使用しています。 ``` { "allowedAnalyses": [ "ANY_QUERY" ], "allowedAnalysisProviders": [ "444455556666" ] } ``` 1. B 社が、作成された分析テンプレートをコラボレーション内で確認し、クエリ文字列やパラメータなどの内容を確認します。 1. B 社が、分析テンプレートが増分のユースケースに対応しており、設定済み視聴者数テーブルのクエリの実行方法がプライバシー要件を満たしていることを判断します。 1. B 社が、視聴者数テーブルのカスタム分析ルールの許可された分析コントロールに分析テンプレート ARN を追加します。B 社は、設定済み視聴者数テーブルでのみ増分クエリを実行できるようにしたいため、許可された分析コントロールを使用しています。 ``` { "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、カスタム分析ルールは差分プライバシーをサポートしています。差分プライバシーは、データプライバシー保護のための数学的に厳格なフレームワークであり、データを再識別されないように保護するのに役立ちます。 差分プライバシーは、広告キャンペーン計画、広告キャンペーン後の測定、金融機関コンソーシアムにおけるベンチマーク、医療研究のための 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 Differential Privacy の汎用[クエリ構造](#dp-query-structure-syntax)と互換性があるため、クエリは正常に実行されます。 ### クエリの構造と構文 差分プライバシーが有効になっているテーブルが 1 つ以上含まれているクエリは、次の構文に従う必要があります。 ``` 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]) ``` **注記** 差分プライバシークエリの構造と構文については、次の点に注意してください。 サブクエリはサポートされていません。 テーブルや CTE に差分プライバシーで保護されたデータが含まれている場合は、テーブル共通式 (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 マッピングテーブルを使用して、2 人のメンバーのデータセット間の重複しない母集団を直接選択または検査することが制限されます。ID マッピングテーブル分析ルールは、他の分析ルールを使用したクエリで暗黙的に使用される場合に、ID マッピングテーブル内の機密データを保護するために使用されます。 ID マッピングテーブル分析ルールを使用すると、 は拡張 SQL で ID マッピングテーブルの両側に重複 AWS Clean Rooms を適用します。これにより、次のタスクを実行できます。 + JOIN ステートメントで ID マッピングテーブルの重複を使用します。 AWS Clean Rooms はINNER、ID マッピングテーブルが重複している場合、ID マッピングテーブルで 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、WHERE、HAVING、GROUP BY、または ORDER BY ステートメントでは使用できません (ソース ID 名前空間の関連付けまたはターゲット ID 名前空間の関連付けにより保護が変更される場合を除く)。 + 拡張 SQL では、 は OUTER JOIN、暗黙的な JOIN、および CROSS AWS Clean Rooms もサポートしていますJOIN。これらの結合で重複要件を満たすことはできません。代わりに、 AWS Clean Rooms を使用して、結合する必要がある列`requireOverlap`を指定します。 サポートされているクエリ構造と構文は、「[ID マッピングテーブルのクエリ構造と構文](#id-mapping-table-query-controls)」で定義されています。 「[ID マッピングテーブル分析ルールのクエリコントロール](#parameters-id-mapping-query-controls)」で定義されている分析ルールのパラメータには、クエリコントロールとクエリ結果コントロールがあります。そのクエリコントロールには、JOIN ステートメント (つまり `requireOverlap`) 内の ID マッピングテーブルの重複を要求する機能が含まれています。 **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\$1insurance** テーブルの両方の **[id]** 列は、ID マッピングテーブルと一致する列を表します。 **cr\$1drivers\$1license** | | | | | --- |--- |--- | | id | driver\$1name | state\$1of\$1registration | | 1 | Eduard | TX | | 2 | Dana | MA | | 3 | Gweneth | IL | **cr\$1insurance** | | | | | --- |--- |--- | | 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\$1insurance** テーブルで一致する既存の ID マッピングテーブルを表しています。すべてのエントリに両方のコラボレーションテーブルの ID があるわけではありません。 | | | | --- |--- | | 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 名前空間から取得される列に対してデフォルトの保護を提供するようにデフォルトで設定されています。この設定を変更して、ID 名前空間 (`sourceID` または `targetID`) から取得される列をクエリ内の任意の場所で許可できます。詳細については、「[の ID 名前空間 AWS Clean Rooms](working-with-id-namespaces.md)」を参照してください。 + ID マッピングテーブル分析ルールは、コラボレーション内の他の分析ルールの SQL 制限を継承します。 ## ID マッピングテーブル分析ルールのクエリコントロール ID マッピングテーブルクエリコントロールを使用すると、 はテーブル内の列を使用してテーブルをクエリする方法 AWS Clean Rooms を制御します。例えば、結合に使用する列と重複が必要な列を制御します。ID マッピングテーブル分析ルールには、JOIN を必要とせずに `sourceID`、`targetID`、またはその両方を射影できるようにする機能も含まれています。 以下の表では、それぞれのコントロールについて説明します。 | コントロール | 定義 | 使用方法 | | --- | --- | --- | | joinColumns | クエリを実行できるメンバーに INNER JOIN ステートメントでの使用を許可する列。 | joinColumns は INNER JOIN 以外のクエリのどの部分でも使用できません。詳細については、「[結合コントロール](analysis-rules-aggregation.md#join-controls)」を参照してください。 | | dimensionColumns | クエリを実行できるメンバーが SELECT ステートメントと GROUP BY ステートメントで使用できる列 (ある場合)。 | `dimensionColumn` は、SELECT および GROUP BY で使用できます。 `dimensionColumn` は `joinKeys` として表示されることもあります。 `dimensionColumns` は、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 マッピングテーブルは、クエリで使用できる特定の適用の対象にはなりません。 次の例は、`sourceID` と `targetID` にデフォルトの保護が適用された ID マッピングテーブル分析ルールの事前定義された構造を示しています。この例では、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 } ``` 次の例は、`targetID` に保護が適用された ID マッピングテーブル分析ルールの事前定義された構造を示しています。この例では、ID マッピングテーブル分析ルールにより、`sourceID` 列の INNER JOIN のみが許可されます。 ``` { "joinColumns": [ "source_id", "target_id" ], "queryConstraints": [ { "requireOverlap": { "columns": [ "target_id" ] } } ], "dimensionColumns": [ "source_id" ] } ``` 次の例は、`sourceID` に保護が適用された ID マッピングテーブル分析ルールの事前定義された構造を示しています。この例では、ID マッピングテーブル分析ルールにより、`targetID` 列の INNER JOIN のみが許可されます。 ``` { "joinColumns": [ "source_id", "target_id" ], "queryConstraints": [ { "requireOverlap": { "columns": [ "source_id" ] } } ], "dimensionColumns": [ "target_id" ] } ``` 次の例は、`sourceID` または `targetID` に保護が適用されない ID マッピングテーブル分析ルールの事前定義された構造を示しています。この例では、ID マッピングテーブル分析ルールにより、`sourceID` 列と `targetID` 列の両方で INNER JOIN が許可されます。 ``` { "joinColumns": [ "source_id", "target_id" ], "queryConstraints": [ { "requireOverlap": { "columns": [] } } ], "dimensionColumns": [ "source_id", "target_id" ] } ``` ## ID マッピングテーブル分析ルール – 例 例えば、企業は個人を特定できる情報 (PII) を参照する長いウォーターフォールステートメントを記述するのではなく、ID マッピングテーブル分析ルールを使ってマルチパーティー LiveRamp トランスコーディングを使用できます。次の例は、ID マッピングテーブル分析ルール AWS Clean Rooms を使用して でコラボレーションする方法を示しています。 A 社は、顧客と販売のデータを持つ広告主であり、これらのデータはソースとして使用されます。また、A 社はコラボレーションの当事者に代わってトランスコーディングを実行し、LiveRamp 認証情報を提供します。 B 社はイベントデータを持つパブリッシャーであり、このデータはターゲットとして使用されます。 **注記** A 社または B 社は、LiveRamp のトランスコーディング認証情報を提供し、トランスコーディングを実行できます。 コラボレーションで ID マッピングテーブル分析を可能にするコラボレーションを作成するためには、各社は次のことを行います。 1. A 社がコラボレーションを作成し、メンバーシップを作成します。B 社を追加します。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 社は、コラボレーションに関連付けられた 2 つの ID 名前空間を検出し、ID マッピングテーブルを作成してデータを入力します。 1. A 社は、ID マッピングテーブル上で結合することで、2 つのデータセット間でクエリを実行します。 ``` --- 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、次の点を考慮してください。 + 結果を受け取ることができるメンバーは、差分プライバシーを使用できません。これらのメンバーは、設定したテーブルの差分プライバシーをオフにしたカスタム分析ルールを設定します。 + クエリを実行できるメンバーは、2 つ以上のデータプロバイダーの差分プライバシーがオンになっている場合、テーブルを結合できません。 # 差分プライバシーポリシー 差分プライバシーポリシーは、クエリを実行できるメンバーがコラボレーション内で実行できる集計関数の数を制御します。**プライバシー予算**は、コラボレーションのすべてのテーブルに適用される共通の有限リソースを定義します。**クエリごとに追加されるノイズ**によって、プライバシー予算が枯渇する速度が決まります。 差分プライバシーで保護されたテーブルをクエリに使用できるようにするには、差分プライバシーポリシーが必要です。これはコラボレーションの 1 回限りのステップで、次の 2 つの入力が含まれます。 + **プライバシー予算** – プライバシー予算はイプシロン単位で定量化され、プライバシー保護のレベルを制御します。これは、コラボレーションにおいて差分プライバシーで保護されるすべてのテーブルに適用される共通かつ有限のリソースです。その目的は、情報が複数のテーブルに存在する可能性があるユーザーのプライバシーを保護することです。 **プライバシー予算**は、テーブルに対してクエリが実行されるたびに消費されます。プライバシー予算が使い果たされると、クエリを実行できるコラボレーションメンバーは、プライバシー予算が増えるか更新されるまで追加のクエリを実行できなくなります。プライバシー予算を大きく設定することで、結果を受け取ることができるメンバーは、データ内の個人に関する不確実性を減らすことができます。ビジネス上の意思決定者と相談した上で、コラボレーション要件とプライバシーニーズのバランスを考慮して、プライバシー予算を選択してください。 コラボレーションに定期的に新しいデータを取り込む予定がある場合は、**[プライバシー予算を毎月更新]** を選択すると、1 か月ごとに新しいプライバシー予算が自動的に作成されます。このオプションを選択すると、更新を繰り返してクエリを繰り返し実行したときに、データ行に関する任意の量の情報を公開できます。プライバシー予算が更新されるたびに同じ行が繰り返しクエリされる場合は、このオプションを選択しないでください。 + **クエリごとに追加されるノイズ**は、関与をわかりにくくするユーザーの数で測定されます。この値によって、プライバシー予算がどの程度枯渇するかが決まります。ノイズ値を大きくすると、プライバシー予算が枯渇する速度が下がるため、データに対して実行できるクエリの数が増えます。ただし、これは正確性の低いデータインサイトの公開とのバランスを取る必要があります。この値を設定するときは、コラボレーションに関するインサイトに必要な精度を考慮してください。 デフォルトの差分プライバシーポリシーを使用すると、ユースケースに応じて設定をすばやく完了したり、差分プライバシーポリシーをカスタマイズしたりできます。 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 コンストラクト | テーブル共通式 (CTE) | 最終 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 左半結合 左アンチ結合 RIGHT JOIN FULL JOIN [JOIN] OR 演算子 CROSS JOIN | ユーザー識別子列の等価結合である JOIN 関数のみがサポートされ、差分プライバシーが有効になっている複数のテーブルをクエリする場合は必須であるという条件でサポートされます。必須の等価結合条件が正しいことを確認してください。テーブル所有者がすべてのテーブルに同じユーザー ID 列を設定して、ユーザーの定義がテーブル間で一貫していることを確認します。 差分プライバシーを有効にして 2 つ以上のリレーションを組み合わせる場合、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 コンストラクト | 代替 | | --- |--- |--- | | Window 関数 | 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 integer CAST \$1column AS type | | 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)を使用して、データ準備のための共通テーブル式 (CTEs) や、、 などの一般的に使用される集計関数など`COUNT`、さまざまな SQL コンストラクトをサポートします`SUM`。実行時にクエリ結果を集計するためのノイズを追加して、データ内の可能なユーザーの寄与を難読化するために、 AWS Clean Rooms 差分プライバシーでは、最後の集計関数`SELECT statement`をユーザーレベルのデータで実行する必要があります。 次の例では、`athletic_brand_sales` データを持つスポーツブランドとのコラボレーションで差分プライバシーを使用してデータを保護したいと考えているメディアパブリッシャーの `socialco_impressions` と `socialco_users` という名前の 2 つのテーブルを使用しています。メディアパブリッシャーは、 AWS Clean Roomsで差分プライバシーを有効にして、`user_id` 列をユーザー識別子列として設定しています。広告主は差分プライバシー保護を必要としないため、組み合わせたデータに対して CTE を使用してクエリを実行したいと考えています。CTE では差分プライバシーで保護されたテーブルを使用しているため、広告主は保護されているテーブルのユーザー ID 列を CTE 列のリストに含め、保護対象のテーブルをユーザー ID 列に結合します。 ``` 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` 句にユーザー ID 列を含める必要があります。 ``` 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-backed AWS Glue テーブルを使用したクエリのみをサポートします。Snowflake または Amazon Athena テーブルを使用したクエリはサポートされていません。 1. AWS Clean Rooms 差分プライバシーはタイミング攻撃に対処しません。例えば、これらの攻撃は、個々のユーザーが大量の行を入力し、このユーザーを追加または削除するとクエリの計算時間が大幅に変化するようなシナリオで発生する可能性があります。 1. AWS Clean Rooms 差分プライバシーは、特定の SQL コンストラクトの使用が原因で実行時にオーバーフローまたは無効なキャストエラーが発生する可能性がある場合、差分プライバシーを保証しません。 次の表は、ランタイムエラーを発生させる可能性があり、分析テンプレートで検証する必要がある一部 (すべてではありません) の SQL コンストラクトのリストです。このようなランタイムエラーの可能性を最小限に抑える分析テンプレートを承認し、クエリログを定期的にレビューして、クエリがコラボレーション契約と整合しているかどうか確認することをお勧めします。 次の SQL コンストラクトは、オーバーフローエラーに対して脆弱です。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/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 では、2 人以上の関係者がデータで機械学習モデルを実行でき、相互にデータを共有する必要はありません。このサービスは、データ所有者がデータとモデル 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 クエリの結果から取得することもできます。類似セグメントの出力は、トレーニングデータに含まれるシードユーザーに最も近いユーザーの集合です。 + 類似モデル** – 他のデータセット内の類似ユーザーを見つけるために使用されるトレーニングデータの機械学習モデル。 API を使用する場合、オーディエンスモデル**という用語は類似モデルと同じ意味で使用されます。例えば、[CreateAudienceModel](https://docs.aws.amazon.com/cleanrooms-ml/latest/APIReference/API_CreateAudienceModel.html) API を使用して類似モデルを作成します。 + *類似セグメント* – シードデータに最も近いトレーニングデータのサブセット。 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/ja_jp/clean-rooms/latest/userguide/images/howItWorksML.png) 類似モデルを使用するには、トレーニングデータプロバイダーとシードデータプロバイダーの 2 つの関係者が、データをコラボレーションに取り込む AWS Clean Rooms ために順番に で作業する必要があります。トレーニングデータプロバイダーが最初に完了しなければならないワークフローは次のとおりです。 1. トレーニングデータプロバイダーのデータは、ユーザーとアイテムのインタラクション AWS Glue のデータカタログテーブルに保存する必要があります。少なくとも、トレーニングデータにはユーザー ID 列、インタラクション ID 列、およびタイムスタンプ列が含まれている必要があります。 1. トレーニングデータプロバイダーは、トレーニングデータを に登録します AWS Clean Rooms。 1. トレーニングデータプロバイダーは、複数のシードデータプロバイダーと共有できる類似モデルを作成します。類似モデルはディープニューラルネットワークであり、トレーニングに最大 24 時間かかることがあります。このモデルは自動的に再トレーニングされないため、毎週再トレーニングすることをお勧めします。 1. トレーニングデータプロバイダーは、関連メトリクスを共有するかどうかや、出力セグメントの Amazon S3 ロケーションなど、類似モデルの設定を行います。トレーニングデータプロバイダーは、1 つの類似モデルから複数の設定済み類似モデルを作成できます。 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 モデルを含むプライベートリポジトリを作成します。 コラボレーションのメンバーは、適切なアクセス許可があれば、*モデルプロバイダー*になることができます。コラボレーションのすべてのメンバーは、トレーニングデータ、推論データ、またはその両方をモデルに提供できます。このガイドでは、データを提供するメンバーを*データプロバイダー*と呼びます。コラボレーションを作成するメンバーは*コラボレーション作成者*であり、このメンバーは*モデルプロバイダー*、*データプロバイダー*の 1 つ、またはその両方です。 最も高いレベルでは、カスタム 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 互換のドッカーイメージのみをサポートしています。 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 は、2 つの当事者間でデータを共有しなくても、データ内の類似ユーザーを識別するためのプライバシー保護方法を提供します。最初のパーティはトレーニングデータを に持ち込み 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 の出力を直接観察せず、トレーニングデータプロバイダーはシードデータを観察することができません。シードデータプロバイダーは、シードデータを出力セグメントに含めることもできます。 次に、トレーニングデータのランダムなサンプルから類似モデルを作成します。このサンプルには、シードオーディエンスと一致しない多数のユーザーが含まれています。このプロセスにより、ユーザーがデータになかったかどうかを判断することが難しくなります。これは、メンバーシップ推論のもう 1 つの手段です。 さらに、シード固有の類似モデルトレーニングの各パラメータに複数のシードカスタマーを使用できます。これにより、モデルがどれだけオーバーフィットできるかが制限され、ユーザーについてどれだけ推測できるかが制限されます。この結果、シードデータの最小サイズは 500 ユーザーとすることをお勧めします。 最後に、ユーザーレベルのメトリクスはトレーニングデータプロバイダーには提供されないため、メンバーシップ推論攻撃を受ける別の手段がなくなります。 # Clean Rooms ML のトレーニングデータ要件 類似モデルを正常に作成するには、トレーニングデータが次の要件を満たしている必要があります。 + トレーニングデータは、Parquet、CSV、または JSON 形式である必要があります。 **注記** Zstandard (ZSTD) 圧縮 Parquet データはサポートされていません。 + トレーニングデータはカタログ化する必要があります AWS Glue。詳細については、 AWS Glue デベロッパーガイド[のAWS Glue データカタログの開始方法](https://docs.aws.amazon.com//glue/latest/dg/start-data-catalog.html)」を参照してください。スキーマは自動的に推測されるため、 AWS Glue クローラを使用してテーブルを作成することをお勧めします。 + トレーニングデータとシードデータを含む Amazon S3 バケットは、他の Clean Rooms ML リソースと同じ AWS リージョンにあります。 + トレーニングデータには、少なくとも 100,000 個の一意のユーザー ID が含まれ、それぞれに少なくとも 2 つのアイテムインタラクションが含まれている必要があります。 + トレーニングデータには、少なくとも 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/ja_jp/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 の一意のユーザー ID である必要があります。 + シードユーザーの最小数は、設定されたオーディエンスモデルの作成時に指定されたシードサイズの最小値と一致する必要があります。 以下は、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 は*リコール*および*関連性スコア*を計算してモデルのパフォーマンスを判断します。リコールは、類似データとトレーニングデータの類似性を比較します。関連性スコアは、モデルのパフォーマンスが良好かどうかではなく、オーディエンスの大きさを判断するために使用されます。 *リコール*は、類似セグメントがトレーニングデータとどの程度類似しているかを公平に測定するものです。リコールは、オーディエンス生成ジョブによってシードオーディエンスに含まれるトレーニングデータのサンプルからの、最も類似したユーザー (デフォルトでは最も類似した 20%) の割合です。値の範囲は 0～1 で、値が大きいほど対象者が良いことを示します。リコール値は、ビンの最大割合とほぼ等しい場合、オーディエンスモデルがランダム選択と同等であることを示します。 Clean Rooms ML はモデルの構築時に真陰性のユーザーを正確にラベル付けしていないため、AWS では、正確性、精度、F1 スコアよりも、これがより優れた評価メトリクスであると考えています。 セグメントレベルの関連性スコア**は、-1 (最も類似しない) から 1 (最も類似する) までの値を持つ類似性の尺度です。Clean Rooms ML は、さまざまなセグメントサイズについて一連の関連性スコアを計算し、データに最適なセグメントサイズを決定するのに役立ちます。関連性スコアは、セグメントサイズが大きくなるにつれて単調に減少するため、セグメントサイズが大きくなるにつれてシードデータに類似しなくなる可能性があります。セグメントレベルの関連性スコアが 0 に達すると、モデルは類似セグメントのすべてのユーザーがシードデータと同じディストリビューションに属すると予測します。出力サイズを大きくすると、類似セグメントに、シードデータと同じディストリビューションに属さないユーザーが含まれる可能性が高くなります。 関連性スコアは 1 つのキャンペーン内で標準化されるため、キャンペーン間の比較には使用しないでください。関連性スコアは、インベントリの品質、インベントリタイプ、広告のタイミングなど、関連性に加えて複数の複雑な要因によって影響を受けるため、ビジネス成果の単一ソースの証拠として使用しないでください。 関連性スコアはシードの品質を判断するためではなく、増減できるかどうかを判断するために使うべきです。次の例を考えます。 + すべて正のスコア – 類似していると予測される出力ユーザーの方が、類似セグメントに含まれるユーザーよりも多いことを示しています。これは、過去 1 か月間に歯磨き粉を購入したユーザーなど、大規模な市場に属するシードデータによく見られます。過去 1 か月に歯磨き粉を複数回購入したユーザーなど、比較的小さなシードデータを確認することをお勧めします。 + すべて負のスコア、または希望する類似セグメントサイズに対して負 – これは、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 モデルを含むプライベートリポジトリを作成します。 コラボレーションのメンバーは、適切なアクセス許可があれば、*モデルプロバイダー*になることができます。コラボレーションのすべてのメンバーは、モデルにデータを提供できます。このガイドでは、データを提供するメンバーを*データプロバイダー*と呼びます。コラボレーションを作成するメンバーは*コラボレーション作成者*であり、このメンバーは*モデルプロバイダー*、*データプロバイダー*の 1 つ、またはその両方です。 以下のトピックでは、カスタム ML モデルの作成に必要な情報について説明します。 **Topics** + [カスタム ML モデリングの前提条件](custom-model-prerequisites.md) + [トレーニングコンテナのモデル作成ガイドライン](custom-model-guidelines.md) + [推論コンテナのモデル作成ガイドライン](inference-model-guidelines.md) + [モデルログとメトリクスの受信](custom-model-logs.md) # カスタム ML モデリングの前提条件 カスタム ML モデリングを実行する前に、次の点を考慮する必要があります。 + トレーニングされたモデルのモデルトレーニングと推論の両方をコラボレーションで実行するかどうかを決定します。 + 各コラボレーションメンバーが実行するロールを決定し、適切な機能を割り当てます。 + モデルをトレーニングし、トレーニングされたモデルで推論を実行するメンバーに `CAN_QUERY`機能を割り当てます。 + コラボレーションの少なくとも 1 人のメンバー`CAN_RECEIVE_RESULTS`に を割り当てます。 + トレーニング済みモデルのエクスポート`CAN_RECEIVE_MODEL_OUTPUT`または推論出力をそれぞれ受け取るメンバーに または `CAN_RECEIVE_INFERENCE_OUTPUT` の機能を割り当てます。ユースケースで必要な場合は、両方の機能を使用できます。 + エクスポートを許可するトレーニング済みモデルアーティファクトまたは推論結果の最大サイズを決定します。 + すべてのユーザーには、ロールに `CleanrooomsFullAccess`および `CleanroomsMLFullAccess`ポリシーがアタッチされていることをお勧めします。カスタム ML モデルを使用するには、 AWS Clean Rooms と AWS Clean Rooms ML SDKs の両方を使用する必要があります。 + IAM ロールに関する次の情報を考慮してください。 + すべてのデータプロバイダーには、 が AWS Glue カタログとテーブル、および基盤となる Amazon S3 ロケーションからデータ AWS Clean Rooms を読み取ることができるサービスアクセスロールが必要です。これらのロールは、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)」を参照してください。 + モデル作成者は、モデルの入力と出力が によって期待どおりに設定されていることを確認する[推論コンテナのモデル作成ガイドラインモデルログとメトリクスの受信](inference-model-guidelines.md)ために、 [トレーニングコンテナのモデル作成ガイドライン](custom-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 トレーニング、および Clean Rooms ML でテストできるように AWS アカウント、以下を確認してください。 + さまざまな環境変数を使用して、トレーニング環境に関する有用なプロパティにアクセスするトレーニングスクリプトを作成することをお勧めします。Clean Rooms ML は、次の引数を使用してモデルコードのトレーニングを呼び出します: `SM_MODEL_DIR`、`SM_OUTPUT_DIR`、`SM_CHANNEL_TRAIN`、`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 トレーニング環境テスト、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 ジョブが完了し、モデルアルゴリズムに満足したら、Amazon ECR レジストリを AWS Clean Rooms ML に登録できます。`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 バッチ変換、および Clean Rooms ML でテストできるように AWS アカウント、以下を確認してください。 + 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 ジョブが完了し、バッチ変換に満足したら、Amazon ECR レジストリを AWS Clean Rooms ML に登録できます。`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 Metrics を介してジョブの進行状況として表示できます。 **モデルログ** モデルログへのアクセスは、設定された各モデルアルゴリズムのプライバシー設定ポリシーによって提供されます。モデル作成者は、設定されたモデルアルゴリズムを (コンソールまたは `CreateConfiguredModelAlgorithmAssociation` API を介して) コラボレーションに関連付けるときに、プライバシー設定ポリシーを設定します。プライバシー設定ポリシーを設定すると、どのメンバーがモデルログを受信できるかが制御されます。 さらに、モデル作成者は、プライバシー設定ポリシーでフィルターパターンを設定して、ログイベントをフィルタリングできます。モデルコンテナが `stdout`または に送信`stderr`し、フィルターパターン (設定されている場合) に一致するすべてのログが Amazon CloudWatch Logs に送信されます。モデルログは`/aws/cleanroomsml/TrainedModelInferenceJobs`、CloudWatch ロググループ`/aws/cleanroomsml/TrainedModels`または でそれぞれ使用できます。 **カスタム定義メトリクス** モデルアルゴリズムを設定する場合 (コンソールまたは `CreateConfiguredModelAlgorithm` API 経由）、モデル作成者は、出力ログで検索する特定のメトリクス名と正規表現ステートメントを指定できます。これらは、`/aws/cleanroomsml/TrainedModels`名前空間の CloudWatch Metrics を介してジョブの進行状況として表示できます。設定されたモデルアルゴリズムを関連付ける場合、モデル作成者はメトリクスのプライバシー設定でオプションのノイズレベルを設定して、カスタムメトリクスの傾向を可視化しながら raw データの出力を回避できます。ノイズレベルが設定されている場合、メトリクスはリアルタイムではなくジョブの最後に発行されます。 # Cryptographic Computing for Clean Rooms Cryptographic Computing for Clean Rooms (C3R) は、[分析ルール](analysis-rules.md)に加えて AWS Clean Rooms 使用できる の機能です。C3R を使うと、組織は機密データをまとめて、データ分析から新しいインサイトを引き出せると同時に、プロセスの中で関係者が知ることのできる事項を暗号化によって制限できます。C3R は、コラボレーションで機密データを扱いたいが、クラウド内の暗号化されたデータのみを使用する必要がある複数の関係者が使用できます。 C3R 暗号化クライアントは、 で使用するデータを[暗号化](glossary.md#glossary-encryption)するために使用できるクライアント側の暗号化ツールです AWS Clean Rooms。C3R 暗号化クライアントを使用する場合、 AWS Clean Rooms データはコラボレーションで使用中も暗号化によって保護されます。通常の AWS Clean Rooms コラボレーションと同様に、入力データはリレーショナルデータベーステーブルであり、計算は SQL クエリとして表されます。ただし、暗号化されたデータに対する SQL クエリについて、C3R は一部の限られたクエリしかサポートしていません。 具体的には、暗号で保護されたデータに対する SQL JOIN および SELECT のステートメントをサポートしています。入力テーブルの各列は、次の SQL ステートメントタイプのいずれか 1 つだけで使用できます。 + JOIN ステートメントで使用される、暗号化によって保護された列は**fingerprint列**と呼ばれます。 + SELECT ステートメントで使用される、暗号化によって保護された列は**sealed列**と呼ばれます。 + JOIN または SELECT ステートメントで使用される、暗号化によって保護されていない列は**cleartext列**と呼ばれます。 場合によっては、GROUP BY ステートメントがfingerprint列でサポートされることもあります。詳細については、「[Fingerprint列](crypto-computing-column-types.md#fingerprint-columns)」を参照してください。現在 C3R では、関連する分析ルールで許可されている場合でも、WHERE 句、または SUM や AVERAGE といった集約関数など、他の SQL 構文の暗号化済みデータへの使用はサポートしていません。 C3R はテーブルの個々のセル内のデータを保護するように設計されています。C3R のデフォルト設定を使用すると、お客様がコラボレーションを通じてサードパーティに提供する基データは、コンテンツが AWS Clean Rooms内部で使用されている間は暗号化されたままになります。C3R では、すべてのsealed列に業界標準の AES-GCM 暗号化を使用し、fingerprint列の保護には Hash-based Message Authentication Code (HMAC) と呼ばれる業界標準の疑似ランダム機能を使用します。 C3R はテーブル内のデータを暗号化しますが、以下の情報は推測できる場合があります。 + テーブルの列数、列名、行数など、テーブル自体に関する情報。 + ほとんどの標準的な暗号化形式と同様、C3R では、暗号化された値の長さについては隠蔽を試みません。C3R には、暗号化された値をパディングしてクリアテキストの正確な長さを隠蔽する機能がありますが、各列のクリアテキストの長さの上限は、第三者に把握される可能性があります。 + 暗号化された C3R テーブルに特定の行がいつ追加されたかなど、ログレベルの情報。 C3R の詳細については、以下のトピックを参照してください。 **Topics** + [Cryptographic Computing for Clean Rooms を使用する際の考慮事項](crypto-computing-considerations.md) + [Cryptographic Computing for Clean Rooms でサポートされているファイルとデータの種類](crypto-computing-file-types.md) + [Cryptographic Computing for Clean Rooms での列名](crypto-computing-column-names.md) + [Cryptographic Computing for Clean Rooms での列タイプ](crypto-computing-column-types.md) + [暗号コンピューティングパラメータ](crypto-computing-parameters.md) + [Cryptographic Computing for Clean Rooms のオプションフラグ](crypto-computing-optional-flags.md) + [クエリと Cryptographic Computing for Clean Rooms](crypto-computing-queries.md) + [C3R 暗号化クライアントのガイドライン](crypto-computing-guidelines.md) # Cryptographic Computing for Clean Rooms を使用する際の考慮事項 Cryptographic Computing for 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` 列は暗号化されています。`City` 列の値 `Chicago` を見れば、`State` の値が`Illinois` であることを高い確率で特定できます。逆に、一方の列が `City` で、もう一方の列が `EmailAddress` の場合、暗号化されている `EmailAddress` の情報がcleartext `City` によって明らかになることはまずありません。 このシナリオのパラメータの詳細については、「[[cleartext 列を許可] パラメータ](crypto-computing-parameters.md#parameter-allowcleartext)」を参照してください。 ## fingerprint列で値の繰り返しを許可する 最も安全な方法では、どのfingerprint列にも変数のインスタンスが 1 つだけ含まれていると想定されてます。1 つのfingerprint列で項目を繰り返すことはできません。C3R 暗号化クライアントは、これらのcleartext値をランダム値と見分けがつかない一意の値にマッピングします。したがって、これらのランダム値からcleartextに関する情報を推測することはできません。 fingerprint列で値が繰り返される場合のリスクは、値が繰り返されるとランダムに見える値も繰り返されることです。したがって理論的には、暗号化されたテーブルにアクセスできる人なら誰でもfingerprint列の統計分析を行って、cleartext値に関する情報を明らかにできる可能性があります。 例えば、fingerprint列が `State` で、テーブルのすべての行が米国の世帯に対応しているとします。頻度分析を行うことで、どの州が `California` でどの州が `Wyoming` であるかを高い確率で推測できます。この推測が可能なのは、`California` の方が `Wyoming` よりも住民の数がはるかに多いからです。逆に、fingerprint列が世帯識別子に関するもので、数百万件のエントリからなるデータベースの中で各世帯が 1 ～ 4 回出現したとします。この場合、頻度分析によって有用な情報が明らかになることはまずありません。 このシナリオのパラメータの詳細については、「[[複製を許可] パラメータ](crypto-computing-parameters.md#parameter-allowduplicates)」を参照してください。 ## fingerprint列の命名方法に関する制限を緩和する デフォルトでは、暗号化されたfingerprint列を使用して 2 つのテーブルが結合される場合、各テーブルのそれらの列は名前が同じであると想定されます。この結果の技術的な理由は、デフォルトでは、各fingerprint列を暗号化するために異なる暗号キーを派生させるからです。このキーは、コラボレーションの共有シークレットキーと列名の組み合わせから派生します。列名の異なる 2 つの列を結合しようとすると、異なるキーが派生し、有効な結合を処理できません。 この問題に対処するには、各列名からキーを派生させる機能をオフにします。すると、C3R 暗号化クライアントはすべてのfingerprint列に 1 つの派生キーを使用します。リスクは、別の種類の頻度分析を行うと、情報が明らかになる可能性があることです。 もう一度 `City` と `State` の例を使ってみましょう。各fingerprint列で同じランダム値を派生させる (列名を組み込まない) 場合、`New York` では `City` 列と `State` 列のランダム値が同じになります。ニューヨークは、米国でも数少ない、`City` と `State` の名前が同じ都市の 1 つです。逆に、データセットの各列の値がまったく異なれば、情報が漏れることはありません。 このシナリオのパラメータの詳細については、「[[名前の異なる列の JOIN を許可] パラメータ](crypto-computing-parameters.md#parameter-allowjoin)」を参照してください。 ## NULL 値の表現方法を決定する 選択肢は、NULL 値を他の値と同様に暗号化処理 (暗号化と HMAC) するかどうかです。NULL 値を他の値と同様に処理しないと、情報が漏洩する可能性があります。 例えば、`Middle Name` 列のcleartextの NULL が、ミドルネームのない人を示しているとします。これらの値を暗号化しないと、暗号化されたテーブルのどの行がミドルネームを持たない人に使われているかが漏れてしまいます。そうした情報は、一部の集団の一部の人々にとっては、ある種の識別信号となる可能性があります。しかし、NULL 値を暗号化処理すると、特定の SQL クエリが異なる動作になります。例えば GROUP BY 句では、fingerprint列内のfingerprint NULL 値がまとめてグループ化されなくなります。 このシナリオのパラメータの詳細については、「[[NULL 値を保存] パラメータ](crypto-computing-parameters.md#parameter-preservenulls)」を参照してください。 # Cryptographic Computing for 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 エントリに対してカスタムエンコーディングを使用できます。 **注記** 特に SQL テーブルのようなよりリッチな表形式のコンテキストでは、NULL エントリは欠落したコンテンツとみなされます**。.csv は歴史的な理由からこの特性を明示的にサポートしていませんが、空白だけを含む空のエントリは NULL と見なすのが一般的な慣習です。したがって、これは C3R 暗号化クライアントのデフォルト動作であり、必要に応じてカスタマイズできます。 ### C3R による .csv エントリの解釈 次の表は、`--csvInputNULLValue=` および `--csvOutputNULLValue=` のフラグに指定された値 (存在する場合) に基づいて、.csv エントリを (わかりやすくするために cleartext から cleartext に) 整列化する方法の例を示しています。引用符の外側にある先頭と末尾の空白は、C3R が値の意味を解釈する前に削除されます。 | `` | `` | 入力エントリ | 出力エントリ | | --- |--- |--- |--- | | None | None | ,任意の製品, | ,任意の製品, | | None | None | , 任意の製品 , | ,任意の製品, | | None | None | ,"任意の製品", | ,任意の製品, | | None | None | , "任意の製品" , | ,任意の製品, | | None | None | ,, | ,, | | None | None | , , | ,, | | None | None | ,"", | ,, | | None | None | ," ", | ," ", | | None | None | , " " , | ," ", | | "任意の製品" | "NULL" | ,任意の製品, | ,NULL, | | "任意の製品" | "NULL" | , 任意の製品 , | ,NULL, | | "任意の製品" | "NULL" | ,"任意の製品", | ,NULL, | | "任意の製品" | "NULL" | , "任意の製品" , | ,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 暗号化クライアントでは、 AWS Clean Roomsでサポートされているデータ型を表す Parquet ファイル内の複雑でない (つまり、プリミティブ型の) データを処理できます。 ただし、sealed列には文字列の列しか使用できません。 以下の Parquet データ型 がサポートされています。 + 以下の論理アノテーション付きの `Binary` プリミティブ型 + `--parquetBinaryAsString` が設定されている場合は不要 (`STRING` データ型) + `Decimal(scale, precision)` (`DECIMAL` データ型) + `String` (`STRING` データ型) + 論理アノテーションのない `Boolean` プリミティブデータ型 (`BOOLEAN` データ型) + 論理アノテーションのない `Double` プリミティブデータ型 (`DOUBLE` データ型) + `Decimal(scale, precision)` 論理アノテーション付きの `Fixed_Len_Binary_Array` プリミティブ型 (`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 でエンコードされたテキストとして扱い、暗号化前にそれらを異なる方法で解釈しようとはしません。 フィンガープリント列では、データ型は等価クラスにグループ化されます。等価クラスは、代表的なデータ型を使用して同等かどうかを明確に比較できるデータ型のセットです。 等価クラスを使用すると、元の表現に関係なく、同一のフィンガープリントを同じセマンティック値に割り当てることができます。ただし、2 つの等価クラスで同じ値があっても、同じフィンガープリント列にはなりません。 例えば、`42` の `INTEGRAL` 値には、元の値が `SMALLINT`、`INT`、または `BIGINT` であったかどうかにかかわらず、同じフィンガープリントが割り当てられます。また、`0` の `INTEGRAL` 値が `FALSE` の `BOOLEAN` 値 (値 `0` で表される) と一致することはありません。 フィンガープリント列では、次の等価クラスと対応する AWS Clean Rooms データ型がサポートされています。 | 等価クラス | サポートされている AWS Clean Rooms データ型 | | --- | --- | | BOOLEAN | BOOLEAN | | DATE | DATE | | INTEGRAL | BIGINT, INT, SMALLINT | | STRING | CHAR, STRING, VARCHAR | # Cryptographic Computing for Clean Rooms での列名 デフォルトでは、Cryptographic Computing for Clean Rooms においては列の名前が重要になります。 **[名前の異なる列の JOIN を許可]** パラメータの値が **[false]** の場合は、fingerprint列の暗号化時に列名が使用されます。このためデフォルトでは、コラボレーターが事前に調整して、クエリで JOIN ステートメントを使用するデータで同じターゲット列名を使用する必要があります。デフォルトでは、JOIN のために暗号化された名前の異なる列は、どの値でも JOIN が正常に処理されません。 **[名前の異なる列の JOIN を許可]** パラメータの値が **[true]** の場合、fingerprint列として暗号化された複数の列にわたる JOIN ステートメントは成功します。このパラメータを使用してデータを暗号化すると、cleartext値をある程度推測できる可能性があります。例えば、ある行の `City` 列と `State` 列の両方に同じ Hash-based Message Authentication Code (HMAC) 値がある場合、その値は `New York` である可能性があります。 ## 列ヘッダー名の正規化 列ヘッダー名は C3R 暗号化クライアントによって正規化されます。変換後の出力では、先頭と末尾のスペースはすべて削除され、列名は小文字になります。 正規化は、列名の影響を受ける可能性のある他のすべての計算や操作の前に適用されます。出力されるファイルには、正規化された名前のみが含まれます。 # Cryptographic Computing for Clean Rooms での列タイプ このトピックでは、Cryptographic Computing for Clean Rooms での列タイプに関する情報を提供します。 **Topics** + [Fingerprint列](#fingerprint-columns) + [シール列](#sealed-columns) + [Cleartext列](#cleartext-columns) ## Fingerprint列 **Fingerprint列は、JOIN ステートメントで使用される、暗号化によって保護された列です。 fingerprint列のデータを復号化することはできません。復号化できるのは、シール列のデータだけです。 Fingerprint列は次の SQL 句と関数でのみ使用する必要があります。 + 他のfingerprint列に対する JOIN (INNER, OUTER, LEFT, RIGHT, or FULL) + `allowJoinsOnColumnsWithDifferentNames` パラメータの値が `false` に設定されている場合、JOIN の両方のfingerprint列が同じ名前であることも必要になります。 + `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` バイト) までエントリがパディングされることに注意してください。つまり、暗号文の長さはバッチごとに異なる可能性があります。したがって、列の最大バイト長がわかっている場合は、`max` の代わりに `fixed` 使用してください。 ## Cleartext列 *Cleartext 列*は、JOIN または SELECT ステートメントで使用される、暗号によって保護されていない列です。 Cleartext列は SQL クエリのどの部分でも使用できます。 # 暗号コンピューティングパラメータ 暗号コンピューティングパラメータは、[コラボレーションの作成](create-collaboration.md)時に、Cryptographic Computing for Clean Rooms (C3R) を使用してコラボレーションに指定できます。 AWS Clean Rooms コンソールまたは `CreateCollaboration` API オペレーションを使用してコラボレーションを作成できます。コンソールでは、**\$1暗号コンピューティングをサポート\$1** オプションをオンにすると、**[暗号コンピューティングパラメータ]** のパラメータ値を設定できます。詳細については、以下のトピックを参照してください。 **Topics** + [[cleartext 列を許可] パラメータ](#parameter-allowcleartext) + [[複製を許可] パラメータ](#parameter-allowduplicates) + [[名前の異なる列の JOIN を許可] パラメータ](#parameter-allowjoin) + [[NULL 値を保存] パラメータ](#parameter-preservenulls) ## [cleartext 列を許可] パラメータ コンソールでは、[コラボレーションの作成](create-collaboration.md)時に **[cleartext 列を許可]** パラメータを設定して、暗号化されたデータを含むテーブルで cleartext データを許可するかどうかを指定できます。 次の表で、**[cleartext 列を許可]** パラメータの値について説明します。 | パラメータ値 | 説明 | | --- | --- | | いいえ | 暗号化されたテーブルでCleartext 列を使用できません。すべてのデータは暗号で保護されます。 | | あり | 暗号化されたテーブルでCleartext 列を使用できます。 Cleartext 列は暗号化によって保護されず、cleartext として含まれます。行の cleartext データによって、テーブル内の他のデータについて明らかになるおそれがある情報をメモしておく必要があります。 特定の列で SUM または AVG を実行するには、その列が 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 列は、データの機密性が低い場合や、暗号化された sealed 列や fingerprint 列で許容される以上の柔軟性が必要な場合に役立ちます。 ## [複製を許可] パラメータ コンソールでは、[コラボレーションの作成](create-collaboration.md)時に **[複製を許可]** パラメータを設定して、暗号化された列の JOIN クエリで NULL 値以外の重複する値を含めるかどうかを指定できます。 **重要** **[複製を許可]**、**[[名前の異なる列の JOIN を許可](#parameter-allowjoin)]**、**[[NULL 値を保存](#parameter-preservenulls)]** の各パラメータには、別々でありながら関連する効果があります。 次の表で、**[複製を許可]** パラメータの値について説明します。 | パラメータ値 | 説明 | | --- | --- | | いいえ | 1 つの fingerprint 列で値の繰り返しは許可されません。1 つの fingerprint 列の値は、すべて一意でなければなりません。 | | あり | 1 つの 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 を許可]** パラメータの値について説明します。 | パラメータ値 | 説明 | | --- | --- | | いいえ | 名前の異なる fingerprint 列の結合はサポートされません。JOIN ステートメントでは、同じ名前の列でのみ正確な結果が得られます。 **[いいえ]** を指定すると情報セキュリティは強化されますが、列名について事前にコラボレーション参加者の合意が必要になります。fingerprint列として暗号化したときに 2 つの列の名前が異なり、**[名前の異なる列の JOIN を許可]** が **[いいえ]** に設定されていると、それらの列の JOIN ステートメントは結果を生成しません。これは、暗号化後の値が 2 つの列の間で共有されないためです。 | | あり | 名前の異なる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 列の暗号化は、「[ステップ 4: 表形式ファイルの暗号化スキーマを生成する](gen-encryption-schema-csv.md)」で設定されたその列の `targetHeader` 設定の影響を受けます。そのため、同じ cleartext 値でも、暗号化対象の fingerprint 列ごとに暗号化表現は異なります。 このパラメータは、cleartext 値が推測されるのを防ぐのに役立つ場合があります。例えば、fingerprint 列 `City` と `State` に暗号化された同一の値が表示されている場合、その値は `New York` であると合理的に推測できます。ただし、このパラメータを使用するには、クエリで結合されるすべての列が共通の名前になるように、事前に追加の調整が必要になります。 **[名前の異なる列の JOIN を許可]** パラメータを使用すると、この制限を緩和できます。パラメータ値を `Yes` に設定すると、名前に関係なく、暗号化されたすべての列を JOIN で一緒に使用できます。 ## [NULL 値を保存] パラメータ コンソールでは、[コラボレーションの作成](create-collaboration.md)時に **[NULL 値を保存]** パラメータを設定して、その列に値がないことを示すことができます。 次の表で、**[NULL 値を保存]** パラメータの値について説明します。 | パラメータ値 | 説明 | | --- | --- | | いいえ | 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. `cleartext` 列の NULL エントリは変更されません。 1. 暗号化された`fingerprint` 列の NULL エントリは、内容を隠すためにランダムな値として暗号化されます。暗号化された列をそのcleartext列の NULL エントリと結合しても、どの NULL エントリとも一致しません。それぞれが一意のランダムコンテンツを受け取るため、一致は生じません。 1. 暗号化された`sealed` 列の NULL エントリは暗号化されます。 コラボレーションの **[NULL 値を保存]** パラメータ値が **[はい]** に設定されている場合、列が暗号化されているかどうかに関係なく、すべての列の NULL エントリは NULL のままとなります。 **[NULL 値を保存]** パラメータは、データエンリッチメントなどのシナリオにおいて、情報が欠落し、NULL で表されているエントリを共有する場合に便利です。また、**[NULL 値を保存]** パラメータは、JOIN または GROUP BY を実行する列に NULL がある場合に、fingerprint または HMAC 形式でも役立ちます。 **[複製を許可]** パラメータと **[NULL 値を保存]** パラメータの値が **[いいえ]** に設定されている場合、1 つのfingerprint 列に複数の NULL エントリがあると、エラーが発生して暗号化が停止します。いずれかのパラメータ値が **[はい]** に設定されていれば、そのようなエラーは発生しません。 # Cryptographic Computing for 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 エントリにカスタムエンコーディングを指定できます。 次の表は、このフラグの使用方法とパラメータをまとめたものです。 | 使用方法 | パラメータ | | --- | --- | | オプション。ユーザーは入力データの NULL エントリにカスタムエンコーディングを指定できます。 | 入力 CSV ファイルの NULL 値に対するユーザー指定のエンコーディング | NULL エントリとは、特に SQL テーブルのようなよりリッチな表形式のコンテキストでは、欠落したコンテンツとみなされるエントリです。.csv は歴史的な理由からこの特性を明示的にサポートしていませんが、空白だけを含む空のエントリは NULL と見なすのが一般的な慣習です。したがって、これは C3R 暗号化クライアントのデフォルト動作であり、必要に応じてカスタマイズできます。 ## `--csvOutputNULLValue` フラグ C3R 暗号化クライアントを使用して[データを暗号化](encrypt-data.md)するときに、`--csvOutputNULLValue` フラグを使用して出力データの NULL エントリにカスタムエンコーディングを指定できます。 次の表は、このフラグの使用方法とパラメータをまとめたものです。 | 使用方法 | パラメータ | | --- | --- | | オプション。ユーザーは、NULL エントリの生成された出力ファイルにカスタムエンコーディングを指定できます。 | 出力 CSV ファイルの NULL 値に対するユーザー指定のエンコーディング | NULL エントリとは、特に SQL テーブルのようなよりリッチな表形式のコンテキストでは、欠落したコンテンツとみなされるエントリです。.csv は歴史的な理由からこの特性を明示的にサポートしていませんが、空白だけを含む空のエントリは NULL と見なすのが一般的な慣習です。したがって、これは C3R 暗号化クライアントのデフォルト動作であり、必要に応じてカスタマイズできます。 ## `--enableStackTraces` フラグ C3R 暗号化クライアントを使用して[データを暗号化](encrypt-data.md)するときに `--enableStackTraces` フラグを使用すると、C3R でエラーが発生したときに、エラー報告用の追加のコンテキスト情報が提供されます。 AWS はエラーを収集しません。エラーが発生した場合は、スタックトレースを使用してエラーを自分でトラブルシューティングするか、スタックトレースを に送信してサポート サポート を依頼してください。 次の表は、このフラグの使用方法とパラメータをまとめたものです。 | 使用方法 | パラメータ | | --- | --- | | オプション。C3R 暗号化クライアントでエラーが発生したときに、エラー報告用の追加のコンテキスト情報を提供するために使用します。 | なし | ## `--dryRun` フラグ C3R 暗号化クライアントの[暗号化](encrypt-data.md)コマンドと[復号化](decrypt-data.md)コマンドにはオプションの `--dryRun` フラグがあります。このフラグは、ユーザーが指定した引数をすべて受け取り、その有効性と一貫性をチェックします。 この `--dryRun` フラグを使用して、スキーマファイルが有効で対応する入力ファイルと一致しているかどうかを確認できます。 次の表は、このフラグの使用方法とパラメータをまとめたものです。 | 使用方法 | パラメータ | | --- | --- | | オプション。C3R 暗号化クライアントはパラメータの解析とファイルのチェックを行いますが、暗号化や復号化は行いません。 | なし | ## `--tempDir` フラグ 設定によっては、暗号化されたファイルは暗号化されていないファイルよりもサイズが大きくなることがあるため、一時ディレクトリを使用することができます。また、データセットを正常に機能させるには、コラボレーションごとに暗号化する必要があります。 C3R を使用して[データを暗号化](encrypt-data.md)する場合は、`--tempDir` フラグを使用して、入力の処理中に一時ファイルを作成する場所を指定できます。 次の表は、このフラグの使用方法とパラメータをまとめたものです。 | 使用方法 | パラメータ | | --- | --- | | ユーザーは、入力の処理中に一時ファイルを作成する場所を指定できます。 | デフォルトはシステム一時ディレクトリです。 | # クエリと Cryptographic Computing for Clean Rooms このトピックでは、Cryptographic Computing for Clean Rooms で暗号化されたデータテーブルを使用するクエリの作成について情報を提供します。 **Topics** + [NULL で分岐するクエリ](#queries-branch-on-null) + [1 つのソース列を複数のターゲット列にマッピングする](#queries-mapping) + [JOIN クエリと SELECT クエリの両方に同じデータを使用する](#queries-using-same-data) ## NULL で分岐するクエリ NULL ステートメントでクエリを分岐するということは、`IF x IS NULL THEN 0 ELSE 1` のような構文を使用することを意味します。 cleartext列では、NULL ステートメントで常にクエリを分岐させることができます。 sealed列やfingerprint列の場合は、**[NULL 値を保存]** パラメータ (`preserveNulls`) の値が `true` に設定されている場合のみ、NULL ステートメントでクエリを分岐させることができます。 これらの制約に違反するクエリは、誤った結果をもたらす可能性があります。 ## 1 つのソース列を複数のターゲット列にマッピングする 1 つのソース列を複数のターゲット列にマッピングできます。例えば、1 つの列で JOIN と SELECT の両方を実行することができます。 詳細については、「[JOIN クエリと SELECT クエリの両方に同じデータを使用する](#queries-using-same-data)」を参照してください。 ## JOIN クエリと SELECT クエリの両方に同じデータを使用する 列内のデータが機密情報ではない場合、そのデータはcleartextのターゲット列に表示され、あらゆる目的に使用できます。 列内のデータが機密情報で、JOIN クエリと SELECT クエリの両方に使用する必要がある場合は、そのソース列を出力ファイルの 2 つのターゲット列にマッピングします。1 つの列は `type` をfingerprint列として暗号化し、もう 1 つの列は `type` をシール列として暗号化します。C3R 暗号化クライアントのインタラクティブなスキーマ生成では、ヘッダーサフィックスとして `_fingerprint` と `_sealed` が提示されます。これらのヘッダーサフィックスは、このような列をすばやく区別するのに便利な規則です。 # C3R 暗号化クライアントのガイドライン C3R 暗号化クライアントは、組織が機密データをまとめてデータ分析から新しいインサイトを引き出すために使用するツールです。このツールは、任意の当事者およびプロセス AWS で学習できる内容を暗号的に制限します。これはきわめて重要ですが、データを暗号化によって保護するプロセスでは、コンピューティングリソースとストレージリソースの両面で大きなオーバーヘッドが生じる可能性があります。そのため、各設定を使用する際のトレードオフや、必要な暗号化保証を維持しながら最適な設定を行う方法を理解することが重要です。このトピックでは、C3R 暗号化クライアントとスキーマのさまざまな設定がパフォーマンスに与える影響に焦点を当てています。 C3R 暗号化クライアントの暗号化設定はすべて、異なる暗号化保証を提供します。コラボレーションレベルの設定が、デフォルトでは最も安全です。コラボレーションの作成中に追加機能を有効にすると、暗号文で頻度分析などのアクティビティを実行できるようになり、プライバシーの保証が弱まります。これらの設定がどのように使用され、どのような影響を及ぼすかの詳細については、「[Cryptographic Computing for Clean Rooms](crypto-computing.md)」を参照してください。 **Topics** + [列タイプがパフォーマンスに与える影響](#performance-implications) + [暗号文のサイズが予期せず大きくなった場合のトラブルシューティング](#troubleshooting-ciphertext-size) ## 列タイプがパフォーマンスに与える影響 C3R ではcleartext、fingerprint、sealedの 3 つの列タイプを使用します。これらの列タイプはそれぞれ異なる暗号化保証を提供し、使用目的も異なります。以下のセクションでは、列タイプがパフォーマンスに与える影響と、各設定がパフォーマンスに与える影響について説明します。 **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列内のデータは、Hash-based Message Authentication Code (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/ja_jp/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` などの他のコラボレーションレベルの設定は結果に影響せず、ローカルで再現を試みる場合は `true` または `false` に設定できます。 **共有シークレットの例**: `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` **コラボレーション ID の例**: `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111` **allowJoinsOnColumnsWithDifferentNames**: `True`。この設定はパフォーマンスやストレージ要件には影響しません。ただし、この設定を行うと、次の表に示す値を再現するときに、列名の選択は重要ではなくなります。 **例 1** | | | | --- |--- | | Input | null | | preserveNulls | TRUE | | Output | null | | 確定的 | Yes | | 入力バイト数 | 0 | | 出力バイト数 | 0 | **例 2** | | | | --- |--- | | Input | null | | preserveNulls | FALSE | | Output | 01:hmac:3lkFjthvV3IUu6mMvFc1a\$1XAHwgw/ElmOq4p3Yg25kk= | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 52 | **例 3** | | | | --- |--- | | Input | empty string | | preserveNulls | - | | Output | 01:hmac:oKTgi3Gba\$1eUb3JteSz2EMgXUkF1WgM77UP0Ydw5kPQ= | | 確定的 | Yes | | 入力バイト数 | 0 | | 出力バイト数 | 52 | **例 4** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:hmac:kU/IqwG7FMmzzshr0B9scomE0UJUEE7j9keTctplGww= | | 確定的 | Yes | | 入力バイト数 | 26 | | 出力バイト数 | 52 | **例 5** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:hmac:ks3htnQbw2vdhCRFF6JNzW5LMndJaHG57uvE26mBtSs= | | 確定的 | Yes | | 入力バイト数 | 62 | | 出力バイト数 | 52 | #### fingerprint列のトラブルシューティング **fingerprint列の暗号文が、入力されたcleartextのサイズより数倍大きいのはなぜですか?** fingerprint列の暗号文の長さは常に 52 バイトです。入力データが小さい場合 (顧客の年齢など) は、サイズが大幅に増加します。この現象は、`preserveNulls` 設定が `false` に設定されている場合にも発生する可能性があります。 **fingerprint列の暗号文が、入力されたcleartextのサイズより数倍小さいのはなぜですか?** fingerprint列の暗号文の長さは常に 52 バイトです。入力データが大きい場合 (顧客の完全な住所など) は、サイズが大幅に減少します。 **`preserveNulls` による暗号保証が必要かどうかはどうすればわかりますか?** 答えは状況により異なります。少なくとも、`preserveNulls` 設定によってデータがどのように保護されるかを「[暗号コンピューティングパラメータ](crypto-computing-parameters.md)」で確認する必要があります。ただし、組織のデータ処理要件と、それぞれのコラボレーションに適用される契約を参照することをお勧めします。 **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 に設定されている場合は、null 値以外の合計数を使用します)。 以下の図は、* `BASE_OVERHEAD = C3R_DESIGNATION + ((NONCE + IV + DATA_TYPE + PAD_SIZE + AUTH_TAG) * 1.33)` * を表しています。 ![\[sealed列の 91 バイトの基本オーバーヘッド。\]](http://docs.aws.amazon.com/ja_jp/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` のパディングタイプを選択すると、列に含まれるデータの長さが隠蔽され、プライバシーを保護する手段となります。これは、暗号化の前に、すべてのcleartextを指定された `pad_length` にパディングすることで行われます。このサイズを超えるデータがあると、C3R 暗号化クライアントは機能しなくなります。 暗号化の前にcleartextにパディングが追加される場合、AES-GCM で、cleartextと暗号文のバイトとの 1 対 1 のマッピングが行われます。base64 エンコーディングによってサイズが 33% 増加します。パディングによって増加するストレージのオーバーヘッドは、`pad_length` の値からcleartextの長さの平均値を引き、1.33 を掛けることで算出できます。その結果が、レコードごとのパディングの平均オーバーヘッドになります。次に、この結果に行の数を掛けて、パディングのオーバーヘッドの合計を求めます (`preserveNulls` が `true` に設定されている場合は、`null` 値以外の合計数を使用します)。 `PADDING_OVERHEAD = (PAD_LENGTH - AVG_CLEARTEXT_LENGTH) * 1.33 * ROW_COUNT` `pad_length` の最小値には、列内の最大値が収まる値を選択することをお勧めします。例えば、最大値が 50 バイトの場合は、50 バイトの `pad_length` で十分です。これより大きい値では、ストレージのオーバーヘッドが増えるだけです。 固定長のパディングでは、コンピューティングのオーバーヘッドは大幅に増加しません。 ##### パディングタイプ `max` `max` のパディングタイプを選択すると、列に含まれるデータの長さが隠蔽され、プライバシーを保護する手段となります。これは、暗号化の前に、すべての cleartext を列内の最大値に追加の `pad_length` を加算した値までパディングすることで行われます。一般に、`max` のパディングは 1 つのデータセットに対して `fixed` のパディングと同様の保証を提供しますが、列内のcleartextの最大値を把握していなくてもかまいません。ただし、更新時には、個々のデータセットの最大値が変わる場合があるため、`max` のパディングで `fixed` のパディングと同様のプライバシー保証が提供されるとは限りません。 `max` のパディングを使用するときは、0 の `pad_length` を追加で選択することをお勧めします。この長さにより、すべての値が列の最大値と同じサイズにパディングされます。これより大きい値では、ストレージのオーバーヘッドが増えるだけです。 特定の列の cleartext の最大値がわかっている場合は、代わりに `fixed` のパディングタイプを使用することをお勧めします。`fixed` のパディングを使用すると、データセットの更新前後で一貫性が保たれます。`max` のパディングを使用すると、データの各サブセットが、そのサブセットにあった最大値までパディングされます。 #### sealed列のデータ例 以下は、再現可能な設定を含む sealed 列の入出力データのサンプルセットです。`allowCleartext`、`allowJoinsOnColumnsWithDifferentNames`、`allowDuplicates` などの他のコラボレーションレベルの設定は結果に影響せず、ローカルで再現を試みる場合は `true` または `false` に設定できます。これらは再現するための基本設定ですが、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** | | | | --- |--- | | Input | null | | preserveNulls | TRUE | | Output | null | | 確定的 | Yes | | 入力バイト数 | 0 | | 出力バイト数 | 0 | **例 2** | | | | --- |--- | | Input | null | | preserveNulls | FALSE | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSPbNIJfG3iXmu6cbCUrizuV | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 91 | **例 3** | | | | --- |--- | | Input | empty string | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSPEM6qR8DWC2PB2GMlX41YK | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 91 | **例 4** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9sGL5VLDQeHzh6DmPpyWNuI= | | 確定的 | No | | 入力バイト数 | 26 | | 出力バイト数 | 127 | **例 5** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnnohrHIGSX54ua\$11/JfcVjc= | | 確定的 | No | | 入力バイト数 | 62 | | 出力バイト数 | 175 | ##### パディングタイプ `fixed` (例 1) この例では、`pad_length` は 62 で最大入力値は 62 バイトです。 **例 1** | | | | --- |--- | | Input | null | | preserveNulls | TRUE | | Output | null | | 確定的 | Yes | | 入力バイト数 | 0 | | 出力バイト数 | 0 | **例 2** | | | | --- |--- | | Input | null | | preserveNulls | FALSE | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoNpATs0GzbnLkor4L\$1/aSuA= | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 175 | **例 3** | | | | --- |--- | | Input | empty string | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoLB53l07VZpA6OwkuXu29CA= | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 175 | **例 4** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcutBAcO\$1Mb9tuU2KIHH31AWg= | | 確定的 | No | | 入力バイト数 | 26 | | 出力バイト数 | 175 | **例 5** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnnohrHIGSX54ua\$11/JfcVjc= | | 確定的 | No | | 入力バイト数 | 62 | | 出力バイト数 | 175 | ##### パディングタイプ `fixed` (例 2) この例では、`pad_length` は 162 で最大入力値は 62 バイトです。 **例 1** | | | | --- |--- | | Input | null | | preserveNulls | TRUE | | Output | null | | 確定的 | Yes | | 入力バイト数 | 0 | | 出力バイト数 | 0 | **例 2** | | | | --- |--- | | Input | null | | preserveNulls | FALSE | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv/xAySX\$1xcntotL703aBTBb | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 307 | **例 3** | | | | --- |--- | | Input | empty string | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv84lVaT9Yd\$16oQx65/\$1gdVT | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 307 | **例 4** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwtX5Hnl\$1WyfO6ks3QMaRDGSf | | 確定的 | No | | 入力バイト数 | 26 | | 出力バイト数 | 307 | **例 5** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwjkJXQZOgPdeFX9Yr/8alV5i | | 確定的 | No | | 入力バイト数 | 62 | | 出力バイト数 | 307 | ##### パディングタイプ `max` (例 1) この例では、`pad_length` は 0 で最大入力値は 62 バイトです。 **例 1** | | | | --- |--- | | Input | null | | preserveNulls | TRUE | | Output | null | | 確定的 | Yes | | 入力バイト数 | 0 | | 出力バイト数 | 0 | **例 2** | | | | --- |--- | | Input | null | | preserveNulls | FALSE | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoNpATs0GzbnLkor4L\$1/aSuA= | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 175 | **例 3** | | | | --- |--- | | Input | empty string | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoLB53l07VZpA6OwkuXu29CA= | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 175 | **例 4** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcutBAcO\$1Mb9tuU2KIHH31AWg= | | 確定的 | No | | 入力バイト数 | 26 | | 出力バイト数 | 175 | **例 5** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnnohrHIGSX54ua\$11/JfcVjc= | | 確定的 | No | | 入力バイト数 | 62 | | 出力バイト数 | 175 | ##### パディングタイプ `max` (例 2) この例では、`pad_length` は 100 で最大入力値は 62 バイトです。 **例 1** | | | | --- |--- | | Input | null | | preserveNulls | TRUE | | Output | null | | 確定的 | Yes | | 入力バイト数 | 0 | | 出力バイト数 | 0 | **例 2** | | | | --- |--- | | Input | null | | preserveNulls | FALSE | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv/xAySX\$1xcntotL703aBTBb | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 307 | **例 3** | | | | --- |--- | | Input | empty string | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv84lVaT9Yd\$16oQx65/\$1gdVT | | 確定的 | No | | 入力バイト数 | 0 | | 出力バイト数 | 307 | **例 4** | | | | --- |--- | | Input | abcdefghijklmnopqrstuvwxyz | | preserveNulls | - | | Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwtX5Hnl\$1WyfO6ks3QMaRDGSf | | 確定的 | No | | 入力バイト数 | 26 | | 出力バイト数 | 307 | **例 5** | | | | --- |--- | | Input | 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` のパディングを使用するときは、`pad_length` (列の最大値を超える追加パディングとも呼ばれます**) を 0 に設定することをお勧めします。 **`fixed` のパディングを使用するときに、最大値が確実に収まるよう `pad_length` に大きい値を選択してもよいですか？** はい。ただし、パディングの長さが長いと効率が低下し、必要以上に多くのストレージを消費します。最大値の大きさを確認し、`pad_length` にその値を設定することをおすすめします。 **`preserveNulls` による暗号保証が必要かどうかはどうすればわかりますか?** 答えは状況により異なります。少なくとも、`preserveNulls` 設定によってデータがどのように保護されるかを「[Cryptographic Computing for Clean Rooms](crypto-computing.md)」で確認する必要があります。ただし、組織のデータ処理要件と、それぞれのコラボレーションに適用される契約を参照することをお勧めします。 **base64 のオーバーヘッドが発生するのはなぜですか?** CSV などの表形式のファイル形式との互換性を保つには、base64 エンコーディングが必要です。Parquet などの一部のファイル形式はデータのバイナリ表現をサポートしていますが、適切なクエリ結果を得るためには、コラボレーションのすべての参加者が同じ方法でデータを表現することが重要です。 ## 暗号文のサイズが予期せず大きくなった場合のトラブルシューティング データを暗号化し、生成されたデータのサイズが驚くほど大きかったとしましょう。次の手順は、サイズが増加している場所と、実行できるアクション (ある場合) を特定するのに役立ちます。 ### サイズの増加が発生した場所の特定 暗号化されたデータが cleartext データよりも大幅に大きくなった理由をトラブルシューティングする前に、まずサイズが増加している場所を特定する必要があります。Cleartext 列は変更されていないため、無視しても問題ありません。残りの fingerprint 列と sealed 列を見て、大幅に増えている列を 1 つ選びます。 ### サイズが増加した理由の特定 fingerprint 列または sealed 列がサイズ増加の原因となっている可能性があります。 **Topics** + [fingerprint列が原因でサイズの増加が生じている場合](#size-increase-from-fingerprint) + [sealed 列が原因でサイズの増加が生じている場合](#size-increase-from-sealed) #### fingerprint列が原因でサイズの増加が生じている場合 ストレージ増加の最も大きな原因となっているのがfingerprint列である場合は、cleartextデータが小さいこと (顧客の年齢など) が要因と考えられます。生成される各fingerprint暗号文の長さは 52 バイトになります。残念ながら、この問題について列単位で対処できることは何もありません。ストレージ要件への影響など、この列の詳細については「[fingerprint列の基本オーバーヘッド](#fingerprint-columns-base-overhead)」を参照してください。 fingerprint列のサイズが大きくなるもう 1 つの原因として、`preserveNulls` のコラボレーション設定が考えられます。`preserveNulls` のコラボレーション設定が無効 (デフォルト設定) になっていると、fingerprint 列の `null` 値はすべて 52 バイトの暗号文になります。現在のコラボレーションでは、これに対してできることは何もありません。`preserveNulls` 設定はコラボレーションの作成時に設定され、正しいクエリ結果を得るためにすべてのコラボレーターが同じ設定を使用する必要があります。`preserveNulls` 設定の詳細と、この設定を有効にした場合にデータのプライバシー保護にどのような影響が及ぶかについては、「[Cryptographic Computing for Clean Rooms](crypto-computing.md)」を参照してください。 #### sealed 列が原因でサイズの増加が生じている場合 ストレージ増加の最も大きな原因となっているのが sealed 列である場合、サイズの増加を引き起こしている可能性のある要因がいくつかあります。 cleartext データが小さい場合 (顧客の年齢など)、生成される各 sealed 暗号文の長さは 91 バイト以上になります。残念ながら、この問題についてできることは何もありません。ストレージ要件への影響など、この列の詳細については「[sealed列の基本オーバーヘッド](#sealed-columns-base-overhead)」を参照してください。 sealed列でストレージが増加する 2 つ目の主な要因はパディングです。パディングとは、データセット内の個々の値のサイズを隠蔽するために、暗号化の前にcleartextに余分なバイトを追加することです。データセットにとって最小限の値でパディングを設定することをお勧めします。少なくとも、`fixed` パディングの `pad_length` は、列内で考えられる最大の値が収まるように設定する必要があります。これより大きい値を設定しても、プライバシー保証は追加されません。例えば、列内で考えられる最大の値が 50 バイトであることがわかっている場合は、`pad_length` を 50 バイトに設定することをお勧めします。ただし、sealed 列で `max` のパディングを使用している場合は、`pad_length` を 0 バイトに設定することをお勧めします。これは、`max` のパディングが、列内の最大値を超える追加のパディングを指すためです**。 sealed列のサイズが大きくなる原因として考えられる最後の要因は、`preserveNulls` のコラボレーション設定です。`preserveNulls` のコラボレーション設定が無効 (デフォルト設定) になっていると、sealed 列の `null` 値はすべて 91 バイトの暗号文になります。現在のコラボレーションでは、これに対してできることは何もありません。`preserveNulls` 設定はコラボレーションの作成時に設定され、正しいクエリ結果を得るためにすべてのコラボレーターが同じ設定を使用する必要があります。この設定の詳細と、設定を有効にした場合にデータのプライバシー保護にどのような影響が及ぶかについては、「[Cryptographic Computing for Clean Rooms](crypto-computing.md)」を参照してください。