Snowflake integration guide
Snowflake は、パートナーがデータを保存し、UID2 フレームワークとインテグレーションできるクラウドデータウェアハウジングソリューションです。Snowflake を使用することで、UID2 は、機密性の高い 直接識別情報 (DII) を公開することなく、消費者識別子データを安全に共有できます。Operator Web Service を直接クエリして消費者識別子データを取得するオプションもありますが、Snowflake UID2 インテグレーションはよりシームレスなエクスペリエンスを提供します。
このドキュメントは、最新の Snowflake marketplace listing を使用している方を 対象としています。以前のバージョンを使用している場合は、Snowflake integration guide (pre-July 2025) を参照してください。以前の実装を使用している場合は、更新と強化を利用するために新しいバージョンへの移行を推奨します。詳細は、Changes from previous version を参照してください。移行情報は、Migration guide を参照してください。
Snowflake marketplace listing
以下の UID2 リスティングは、Snowflake Marketplace で利用できます:
インテグレーションオプションとステップの概要は、Advertiser/data provider integration overview を参照してください。
Functionality
以下の表は、UID2 Snowflake インテグレーションで利用可能な機能をまとめたものです。
| Encrypt Raw UID2 to UID2 Token for Sharing | Decrypt UID2 Token to Raw UID2 | Generate UID2 Token from DII | Refresh UID2 Token | Map DII to Raw UID2s |
|---|---|---|---|---|
| ✅ | ✅ | —* | — | ✅ |
*Snowflake を使用して、DII から直接 UID2 Token を生成することはできません。ただし、DII を raw UID2 に変換し、その後 raw UID2 を UID2 Token に暗号化することはできます。
パブリッシャーで、bidstream で UID2 Token を共有している場合は、Tokenized sharing in the bidstream を参照してください。
Changes from previous version
2025 年 7 月の UID2 Snowflake Marketplace インテグレーションの更新では、UID2 のリフレッシュ管理を簡素化し、ローテーション後 90 日間の以前の raw UID2 にアクセスできる新しい ID マッピング関数が導入されました。
これらの変更は、コードインテグレーションが 2025 年 7 月以前に公開された Snowflake 関数のバージョンを使用していることを前 提としています: Snowflake integration guide (pre-July 2025) を参照してください。このバージョンへの移行の詳細は、Migration guide を参照してください。
以下の表は、旧バージョンと新バージョンの ID マッピング関数の違いを示しています。
| Function | Version | Return Fields | Key Differences | Comments |
|---|---|---|---|---|
FN_T_IDENTITY_MAP | 以前のバージョン | UID, BUCKET_ID, UNMAPPED | 基本的な ID マッピングとソルトバケットの追跡 | ソルトバケット監視を使用したレガシー関数。詳細は、Snowflake integration guide (pre-July 2025) を参照してください。 |
FN_T_IDENTITY_MAP_V3 | 現在 | UID, PREV_UID, REFRESH_FROM, UNMAPPED | 強化された以前の UID2 アクセスとリフレッシュタイムスタンプ | ローテーション後 90 日間の以前の UID2 を返し、ソルトバケット監視の代わりにリフレッシュタイムスタンプを使用します。詳細は、Map DII を参照してください。 |
Key benefits
このアップデートにより、以下の 2 つの主要な利点が提供されます:
- Simplified Refresh Management:
REFRESH_FROMタイムスタンプに達した UID2 を監視できるようになり、ローテーションのために Salt Bucket をポーリングする必要がなくなります。 - Previous UID2 Access: ローテーション後 90 日間、以前の raw UID2 にアクセスできるようになり、キャンペーンの測定が可能になります。
Workflow diagram
以下の図は、Snowflake における UID2 インテグレーションプロセスの異なる部分とワークフローを示しています。
| Partner Snowflake Account | UID2 Snowflake Account | UID2 Core Opt-Out Cloud Setup |
|---|---|---|
| パートナーとして、データをホストし、UID2 インテグレーションに参加するための Snowflake アカウントをセットアップします。UID2 Share を通じて関数とビューを消費します。 | UID2 インテグレーションは、Snowflake アカウントでホストされ、UID2 関連のタスクを実行するために必要なデータのみを引き出す認可された関数とビューへのアクセスを提供します。プライベートテーブルにはアクセスできません。UID2 Share は、UID2 関連のタスクを実行するために必要な基本的なデータのみを公開します。 Note: ソルト と暗号化キーはプライベートテーブルに保存されています。DII はどの時点でも保存されません。 | ETL (Extract Transform Load) ジョブは、UID2 Core/Optout Snowflake ストレージを常に更新し、UID2 Operator Web Service を動かす内部データを提供します。Operator Web Service で使用されるデータは、UID2 Share を通じても利用可能です。 |
| 共有関数とビューを使用すると、トランザクションコンピューティングコストを Snowflake に支払います。 | これらのプライベートテーブルは、UID2 Snowflake アカウントで保護され、UID2 関連のタスクを完了するために使用される内部データを保持する UID2 Core/Optout Snowflake ストレージと自動的に同期します。 |
Preparing DII for processing
UID2 に変換する入力データが許容可能な形式であることは非常に重要です。そうでない場合、期待される結果は得られません。たとえば、Phone number normalization で説明されているように、電話番号には国コードを含めるように正規化する必要があります。
詳細は、Preparing emails and phone numbers for processing を参照してください。
フルトークン生成パイプラインをエンドツーエンドで検証し、正規化・ハッシュ化・エンコードされた値から生成されたトークンが正確であることを確認するためには、［UID2 Token Validator］（../ref-info/ref-token-validator.md）を使用してください。
Summary of integration steps
データのリクエストを行うには、ACCOUNTADMIN ロールまたは Snowflake アカウントで CREATE DATABASE および IMPORT SHARE 権限を持つ他のロールを使用する必要があります。
以下のリストは、本番環境での Snowflake における UID2 マッピングのインテグレーション手順をまとめたものです:
本番環境を使用する前にインテグレーションを試してみたい場合は、Testing in the integ environmentを参照してください。
-
UID2 POC が UID2 担当者によって署名されていることを確認してください。担当者がわからない場合は、Contact infoを参照してください。
-
UID2 Share へのアクセスをリクエストします:
-
Snowflake marketplace listing でアクセスをリクエストします。リクエストには、Snowflake アカウント番号とリージョンを含めてください。
-
UID2 担当者にアクセスをリクエストしたことを伝えてください。
-
-
UID2 担当者が、UID2 mapping share へのアクセスをあなたの Snowflake アカウントにプロビジョニングします。
初期のテストを行った場合（Testing in the integ environmentを参照）、関数を本番の UID2 Share に更新し、関連するテーブル名も更新してください。
Testing in the integ environment
UID2 POC に署名する前に mapping share をテストしたい場合は、UID2 担当者に integ (インテグレーション) 環境の Snowflake シェアへのアクセスをリクエストできます。この環境はテスト専用であり、本番データはありません。リクエストには、アカウント番号とリージョンを必ず含めてください。
このシナリオでは、以下の手順が実行されます:
-
UID2 担当者が Snowflake プライベートマーケットプレイスにシェアリスティングをプロビジョニングし、このステップが完了したら知らせます。
-
その後、プライベートマーケットプレイスのリスティングを表示し、integ シェアへのアクセスをリクエストできます。
-
アクセスをリクエストすると、UID2 担当者が integ シェアをあなたのアカウントにプロビジョニングします。
Shared objects
DII を UID2 にマッピングするには、以下の関数を使用します:
FN_T_IDENTITY_MAP_V3(詳細はMap DIIを参照してください)
以下の関数は FN_T_IDENTITY_MAP_V3 に置き換えられ、非推奨となっています。以前の Snowflake バージョンを使用している場合は引き続き使用できますが、できるだけ早くアップグレードすることをお勧めします（詳細は Snowflake integration guide (pre-July 2025) を参照してください）:
FN_T_IDENTITY_MAP(deprecated)
非推奨の関数を使用していて、新しい関数への移行につい てのヘルプが必要な場合は、Migration guideを参照してください。
再生成が必要な UID2 を特定するには、FN_T_IDENTITY_MAP_V3 関数から返される REFRESH_FROM タイムスタンプを監視します。詳細は Monitor raw UID2 refresh and regenerate raw UID2s を参照してください。
以下の関数は、UID2 Share 参加者向けに利用可能です:
FN_T_ENCRYPT(See Encrypt tokens)FN_T_DECRYPT(See Decrypt tokens)
詳細は、Usage for UID2 sharersを参照してください。
Database and schema names
以下のセクションは、各ソリューションのクエリ例を含みます。これらは、データベース名とスキーマ名の変数を除いて同一です:
{DATABASE_NAME}.{SCHEMA_NAME}
例:
select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP_V3('validate@example.com', 'email'));
すべてのクエリ例は、各名前変数に対して以下のデフォルト値を使用します:
| Variable | Default Value | Comments |
|---|---|---|
{DATABASE_NAME} | UID2_PROD_UID_SH | 必要に応じて、選択した UID2 Share へのアクセスが付与された後に新しいデータベースを作成する際に、デフォルトのデータベース名を変更できます。 |
{SCHEMA_NAME} | UID | これは変更できません。 |
Map DII
すべての種類の DII をマッピングするには、FN_T_IDENTITY_MAP_V3 関数を使用します。
DII がメールアドレスの場合、サービスは UID2 Email address normalization ルールを使用してデータを正規化します。
DII が電話番号の場合、UID2 Phone number normalization ルールを使用して、サービスに送信する前に正規化する必要があります。
| Argument | Data Type | Description |
|---|---|---|
INPUT | varchar(256) | UID2 にマップする DII、リフレッシュ タイムスタンプ、およびローテーション後 90 日間の前の UID2。 |
INPUT_TYPE | varchar(256) | マップする DII のタイプ。許可される値: email、email_hash、phone、 phone_hash。 |
指定した DII に対して、成功したクエリは以下の情報を返します。
| Column Name | Data Type | Description |
|---|---|---|
UID | TEXT | 値は次のいずれかです:
|
PREV_UID | TEXT | 値は次のいずれかです:
|
REFRESH_FROM | NUMBER | 値は次のいずれかです:
|
UNMAPPED | TEXT | 値は次のいずれかです:
|
Values for the UNMAPPED column
以下の表は、UNMAPPED 列の可能な値です。
| Value | Meaning |
|---|---|
NULL | DII が正常にマッピングされました。 |
OPTOUT | ユーザーがオプトアウトしています。 |
INVALID IDENTIFIER | メールアドレスまたは電話番号が無効です。 |
INVALID INPUT_TYPE | INPUT_TYPE の値が無効です。INPUT_TYPE の有効な値は、email、email_hash、phone、phone_hash です。 |
Examples
以下はマッピングリクエストの例です:
- Single unhashed email
- Multiple unhashed emails
- Single unhashed phone number
- Multiple unhashed phone numbers
- Single hashed email
- Multiple hashed emails
- Single hashed phone number
- Multiple hashed phone numbers
これらの例の入力および出力データは架空のものであり、説明を目的としています。提供されている値は実際の値ではありません。
Mapping request example - single unhashed email
以下のクエリは、default database and schema namesを使用して、単一のメールアドレスをマッピングする方法です。
select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3('validate@example.com', 'email'));
単一のメールアドレスのクエリ結果は以下の通りです:
+----------------------------------------------+--------------------------------------------------+--------------+----------+
| UID | PREV_UID | REFRESH_FROM | UNMAPPED |
+----------------------------------------------+--------------------------------------------------+--------------+----------+
| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL |
+----------------------------------------------+--------------------------------------------------+--------------+----------+
Mapping request example - multiple unhashed emails
以下のクエリは、default database and schema namesを使用して、複数のメールアドレスをマッピングする方法です。
select a.ID, a.EMAIL, m.UID, m.PREV_UID, m.REFRESH_FROM, m.UNMAPPED from AUDIENCE a LEFT JOIN(
select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(EMAIL, 'email') t) m
on a.ID=m.ID;
複数のメールアドレスのクエリ結果は以下の通りです:
以下の表は、レスポンス内の各項目を識別し、NULL または不正な形式のメールアドレスに対する NULL 値を含みます。
+----+----------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
| ID | EMAIL | UID | PREV_UID | REFRESH_FROM | UNMAPPED |
+----+----------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL |
| 2 | test@uidapi.com | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | NULL | 1735689600 | NULL |
| 3 | optout@example.com | NULL | NULL | NULL | OPTOUT |
| 4 | invalid-email | NULL | NULL | NULL | INVALID IDENTIFIER |
| 5 | NULL | NULL | NULL | NULL | INVALID IDENTIFIER |
+----+----------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
Mapping request example - single unhashed phone number
以下のクエリは、default database and schema namesを使用して、単一の電話番号をマッピングする方法です。
電話番号は、UID2 Phone number normalization ルールを使用して正規化する必要があります。
select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3('+12345678901', 'phone'));
単一の電話番号のクエリ結果は以下の通りです:
+----------------------------------------------+----------+--------------+----------+
| UID | PREV_UID | REFRESH_FROM | UNMAPPED |
+----------------------------------------------+----------+--------------+----------+
| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | NULL | 1735689600 | NULL |
+----------------------------------------------+----------+--------------+----------+
Mapping request example - multiple unhashed phone numbers
以下のクエリは、default database and schema namesを使用して、複数の電話番号をマッピングする方法です。
電話番号は、UID2 Phone number normalization ルールを使用して正規化する必要があります。
select a.ID, a.PHONE, m.UID, m.PREV_UID, m.REFRESH_FROM, m.UNMAPPED from AUDIENCE a LEFT JOIN(
select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(PHONE, 'phone') t) m
on a.ID=m.ID;
複数の電話番号のクエリ結果は以下の通りです:
以下の表は、レスポンス内の各項目を識別し、NULL または不正な形式の電話番号に対する NULL 値を含みます。
+----+--------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
| ID | PHONE | UID | PREV_UID | REFRESH_FROM | UNMAPPED |
+----+--------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
| 1 | +12345678901 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL |
| 2 | +61491570006 | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | NULL | 1735689600 | NULL |
| 3 | +56789123001 | NULL | NULL | NULL | OPTOUT |
| 4 | 1234 | NULL | NULL | NULL | INVALID IDENTIFIER |
| 5 | NULL | NULL | NULL | NULL | INVALID IDENTIFIER |
+----+--------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
Mapping request example - single hashed email
以下のクエリは、default database and schema namesを使用して、単一のメールアドレスハッシュをマッピングする方法です。
select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(BASE64_ENCODE(SHA2_BINARY('validate@example.com', 256)), 'email_hash'));
単一のメールアドレスハッシュのクエリ結果は以下の通りです:
+----------------------------------------------+----------------------------------------------+--------------+----------+
| UID | PREV_UID | REFRESH_FROM | UNMAPPED |
+----------------------------------------------+----------------------------------------------+--------------+----------+
| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL |
+----------------------------------------------+----------------------------------------------+--------------+----------+
Mapping request example - multiple hashed emails
以下のクエリは、default database and schema namesを使用して、複数のメールアドレスハッシュをマッピングする方法です。
select a.ID, a.EMAIL_HASH, m.UID, m.PREV_UID, m.REFRESH_FROM, m.UNMAPPED from AUDIENCE a LEFT JOIN(
select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(EMAIL_HASH, 'email_hash') t) m
on a.ID=m.ID;
複数のメールアドレスハッシュのクエリ結果は以下の通りです:
以下の表は、レスポンス内の各項目を識別し、NULL または不正な形式のメールアドレスハッシュに対する NULL 値を含みます。
+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
| ID | EMAIL_HASH | UID | PREV_UID | REFRESH_FROM | UNMAPPED |
+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
| 1 | LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI= | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL |
| 2 | /XJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g= | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | NULL | 1735689600 | NULL |
| 2 | UebesrNN0bQkm/QR7Jx7eav+UDXN5Gbq3zs1fLBMRy0= | NULL | NULL | 1735689600 | OPTOUT |
| 4 | NULL | NULL | NULL | NULL | INVALID IDENTIFIER |
+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
Mapping request example - single hashed phone number
以下のクエリは、default database and schema namesを使用して、単一の電話番号ハッシュをマッピングする方法です。
select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(BASE64_ENCODE(SHA2_BINARY('+12345678901', 256)), 'phone_hash'));
単一の電話番号ハッシュのクエリ結果は以下の通りです:
+----------------------------------------------+----------------------------------------------+--------------+----------+
| UID | PREV_UID | REFRESH_FROM | UNMAPPED |
+----------------------------------------------+----------------------------------------------+--------------+----------+
| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL |
+----------------------------------------------+----------------------------------------------+--------------+----------+
Mapping request example - multiple hashed phone numbers
以下のクエリは、default database and schema namesを使用して、複数の電話番号ハッシュをマッピングする方法です。
select a.ID, a.PHONE_HASH, m.UID, m.PREV_UID, m.REFRESH_FROM, m.UNMAPPED from AUDIENCE a LEFT JOIN(
select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(PHONE_HASH, 'phone_hash') t) m
on a.ID=m.ID;
複数の電話番号ハッシュのクエリ結果は以下の通りです:
以下の表は、 レスポンス内の各項目を識別し、NULL または不正な形式の電話番号ハッシュに対する NULL 値を含みます。
+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
| ID | PHONE_HASH | UID | PREV_UID | REFRESH_FROM | UNMAPPED |
+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
| 1 | LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI= | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL |
| 2 | /XJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g= | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | NULL | 1735689600 | NULL |
| 2 | UebesrNN0bQkm/QR7Jx7eav+UDXN5Gbq3zs1fLBMRy0= | NULL | NULL | 1735689600 | OPTOUT |
| 4 | NULL | NULL | NULL | NULL | INVALID IDENTIFIER |
+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+
Monitor raw UID2 refresh and regenerate raw UID2s
FN_T_IDENTITY_MAP_V3 関数は、各 UID2 をリフレッシュする必要がある時刻を示すリフレッシュタイムスタンプ (REFRESH_FROM) を返します。
raw UID2 は、リフレッシュタイムスタンプの前では変化しません。リフレッシュタイムスタンプの後、DII を再マッピングすると新しいリフレッシュタイムスタンプが返されますが、raw UID2 は変化する場合もあれば変化しない場合もあります。raw UID2 が複数のリフレッシュ間隔にわたって変化しない可能性もあります。
UID2 のリフレッシュが必要なものを特定するには、関数から返された REFRESH_FROM タイムスタンプを現在の時刻と比較します。
| Column Name | Data Type | Description |
|---|---|---|
UID | TEXT | UID2 に関連付けられた DII です。これは、アイデンティティマッピング関数によって返された現在の UID2 値です。 |
REFRESH_FROM | NUMBER | この UID2 をリフレッシュする必要がある時刻を示すタイムスタンプ (エポック秒) です。この値を現在の時刻と比較して、再生成が必要かどうかを判断します。 |
以下の例は、入力テーブルと、リフレッシュ時間が到達したために再生成する必要がある UID2 をテーブル内で見つけるために使用されるクエリです。
Targeted input table
この例では、広告主/データプロバイダーは、AUDIENCE_WITH_UID2 という名前のテーブルに UID2 を保存しています。REFRESH_FROM 列には、各 UID2 をリフレッシュする必要があるタイムスタンプが含まれています。UID2 が生成されていない場合、値は NULL です（3 番目の例を参照）。広告主/データプロバイダーは、これらのタイムスタンプを現在の時刻と比較して、どの UID2 を再生成する必要があるかを判断できます。
select * from AUDIENCE_WITH_UID2;
+----+----------------------+----------------------------------------------+--------------+
| ID | EMAIL | UID2 | REFRESH_FROM |
+----+----------------------+----------------------------------------------+--------------+
| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | 1735689600 |
| 2 | test1@uidapi.com | Q4A5ZBuBCYfuV3Wd8Fdsx2+i33v7jyFcQbcMG/LH4eM= | 1735776000 |
| 3 | test2@uidapi.com | NULL | NULL |
+----+----------------------+----------------------------------------------+--------------+
欠落または期限切れの UID2 を見つけるには、次のクエリ例を使用します。
select * from AUDIENCE_WITH_UID2
where REFRESH_FROM <= DATE_PART(epoch_second, CURRENT_TIMESTAMP()) or UID2 IS NULL;
クエリの結果:
次の表は、レスポンス内の各アイテムを特定します。結果には、REFRESH_FROM タイムスタンプが経過したためにリフレッシュが必要な UID2 または欠落している UID2 が含まれます。ID 1 は、そのリフレッシュ時間 (1735689600) が過去にあるため返されます (現在の時間がそれ以降であると仮定)。ID 2 は、そのリフレッシュ時間がまだ到達していないため返されません。ID 3 は、UID2 が欠落しているため返されます。
+----+----------------------+----------------------------------------------+--------------+
| ID | EMAIL | UID2 | REFRESH_FROM |
+----+----------------------+----------------------------------------------+--------------+
| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | 1735689600 |
| 3 | test2@uidapi.com | NULL | NULL |
+----+----------------------+----------------------------------------------+--------------+
Usage for UID2 sharers
UID2 sharing participant は、送信者または受信者として共有に参加し、他の参加者と UID2 を共有する組織です。
広告主とデータプロバイダーは、Snowflake (tokenized sharing)を介して、他の承認された UID2 共有参加者と UID2 を共有できます。彼らは raw UID2s を UID2 Token に暗号化し、ピクセルで共有するために別の参加者に送信できます (詳細は Tokenized sharing in pixels を参照してください)。Snowflake 内でピクセルでデータを送信していない場合でも、Security requirements for UID2 sharing に記載されている要件に従う限り、UID2 共有に参加できます。
このプロセスで生成された UID2 Token は共有用であり、ビッドストリームでは使用できません。ビッドストリーム用のトークンを生成するための別のワークフローがあります: Tokenized sharing in the bidstream を参照してください。
Snowflake でピクセルやビッドストリームでデータを送信していない場合でも、Security requirements for UID2 sharing に記載されている要件に従う限り、UID2 共有に参加できます。
以下の機能は、トークン化された共有をサポートしています:
Encrypt tokens
raw UID2 を UID2 Token に暗号化するには、FN_T_ENCRYPT 関数を使用します。
| Argument | Data Type | Description |
|---|---|---|
RAW_UID2 | varchar(128) | UID2 Token に暗号化する raw UID2 |
クエリが成功すると、指定された raw UID2 に対して以下の情報が返されます。
| Column Name | Data Type | Description |
|---|---|---|
UID_TOKEN | TEXT | 値は以下のいずれか:
|
ENCRYPTION_STATUS | TEXT | 値は以下のいずれか:
|
Values for the ENCRYPTION_STATUS column
以下の表は、ENCRYPTION_STATUS 列の可能な値を示しています。
| Value | Meaning |
|---|---|
NULL | raw UID2 が正常に暗号化されました。 |
MISSING_OR_INVALID_RAW_UID2 | raw UID2 が NULL です。 |
INVALID_RAW_UID2 | raw UID2 が無効です。 |
MISMATCHING_IDENTITY_SCOPE | raw UID2 が不正なアイデンティティスコープに属しています。たとえば、UID2 が期待される場所に EUID が渡されます。 |
NOT_AUTHORIZED_FOR_MASTER_KEY | 呼び出し元が必要な暗号化キーにアクセスできません。UID2 管理者にお問い合わせください。 |
NOT_AUTHORIZED_FOR_SITE_KEY | 呼び出し元が必要な暗号化キーにアクセスできません。UID2 管理者にお問い合わせください。 |
Encrypt token request example - single raw UID2
以下のクエリは、default database and schema namesを使用して、単一の raw UID2 を UID2 Token に暗号化する方法です。
select UID_TOKEN, ENCRYPTION_STATUS from table(UID2_PROD_UID_SH.UID.FN_T_ENCRYPT('2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU='));
単一の raw UID2 のクエリ結果は以下の通りです:
+------------------------+-------------------+
| UID_TOKEN | ENCRYPTION_STATUS |
+--------------------------------------------+
| A41234<rest of token> | NULL |
+--------------------------------------------+
Encrypt token request example - multiple raw UID2s
以下のクエリは、default database and schema namesを使用して、複数の raw UID2 を UID2 Token に暗号化する方法です。
select a.RAW_UID2, t.UID_TOKEN, t.ENCRYPTION_STATUS from AUDIENCE_WITH_UID2 a, lateral UID2_PROD_UID_SH.UID.FN_T_ENCRYPT(a.RAW_UID2) t;
複数の raw UID2 のクエリ結果は以下の通りです:
以下の表は、レスポンス内の各項目を識別し、NULL または不正な形式の電話番号ハッシュに対する NULL 値を含みます。
+----+----------------------------------------------+-----------------------+-----------------------------+
| ID | RAW_UID2 | UID_TOKEN | ENCRYPTION_STATUS |
+----+----------------------------------------------+-----------------------+-----------------------------+
| 1 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | A41234<rest of token> | NULL |
| 2 | NULL | NULL | MISSING_OR_INVALID_RAW_UID2 |
| 3 | BXJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g5 | B45678<rest of token> | NULL |
+----+----------------------------------------------+-----------------------+-----------------------------+
Decrypt tokens
UID2 Token を raw UID2 に復号化するには、FN_T_DECRYPT 関数を使用します。
| Argument | Data Type | Description |
|---|---|---|
UID_TOKEN | varchar(512) | raw UID2 に復号化する UID2 Token です。 |
クエリが成功すると、指定された UID2 Token に対して以下の情報が返されます。
| Column Name | Data Type | Description |
|---|---|---|
UID | TEXT | 以下の値のいずれか:
|
SITE_ID | INT | 以下の値のいずれか:
|
DECRYPTION_STATUS | TEXT | 以下の値のいずれか:
|
UID2 Token が復号化できない場合、関数は通常、行を返しません。
Values for the DECRYPTION_STATUS column
DECRYPTION_STATUS の可能な値は以下の通りです:
| Value | Meaning |
|---|---|
NULL | UID2 Token は復号化されました。 |
EXPIRED_TOKEN | UID2 Token は指定された有効期限を超えています。 |
Decrypt token request example—single UID2 token
以下のクエリは、default database and schema namesを使用して、単一の UID2 Token を raw UID2 に復号化する方法です。
select UID, SITE_ID, DECRYPTION_STATUS from table(UID2_PROD_UID_SH.UID.FN_T_DECRYPT('A41234<rest of token>'));
単一の UID2 Token のクエリ結果は以下の通りです:
+----------------------------------------------+-------------------+
| UID | DECRYPTION_STATUS |
+----------------------------------------------+-------------------+
| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | NULL |
+----------------------------------------------+-------------------+
Decrypt token request example—multiple UID2 tokens
以下のクエリは、default database and schema namesを使用して、複数の UID2 Token を raw UID2 に復号化する方法です。
select a.ID, b.UID, b.SITE_ID, CASE WHEN b.UID IS NULL THEN 'DECRYPT_FAILED' ELSE b.DECRYPTION_STATUS END as DECRYPTION_STATUS
from TEST_IMPRESSION_DATA a LEFT OUTER JOIN (
select ID, t.* from TEST_IMPRESSION_DATA, lateral UID2_PROD_UID_SH.UID.FN_T_DECRYPT(UID_TOKEN) t) b
on a.ID=b.ID;
複数の UID2 Token のクエリ結果は以下の通りです:
以下の表は、レスポンス内の各項目を識別し、NULL または不正な形式の電話番号ハッシュに対する NULL 値を含みます。
+----+----------------------------------------------+----------+-------------------+
| ID | UID | SITE_ID | DECRYPTION_STATUS |
+----+----------------------------------------------+----------+-------------------+
| 1 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | 12345 | NULL |
| 2 | NULL | NULL | DECRYPT_FAILED |
| 3 | BXJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g5 | 23456 | NULL |
| 4 | NULL | NULL | EXPIRED_TOKEN |
| 5 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | 12345 | NULL |
+----+----------------------------------------------+----------+-------------------+
UID2 sharing example
以下の手順は、Snowflake を使用する送信者と受信者の両方の共有方法の例を示しています。この例では、広告主 (送信者) が raw UID2s を含むオーディエンステーブル (AUDIENCE_WITH_UID2S) を持ち、データプロバイダー (受信者) にテーブル内のデータを Snowflake Secure Data Sharing 機能を使用して利用可能にしたいと考えています。
Sender instructions
AUDIENCE_WITH_UID2_TOKENSテーブルを作成します。AUDIENCE_WITH_UID2Sテーブル内の raw UID2s を暗号化し、結果をAUDIENCE_WITH_UID2_TOKENSテーブルに保存します。次のクエリは、このタスクを達成するのに役立ちます:insert into AUDIENCE_WITH_UID2_TOKENS select a.ID, t.UID_TOKEN from AUDIENCE_WITH_UID2S a, lateral UID2_PROD_UID_SH.UID.FN_T_ENCRYPT(a.RAW_UID2) t;- セキュアな共有を作成し、
AUDIENCE_WITH_UID2_TOKENSテーブルへのアクセスを許可します。 - 受信者にセキュアな共有へのアクセスを許可します。
UID2 Token が共有中に期限切れにならないようにするために、暗号化された UID2 Token をできるだけ早く受信者に送信してください。
Receiver instructions
- 送信者が提供したセキュアな共有からデータベースを作成します。
RECEIVED_AUDIENCE_WITH_UID2という新しいテーブルを作成します。- 共有された
AUDIENCE_WITH_UID2_TOKENSテーブルからトークンを復号化し、その結果をRECEIVED_AUDIENCE_WITH_UID2テーブルに保存します。次のクエリは、このタスクを達成するのに役立ちます:insert into RECEIVED_AUDIENCE_WITH_UID2
select a.ID, b.UID, CASE WHEN b.UID IS NULL THEN 'DECRYPT_FAILED' ELSE b.DECRYPTION_STATUS END as DECRYPTION_STATUS
from AUDIENCE_WITH_UID2_TOKENS a LEFT OUTER JOIN (
select ID, t.* from AUDIENCE_WITH_UID2_TOKENS, lateral UID2_PROD_UID_SH.UID.FN_T_DECRYPT(UID_TOKEN) t) b
on a.ID=b.ID;
UID2 Token が共有中に期限切れにならないようにするために、受信者は送信者からトークンをできるだけ早く復号化してください。
Migration guide
このセクションでは、以前のバージョンから新しい UID2 Snowflake v3 機能にアップグレードするための情報を提供します。
2025 年 2 月以前のバージョンからアップグレードする場合は、以前のバージョンのドキュメントの Migration guide を参照してください。
Changing existing code
変更の概要は、Changes from previous versionを参照してください。このセクションのコードスニペットは、以前の関数がどのように実装されていたかの前後の例であり、新しい関数を使用するように更新する方法を示しています。主な変更点は、FN_T_IDENTITY_MAPからFN_T_IDENTITY_MAP_V3への移行であり、これによりソルトバケット ID の代わりにリフレッシュタイムスタンプが提供され、以前の UID2 アクセスも含まれます。
Example for mapping unhashed emails
Before:
select UID, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP(EMAIL, 'email'));
After:
select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP_V3(EMAIL, 'email'));
Example for mapping unhashed phone numbers
Before:
select UID, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP(PHONE_NUMBER, 'phone'));
After:
select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP_V3(PHONE_NUMBER, 'phone'));
Example for monitoring UID2 refresh and regenerating raw UID2s
v3 関数はリフレッシュタイムスタンプを直接提供するため、ソルトバケットを監視する必要がなくなりました。ソルトバケットビューと結合する代わりに、関数から返された REFRESH_FROM タイムスタンプを現在のタイムスタンプと比較できます。
Before (ソルトバケットをモニタリング):
select a.*, b.LAST_SALT_UPDATE_UTC
from AUDIENCE_WITH_UID2 a LEFT OUTER JOIN {DATABASE_NAME}.{SCHEMA_NAME}.SALT_BUCKETS b
on a.BUCKET_ID=b.BUCKET_ID
where a.LAST_UID2_UPDATE_UTC < b.LAST_SALT_UPDATE_UTC or a.UID2 IS NULL;
After (リフレッシュタイムスタンプを使用):
select * from AUDIENCE_WITH_UID2
where REFRESH_FROM <= DATE_PART(epoch_second, CURRENT_TIMESTAMP()) or UID2 IS NULL;