メインコンテンツまでスキップ

Snowflake Integration Guide

Snowflake はクラウドデータウェアハウスソリューションで、パートナーとして顧客のデータを保存し、UID2 フレームワークとインテグレーションできます。Snowflake を使用することで、UID2 は、機密性の高い directly identifying information (DII) を公開することなく、認可された消費者識別子データを安全に共有できます。消費者識別子データを直接 Operator Web Services に問い合わせることもできますが、Snowflake UID2 とのインテグレーションにより、よりシームレスな体験が可能になります。

UID2 の以下のリストが Snowflake marketplace で入手可能です:

Functionality​

以下の表は、UID2 Snowflake インテグレーションで利用可能な機能をまとめたものです。

Encrypt Raw UID2 to UID2 TokenDecrypt Raw UID2 from UID2 TokenGenerate UID2 Token from DIIRefresh UID2 TokenMap DII to a raw UID2
YesYesNo*NoYes

*DII から直接 UID2 Token を生成することはできません。しかし、DII を raw UID2 に変換し、raw UID2 を暗号化して UID2 Token にすることはできます。

NOTE: ビッドストリームで UID2 Token を共有するパブリッシャーの場合は、Tokenized Sharing in the Bid Stream を参照してください

Workflow Diagram​

次の図は、Snowflake が UID2 インテグレーションプロセスにどのように関わるかを示しています:

Snowflake Integration Architecture

Partner Snowflake AccountUID2 Snowflake AccountUID2 Core Opt-Out Cloud Setup
パートナーは、Snowflake アカウントを設定してデータをホストし、UID2 Share を通じて関数やビューを使うことで、UID2 インテグレーションに関与できます。Snowflake アカウントでホストされている UID2 インテグレーションでは、プライベートテーブルからデータを引き出す認可をされた関数とビューへのアクセスが許可されます。プライベートテーブルにはアクセスできません。UID2 Share では、UID2 関連のタスクを実行するために必要な重要なデータのみが公開されます。ETL (Extract Transform Load) ジョブは、UID2 Core/Optout Snowflake ストレージを常に更新し、UID2 Operator Web Services を動かす内部データを提供します。Operator Web Services で使用されるデータは、UID2 Share からも入手できます。
Shared 関数とビューを使用する場合、Snowflake にトランザクションのコストを支払います。UID2 Snowflake アカウントで保護されたこれらのプライベートテーブルは、UID2 関連のタスクを完了するために使用される内部データを保持する UID2 Core/Optout Snowflake ストレージと自動的に同期されます。

Access the UID2 Shares​

UID2 Shareへのアクセスは、Snowflake Data Marketplace を通して行います。ここでは、選択した UID2 パーソナライズドリストに基づいて特定のデータセットをリクエストすることができます。

Snowflakeデータマーケットプレイスでは、UID2 用に2つのパーソナライズされたリストが提供されています:

IMPORTANT: データをリクエストするには、Snowflake アカウントにACCOUNTADMIN ロール権限が必要です。

UID2 Share へのアクセスを要求するには、次の手順を実行します。

  1. Snowflake Data Marketplace にログインし、関心のある UID2 ソリューションを選択します:
  2. パーソナライズドデータ セクションで、データのリクエスト をクリックします。
  3. 画面の指示に従って、連絡先やその他の必要情報を確認し、入力してください。
  4. The Trade Desk の既存顧客で Advertiser Identity Solution に興味がある場合は、データリクエストフォームの Message 欄に The Trade Desk が発行したパートナー ID および広告主 ID を記載してください。
  5. フォームを送信します。

リクエストを受け取った後、UID2 Administrator が適切なアクセス方法をご連絡します。Snowflake でのデータリクエストの管理についての詳細は、Snowflake documentation を参照してください。

Shared Objects​

選択した UID2 ソリューションに関係なく、以下の関数を使って、DII を UID2 にマッピングできます:

  • FN_T_UID2_IDENTITY_MAP (Map DII を参照してください)

以下の関数は非推奨となり、FN_T_UID2_IDENTITY_MAP が優先されます。これらの関数はまだ使用できますが、 FN_T_UID2_IDENTITY_MAP の方が優れています。すでにこれらの関数を使用している場合は、できるだけ早くアップグレードすることをお勧めします。

  • FN_T_UID2_IDENTITY_MAP_EMAIL (非推奨)
  • FN_T_UID2_IDENTITY_MAP_EMAIL_HASH (非推奨)

NOTE: 非推奨の関数を使用していて、新しい関数への移行の手助けが必要な場合は、Migration Guide を参照してください。

再生成が必要な UID2 を特定するには、UID Share から UID2_SALT_BUCKETS ビューを使用します。詳しくは、Regenerate UID2s を参照してください。

UID2 Sharing 参加者には、以下の機能も利用できます:

詳細は、Usage for UID2 Sharers を参照してください。

Database and Schema Names​

以下のセクションでは、各ソリューションのクエリ例を示します。これらは、データベースとスキーマ名の変数を除けば、同じものです:

{DATABASE_NAME}.{SCHEMA_NAME}

例:

select UID2, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_IDENTITY_MAP('validate@example.com', 'email'));

すべてのクエリ例では、各名前変数に以下のデフォルト値を使用しています:

VariableAdvertiser Solution Default ValueData Provider Solution Default ValueComments
{DATABASE_NAME}UID2_PROD_ADV_SHUID2_PROD_DP_SH必要であれば、選択した UID2 Share へのアクセス権が与えられた後に新しいデータベースを作成する際に、デフォルトのデータベース名を変更できます。
{SCHEMA_NAME}ADVDPこれはイミュータブルです。

Map DII​

すべてのタイプの DII をマッピングするには、FN_T_UID2_IDENTITY_MAP 関数を使用します。

DII がメールアドレスの場合、サービスは UID2 メールアドレスの正規化 規則を使用して正規化されます。

DII が電話番号の場合、UID2 電話番号正規化 ルールを使用して、サービスに送信する前に正規化する必要があります。

ArgumentData TypeDescription
INPUTvarchar(256)UID2とセカンドレベルレベルのバケット ID にマッピングするDII。
INPUT_TYPEvarchar(256)マッピングするDIIのタイプ。指定できる値: email, email_hash, phone, phone_hash

クエリに成功すると、指定された DII について以下の情報が返されます。

Column NameData TypeDescription
UID2TEXTDII は正常にマッピングされました:
DII は正常にマップされませんでした: NULL。
BUCKET_IDTEXTDIIは正常にマップされました: UID2 の生成に使われたセカンドレベルのソルトバケットの ID。この ID は UID2_SALT_BUCKETS ビューのバケットIDに対応します。
DIIは正常にマップされませんでした: NULL。
UNMAPPEDTEXTDII は正常にマッピングされました: NULL
DII は正常にマップされませんでした: NULL: DII は正常にマップされませんでした: 識別子がマップされなかった理由: OPTOUT、INVALID IDENTIFIER、INVALID INPUT TYPE のいずれか。詳細は Values for the UNMAPPED Column を参照してください。

Values for the UNMAPPED Column​

UNMAPPEDに指定できる値は以下の通りです:

ValueMeaning
NULLDII は正常にマッピングされました。
OPTOUTユーザはオプトアウトしました。
INVALID IDENTIFIERメールアドレスまたは電話番号が無効です。
INVALID INPUT TYPEINPUT_TYPE の値が無効です。INPUT_TYPE の値は以下のいずれかでなければなりません: email、email_hash、phone、phone_hash。

Examples​

このセクションのマッピングリクエストの例:

NOTE: これらの例の入出力データは、説明のみを目的とした架空のものです。提供された値は実際の値ではありません。

Mapping Request Example - Single Unhashed Email​

次のクエリは、デフォルトのデータベースとスキーマ名 を使用して、単一のメールアドレスをマッピングする方法を示しています。

単一のメールアドレスに対する広告主ソリューションのクエリー:

select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP('validate@example.com', 'email'));

単一のメールアドレスに対するデータプロバイダーソリューションのクエリー:

select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP('validate@example.com', 'email'));

単一のメールアドレスに対するクエリー結果:

+----------------------------------------------+------------+----------+
| UID2                                         | BUCKET_ID  | UNMAPPED |
+----------------------------------------------+------------+----------+
| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ  | NULL     |
+----------------------------------------------+------------+----------+

Mapping Request Example - Multiple Unhashed Emails​

以下のクエリは、デフォルトのデータベースとスキーマ名 を使用して、複数のメールアドレスをマッピングする方法を示しています。

複数のメールアドレスに対する広告主ソリューションのクエリー:

select a.ID, a.EMAIL, m.UID2, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN(
    select ID, t.* from AUDIENCE, lateral UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP(EMAIL, 'email') t) m
    on a.ID=m.ID;

複数のメールアドレスに対するデータプロバイダーソリューションのクエリー:

select a.ID, a.EMAIL, m.UID2, m.BUCKET_ID, UNMAPPED from AUDIENCE a LEFT JOIN(
    select ID, t.* from AUDIENCE, lateral UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP(EMAIL, 'email') t) m
    on a.ID=m.ID;

複数のメールアドレスに対するクエリー結果:

以下の表は、NULL または不適切な書式のメールアドレスに対する NULL 値を含む、 レスポンスの各項目です。

+----+--------------------+----------------------------------------------+------------+--------------------+
| ID | EMAIL              | UID2                                         | BUCKET_ID  | UNMAPPED           |
+----+--------------------+----------------------------------------------+------------+--------------------+
|  1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ  | NULL               |
|  2 | test@uidapi.com    | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL               |
|  3 | invalid-email      | NULL                                         | NULL       | INVALID IDENTIFIER |
|  4 | NULL               | NULL                                         | NULL       | INVALID IDENTIFIER |
+----+--------------------+----------------------------------------------+------------+--------------------+

Mapping Request Example - Single Unhashed Phone Number​

以下のクエリは、デフォルトのデータベース名とスキーマ名 を使って電話番号をマッピングする方法を示しています。

電話番号は、UID2 電話番号正規化 ルールを使って正規化する必要があります。

単一の電話番号に対する広告主ソリューションのクエリー:

select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP('+12345678901', 'phone'));

単一の電話番号に対するデータプロバイダーソリューションのクエリー:

select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP('+12345678901', 'phone'));

単一の電話番号に対するクエリー結果:

+----------------------------------------------+------------+----------+
| UID2                                         | BUCKET_ID  | UNMAPPED |
+----------------------------------------------+------------+----------+
| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ  | NULL     |
+----------------------------------------------+------------+----------+

Mapping Request Example - Multiple Unhashed Phone Numbers​

以下のクエリは、デフォルトのデータベース名とスキーマ名 を使用して、複数の電話番号をマップする方法を示しています。

電話番号は UID2 の電話番号正規化 ルールを使って正規化する必要があります。

複数の電話番号に対する広告主ソリューションのクエリー:

select a.ID, a.PHONE, m.UID2, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN(
    select ID, t.* from AUDIENCE, lateral UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP(PHONE, 'phone') t) m
    on a.ID=m.ID;

複数の電話番号に対するデータプロバイダーソリューションのクエリー:

select a.ID, a.PHONE, m.UID2, m.BUCKET_ID, UNMAPPED from AUDIENCE a LEFT JOIN(
    select ID, t.* from AUDIENCE, lateral UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP(PHONE, 'phone') t) m
    on a.ID=m.ID;

複数の電話番号に対するクエリー結果:

The following table identifies each item in the response, including NULL values for NULL or invalid phone numbers.

+----+--------------+----------------------------------------------+------------+--------------------+
| ID | PHONE        | UID2                                         | BUCKET_ID  | UNMAPPED           |
+----+--------------+----------------------------------------------+------------+--------------------+
|  1 | +12345678901 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ  | NULL               |
|  2 | +61491570006 | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL               |
|  3 | 1234         | NULL                                         | NULL       | INVALID IDENTIFIER |
|  4 | NULL         | NULL                                         | NULL       | INVALID IDENTIFIER |
+----+--------------+----------------------------------------------+------------+--------------------+

Mapping Request Example - Single Hashed Email​

以下のクエリは、デフォルトのデータベースとスキーマ名 を使用して、単一のメールアドレスハッシュをマップする方法を示しています。

単一のハッシュ化されたメールアドレスに対する広告主ソリューションのクエリー:

select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('validate@example.com', 256)), 'email_hash'));

単一のハッシュ化されたメールアドレスに対するデータプロバイダーソリューションのクエリー:

select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('validate@example.com', 256)), 'email_hash'));

単一のハッシュ化されたメールアドレスに対するクエリー結果:

+----------------------------------------------+------------+----------+
| UID2                                         | BUCKET_ID  | UNMAPPED |
+----------------------------------------------+------------+----------+
| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ  | NULL     |
+----------------------------------------------+------------+----------+

Mapping Request Example - Multiple Hashed Emails​

以下のクエリは、デフォルトのデータベースとスキーマ名 を使用して、複数のメールアドレスハッシュをマッピングする方法を示しています。

複数のハッシュ化されたメールアドレスに対する広告主ソリューションのクエリー:

select a.ID, a.EMAIL_HASH, m.UID2, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN(
    select ID, t.* from AUDIENCE, lateral UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP(EMAIL_HASH, 'email_hash') t) m
    on a.ID=m.ID;

複数のハッシュ化されたメールアドレスに対するデータプロバイダーソリューションのクエリー:

select a.ID, a.EMAIL_HASH, m.UID2, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN(
    select ID, t.* from AUDIENCE, lateral UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP(EMAIL_HASH, 'email_hash') t) m
    on a.ID=m.ID;

複数のハッシュ化されたメールアドレスに対するクエリー結果:

以下の表は、NULL ハッシュの NULL 値を含め、レスポンスの各項目を示しています。

+----+----------------------------------------------+----------------------------------------------+------------+--------------------+
| ID | EMAIL_HASH                                   | UID2                                         | BUCKET_ID  | UNMAPPED           |
+----+----------------------------------------------+----------------------------------------------+------------+--------------------+
|  1 | LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI= | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ  | NULL               |
|  2 | NULL                                         | NULL                                         | NULL       | INVALID IDENTIFIER |
|  3 |/XJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g=  | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL               |
+----+----------------------------------------------+----------------------------------------------+------------+--------------------+

Mapping Request Example - Single Hashed Phone Number​

以下のクエリは、デフォルトのデータベース名とスキーマ名 を使用して、単一の電話番号ハッシュをマップする方法を示しています。

単一のハッシュ化された電話番号に対する広告主ソリューションのクエリー:

select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('+12345678901', 256)), 'phone_hash'));

単一のハッシュ化された電話番号に対するデータプロバイダーソリューションのクエリー:

select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('+12345678901', 256)), 'phone_hash'));

単一のハッシュ化された電話番号に対するクエリー結果:

+----------------------------------------------+------------+----------+
| UID2                                         | BUCKET_ID  | UNMAPPED |
+----------------------------------------------+------------+----------+
| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ  | NULL     |
+----------------------------------------------+------------+----------+

Mapping Request Example - Multiple Hashed Phone Numbers​

以下のクエリは、デフォルトのデータベース名とスキーマ名 を使用して、複数の電話番号ハッシュをマップする方法を示しています。

複数のハッシュ化された電話番号に対する広告主ソリューションのクエリー:

select a.ID, a.PHONE_HASH, m.UID2, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN(
    select ID, t.* from AUDIENCE, lateral UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP(PHONE_HASH, 'phone_hash') t) m
    on a.ID=m.ID;

複数のハッシュ化された電話番号に対するデータプロバイダーソリューションのクエリー:

select a.ID, a.PHONE_HASH, m.UID2, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN(
    select ID, t.* from AUDIENCE, lateral UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP(PHONE_HASH, 'phone_hash') t) m
    on a.ID=m.ID;

複数のハッシュ化された電話番号に対するクエリー結果:

以下の表は、NULL ハッシュの NULL 値を含め、レスポンスの各項目を示しています。

+----+----------------------------------------------+----------------------------------------------+------------+--------------------+
| ID | PHONE_HASH                                   | UID2                                         | BUCKET_ID  | UNMAPPED           |
+----+----------------------------------------------+----------------------------------------------+------------+--------------------+
|  1 | LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI= | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ  | NULL               |
|  2 | NULL                                         | NULL                                         | NULL       | INVALID IDENTIFIER |
|  3 |/XJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g=  | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL               |
+----+----------------------------------------------+----------------------------------------------+------------+--------------------+

Regenerate UID2s​

UID2_SALT_BUCKETS ビュークエリは、セカンドレベルのソルトバケットが最後に更新された日時を返します。セカンドレベルのソルトは UID2 を生成する際に使用されます。バケット内のソルトが更新されると、それまで生成されていた UID2 が古くなり、同じユーザーに対して他者が生成した UID2 とは一致しなくなります。

どの UID2 が再生成を必要としているかを判断するには、生成されたときのタイムスタンプを、セカンドレベルのソルトバケット更新の最新のタイムスタンプと比較します。

Column NameData TypeDescription
BUCKET_IDTEXTセカンドレベルのソルトバケットの ID です。この ID は、ID マップ関数が返す BUCKET_ID と同じものです。BUCKET_ID をキーとして、関数呼び出しの結果とこのビュー呼び出しの結果の間のジョインクエリを実行します。
LAST_SALT_UPDATE_UTCTIMESTAMP_NTZバケット内のソルトが最後に更新された時刻です。この値は UTC タイムゾーンで表現されます。

次の例は、入力テーブルと、セカンドレベルのソルトが更新されたために再生成が必要なテーブルの UID2 を見つけるために使用されるクエリを示しています。

Targeted Input Table​

このシナリオ例では、広告主/データプロバイダーは UID2 を AUDIENCE_WITH_UID2 という名前のテーブルに格納しています。最後の列 LAST_UID2_UPDATE_UTC は、UID2 が生成された時刻を記録するために使用されます。UID2 が生成されていない場合、3番目の例に示すように値は NULL となります。広告主/データプロバイダーはこのタイムスタンプ値を使って、どのUID2 を再生成する必要があるかを判断できます。

select * from AUDIENCE_WITH_UID2;
+----+--------------------+----------------------------------------------+------------+-------------------------+
| ID | EMAIL              | UID2                                         | BUCKET_ID  | LAST_UID2_UPDATE_UTC    |
+----+--------------------+----------------------------------------------+------------+-------------------------+
|  1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ  | 2021-03-01 00:00:00.000 |
|  2 | test1@uidapi.com   | Q4A5ZBuBCYfuV3Wd8Fdsx2+i33v7jyFcQbcMG/LH4eM= | ad1ANEmVZ  | 2021-03-03 00:00:00.000 |
|  3 | test2@uidapi.com   | NULL                                         | NULL       | NULL                    |
+----+--------------------+----------------------------------------------+------------+-------------------------+

欠落しているまたは古い UID2 を見つけるには、デフォルトのデータベースとスキーマ名 を使用する次のクエリ例を使用します。

広告主ソリューションのクエリー:

select a.*, b.LAST_SALT_UPDATE_UTC
  from AUDIENCE_WITH_UID2 a LEFT OUTER JOIN UID2_PROD_ADV_SH.ADV.UID2_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;

データプロバイダーソリューションのクエリー:

select a.*, b.LAST_SALT_UPDATE_UTC
  from AUDIENCE_WITH_UID2 a LEFT OUTER JOIN UID2_PROD_DP_SH.DP.UID2_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;

クエリー結果:

以下の表は、レスポンスに含まれる各項目を表たものです。以下の ID1 の例で示すように、結果には EMAIL、UID2、BUCKET_ID、LAST_UID2_UPDATE_UTC、LAST_SALT_UPDATE_UTCが含まれます。ID 2 は、対応する UID2 が最後のバケット更新の後に生成されたため、情報は返されません。ID 3 は、UID2 が存在しないため、NULL値が返されます。

+----+--------------------+----------------------------------------------+------------+-------------------------+-------------------------+
| ID | EMAIL              | UID2                                         | BUCKET_ID  | LAST_UID2_UPDATE_UTC    | LAST_SALT_UPDATE_UTC    |
+----+--------------------+----------------------------------------------+------------+-------------------------+-------------------------+
|  1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ  | 2021-03-01 00:00:00.000 | 2021-03-02 00:00:00.000 |
|  3 | test2@uidapi.com   | NULL                                         | NULL       | NULL                    | NULL                    |
+----+--------------------+----------------------------------------------+------------+-------------------------+-------------------------+

Migration Guide​

FN_T_UID2_IDENTITY_MAP_EMAIL 関数と FN_T_UID2_IDENTITY_MAP_EMAIL_HASH 関数を使用している場合は、できるだけ早く FN_T_UID2_IDENTITY_MAP 関数に移行することをお勧めします。この関数は、他の2つの関数が行うことをすべて行い、その他の改良も組み込まれています。

FN_T_UID2_IDENTITY_MAP 関数の利点:

  • 電話番号とハッシュ化された電話番号の両方のマッピングをサポートしています。
  • ユーザーのオプトアウトをサポートしました。
  • UNMAPPED という新しいカラムが追加されました。何らかの理由で DII を UID2 にマッピングできない場合、この列にはその理由についての情報が含まれます。詳細については、Values for the UNMAPPED Column を参照してください。

このセクションには、新機能へのアップグレードに役立つ以下の情報が含まれています:

Changing Existing Code​

このセクションのコードスニペットは、以前の関数がどのように実装されているか、そして新しい関数を使用するためにどのように更新できるかを示す Before / After の例です。

Example for mapping unhashed emails​

Before:

FN_T_UID2_IDENTITY_MAP_EMAIL(EMAIL)

After:

FN_T_UID2_IDENTITY_MAP(EMAIL, 'email')

Example for mapping unhashed emails​

Before:

FN_T_UID2_IDENTITY_MAP_EMAIL_HASH(EMAIL_HASH)

After:

FN_T_UID2_IDENTITY_MAP(EMAIL_HASH, 'email_hash')

Using the Values for the UNMAPPED Column​

新しい関数を実装したら、FN_T_UID2_IDENTITY_MAPが返す UNMAPPED カラムをチェックすることができます。DII が UID2 にマッピングできなかった場合、この列にはその理由が示されます。

値とその説明の詳細については、Values for the UNMAPPED Column を参照してください。

Usage for UID2 Sharers​

UID2 sharer とは、UID2 を他の参加者と Sharing (共有)したい参加者のことです。広告主とデータプロバイダーは、Snowflake を介して、UID2 を他の認可された UID2 を sharing する参加者と共有することができます。詳細については、UID2 Sharing: Overview を参照してください。

Sharing する参加者は、他の参加者に送信する前に、raw UID2 を暗号化して UID2 Tokenに変換しなければなりません。

IMPORTANT: このプロセスで生成される UID2 Token は共有専用です—ビッドストリームでは使用できません。ビッドストリーム用のトークン生成には別のワークフローがあります: Tokenized Sharing in the Bid Stream を参照してください。

以下のシナリオは UID2 sharing に対応しています:

Encrypt Tokens​

raw UID2 を UID2 Token に暗号化するには、関数 FN_T_UID2_ENCRYPT を使用します。該当する接頭辞を使用して自分の役割を示します:s

  • 広告主の場合: ADV.FN_T_UID2_ENCRYPT
  • データプロバイダーの場合: DP.FN_T_UID2_ENCRYPT
ArgumentData TypeDescription
RAW_UID2varchar(128)UID2 Token に暗号化する raw UID2。

クエリーに成功すると、指定された raw UID2 について以下の情報が返されます。

Column NameData TypeDescription
UID2_TOKENTEXT値は次のいずれかです:
  • 暗号化成功: raw UID2 を含む UID2 Token。
  • 暗号化失敗: NULL
ENCRYPTION_STATUSTEXT値は次のいずれかです。
  • 暗号化成功: NULL
  • 暗号化失敗: raw UID2 が暗号化されなかった理由。例: INVALID_RAW_UID2 または INVALID NOT_AUTHORIZED_FOR_MASTER_KEY。
    詳細については、Values for the ENCRYPTION_STATUS Column を参照してください。

Values for the ENCRYPTION_STATUS Column​

次の表は、ENCRYPTION_STATUS 列の有効な値です。

ValueMeaning
NULLThe raw UID2 was successfully encrypted.
MISSING_OR_INVALID_RAW_UID2raw UID2 の暗号化に成功しました。
INVALID_RAW_UID2raw UID2 が無効です。
MISMATCHING_IDENTITY_SCOPEraw UID2 が不正な ID スコープに属している。例えば、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 に暗号化する方法を示しています。

単一の raw UID2 に対する広告主ソリューションクエリ:

select UID2_TOKEN, ENCRYPTION_STATUS from table(UID2_PROD_ADV_SH.ADV.FN_T_UID2_ENCRYPT('2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU='));

単一の raw UID2 に対するデータプロバイダのソリューションクエリ:

select UID2_TOKEN, ENCRYPTION_STATUS from table(UID2_PROD_DP_SH.DP.FN_T_UID2_ENCRYPT('2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU='));

単一の raw UID2 に対するクエリー結果:

+------------------------+-------------------+
| UID2_TOKEN             | ENCRYPTION_STATUS |
+--------------------------------------------+
| A41234<rest of token>  | NULL              |
+--------------------------------------------+

Encrypt Token Request Example - Multiple Raw UID2s​

以下のクエリは、default database and schema names を使用して、複数の raw UID2 を暗号化する方法を示しています。

複数の raw UID2 に対する広告主ソリューションのクエリ:

select a.RAW_UID2, t.UID2_TOKEN, t.ENCRYPTION_STATUS from AUDIENCE_WITH_UID2 a, lateral UID2_PROD_ADV_SH.ADV.FN_T_UID2_ENCRYPT(a.RAW_UID2) t;

複数の raw UID2 に対するデータプロバイダのソリューションクエリ:

select a.RAW_UID2, t.UID2_TOKEN, t.ENCRYPTION_STATUS from AUDIENCE_WITH_UID2 a, lateral UID2_PROD_DP_SH.DP.FN_T_UID2_ENCRYPT(a.RAW_UID2) t;

複数の raw UID2 に対するクエリー結果:

以下の表は、raw UID2 が NULL の場合の NULL 値を含め、レスポンスの各項目を示しています。

+----+----------------------------------------------+-----------------------+-----------------------------+
| ID | RAW_UID2                                     | UID2_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_UID2_DECRYPT を使用します。該当する接頭辞を使用して自分の役割を示します:

  • 広告主の場合: ADV.FN_T_UID2_DECRYPT
  • データプロバイダーの場合: DP.FN_T_UID2_DECRYPT
ArgumentData TypeDescription
UID2_TOKENvarchar(512)raw UID2 に復号する UID2 Token です。

クエリーに成功すると、指定された UID2 Token について以下の情報が返されます。

Column NameData TypeDescription
UID2TEXT値は次のいずれかです:
  • 復号化成功: UID2 Token に対応する raw UID2。
  • 復号化失敗: NULL.
SITE_IDINT値は次のいずれかです:
  • 復号化成功: トークンを暗号化した UID2 参加者の識別子。
  • 復号化失敗: NULL.
DECRYPTION_STATUSTEXT値は次のいずれかです:
  • 復号化成功: NULL.
  • 暗号化失敗: UID2 Token が復号化されなかった理由。例えば、EXPIRED_TOKEN です。
    詳細については、Values for the DECRYPTION_STATUS Column を参照してください。

NOTE: UID2 Token がうまく復号化できない場合、この関数は行を返しません。

Values for the DECRYPTION_STATUS Column​

次の表は、DECRYPTION_STATUS 列の有効な値です。

ValueMeaning
NULLUID2トークンは正常に復号化されました。
EXPIRED_TOKENUID2 Token の有効期限が切れています。

Decrypt Token Request Example—Single UID2 Token​

以下のクエリは、default database and schema names を使用して、単一の UID2 Token を raw UID2 に復号する方法を示しています。

単一の UID2 Token に対する広告主ソリューションクエリ:

select UID2, SITE_ID, DECRYPTION_STATUS from table(UID2_PROD_ADV_SH.ADV.FN_T_UID2_DECRYPT('A41234<rest of token>'));

単一の UID2 Token に対するデータプロバイダのソリューションクエリ:

select UID2, SITE_ID, DECRYPTION_STATUS from table(UID2_PROD_DP_SH.DP.FN_T_UID2_DECRYPT('A41234<rest of token>'));

単一の UID2 Token に対するクエリー結果:

+----------------------------------------------+-------------------+
| UID2                                         | DECRYPTION_STATUS |
+----------------------------------------------+-------------------+
| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | NULL              |
+----------------------------------------------+-------------------+

Decrypt Token Request Example—Multiple UID2 Tokens​

以下のクエリは、default database and schema names を使用して、複数の UID2 Token を復号化する方法を示しています。

複数の UID2 Token に対する広告主ソリューションクエリ:

select a.ID, b.UID2, b.SITE_ID, CASE WHEN b.UID2 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_ADV_SH.ADV.FN_T_UID2_DECRYPT(UID2_TOKEN) t) b
  on a.ID=b.ID;

複数の UID2 Token に対するデータプロバイダのソリューションクエリ:

select a.ID, b.UID2, b.SITE_ID, CASE WHEN b.UID2 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_DP_SH.DP.FN_T_UID2_DECRYPT(UID2_TOKEN) t) b
  on a.ID=b.ID;

複数の UID2 Token に対するクエリー結果:

以下の表は、NULL 値や期限切れの UID2 Token など、レスポンスの各項目を示しています。

+----+----------------------------------------------+----------+-------------------+
| ID | UID2                                         | 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 を使用している場合に、sharing がどのように機能するかの例を示しています。このシナリオ例では、広告主(送信者) が raw UID2 (AUDIENCE_WITH_UID2) を持つオーディエンステーブルを持っており、Snowflake Secure Data Sharing 機能を使ってテーブル内のデータをデータプロバイダー(受信者) が利用できるようにしたいと考えています。

Sender Instructions​

  1. AUDIENCE_WITH_UID2_TOKENS という名前の新しいテーブルを作成します。
  2. AUDIENCE_WITH_UID2S テーブルの raw UID2 を暗号化し、その結果を AUDIENCE_WITH_UID2_TOKENS テーブルに格納します。例えば、以下のクエリはこのタスクを達成するのに役立ちます: 
    insert into AUDIENCE_WITH_UID2_TOKENS select a.ID, t.UID2_TOKEN from AUDIENCE_WITH_UID2S a, lateral UID2_PROD_ADV_SH.ADV.FN_T_UID2_ENCRYPT(a.RAW_UID2) t;
  3. 安全な共有を作成し、AUDIENCE_WITH_UID2_TOKENS テーブルへのアクセス権を付与します。
  4. 受信者に安全な共有へのアクセスを許可します。

WARNING: 共有した UID2 Token の期限切れを避けるため、送信者は暗号化後できるだけ早く、新しく暗号化された UID2 Token を受信者に送るべきです。

Receiver Instructions​

  1. 送信者がアクセス権を提供した安全な共有からデータベースを作成します。
  2. RECEIVED_AUDIENCE_WITH_UID2 という新しいテーブルを作成します。
  3. 共有された AUDIENCE_WITH_UID2_TOKENS テーブルからトークンを復号化し、その結果を RECEIVED_AUDIENCE_WITH_UID2 テーブルに格納します。例えば、以下のようなクエリが考えられます: 
    insert into RECEIVED_AUDIENCE_WITH_UID2
      select a.ID, b.UID2, CASE WHEN b.UID2 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_DP_SH.DP.FN_T_UID2_DECRYPT(UID2_TOKEN) t) b
        on a.ID=b.ID;

WARNING: 共有された UID2 Token の期限切れを避けるため、受信者は、送信者から UID2 Token が利用可能になり次第、復号化すべきです。