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

POST /v3/identity/map

複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックしたり、raw UID2 の更新が可能な時期を確認したり、現在の raw UID2 が発行されてから 90 日未満の場合に前の UID2 を表示することもできます。

Used by: このエンドポイントは、主に広告主とデータプロバイダーによって使用されます。詳細は、Advertiser/Data Provider Integration Overview を参照してください。

UID2 のオプトアウト手順とユーザーがオプトアウトする方法は、User Opt-Out を参照してください。

Version​

このドキュメントは、エンドポイントの最新版であるバージョン 3 を対象としています。

必要に応じて、以前のバージョンのドキュメントも利用可能です: POST /v2/identity/map を参照してください。

Batch Size and Request Parallelization Requirements​

以下が必要な情報です:

  • 最大リクエストサイズは 1MB です。
  • 大量のメールアドレス、電話番号、またはそれぞれのハッシュをマッピングする場合は、1 バッチあたり最大 5,000 アイテムの 順次 バッチで送信します。
  • Private Operator を使用していない限り、バッチを並行して送信しないでください。つまり、単一の HTTP 接続を使用し、ハッシュ化またはハッシュされていない Directly Identifying Information (DII) 値のバッチを連続して送信し、複数の並行接続を作成しないでください。
  • メールアドレス、電話番号、またはそれぞれのハッシュのマッピングを必ず保存してください。
    マッピングを保存しないと、数百万のメールアドレスや電話番号をマッピングする際に処理時間が大幅に増加する可能性があります。ただし、実際に更新が必要なマッピングのみを再計算すると、UID2 の約 1/365 が毎日更新されるため、総処理時間が短縮されます。詳細は、Advertiser/Data Provider Integration Overview と FAQs for Advertisers and Data Providers を参照してください。

Request Format​

POST '{environment}/v3/identity/map'

認証の詳細は、Authentication and Authorization を参照してください。

important

すべてのリクエストをシークレットを使用して暗号化する必要があります。詳細は、Encrypting Requests and Decrypting Responses を参照してください。

Path Parameters​

Path ParameterData TypeAttributeDescription
{environment}string必須テスト（インテグレーション）環境: https://operator-integ.uidapi.com
本番環境: 最適な選択は、ユーザーの所在地によって異なります。ユースケースに適した URL の選択方法や、有効なベース URL の一覧は、Environments を参照してください。
注記

インテグレーション環境と本番環境では、異なる API Key が必要です。各環境の認証情報の取得方法は、Getting Your Credentials を参照してください。

Unencrypted JSON Body Parameters​

important

暗号化を行う際には、リクエストの JSON 本文に次の 4 つのパラメータのうち、いずれか 1 つ をキーと値のペアとして含めてください。

Body ParameterData TypeAttributeDescription
emailstring array条件付きで必須マッピングするメールアドレスのリスト。
email_hashstring array条件付きで必須マッピングする 正規化済み メールアドレスの Base64 エンコードされた SHA-256 ハッシュのリスト。
phonestring array条件付きで必須マッピングする 正規化済み 電話番号のリスト。
phone_hashstring array条件付きで必須マッピングする 正規化済み 電話番号の Base64 エンコードされた SHA-256 ハッシュのリスト。

Request Examples​

以下の例は、POST /v3/identity/map エンドポイントへの暗号化されていない JSON リクエスト本文の例です:

{
    "email":[
        "user@example.com",
        "user2@example.com"
    ],
    "phone":[
        "+12345678901",
        "+441234567890"
    ]
}
{
    "email_hash":[
        "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
        "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU="
    ],
    "phone_hash":[
        "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
        "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ="
    ]
}

以下は、電話番号の POST /v3/identity/map エンドポイントへの暗号化されたリクエストの例です:

echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v3/identity/map [YOUR_CLIENT_API_KEY] [YOUR_CLIENT_SECRET]

詳細および異なるプログラミング言語でのコード例は、Encrypting Requests and Decrypting Responses を参照してください。

Decrypted JSON Response Format​

注記

HTTP ステータスコードが 200 の場合、レスポンスは暗号化されます。それ以外の場合、レスポンスは暗号化されません。

復号化に成功したレスポンスは、指定されたメールアドレス、電話番号、またはそれぞれのハッシュに対する現在の raw UID2、以前の raw UID2、および更新タイムスタンプを返します。

レスポンスの配列は、入力配列の順序を保持します。レスポンス配列の各要素は、対応するリクエスト配列の同じインデックスにある要素に直接マッピングされます。これにより、結果をその対応する入力と信頼性高く関連付けることができます。

raw UID2 にマッピングできない入力値は、マッピングできなかった理由を含むエラーオブジェクトにマッピングされます。マッピングに失敗するのは、DII が無効であるか、UID2 エコシステムからオプトアウトされている場合です。このような場合、レスポンスステータスは success ですが、raw UID2 は返されません。

以下の例は、入力と対応するレスポンスを示しています。

Input:

{
    "email": [
        "user@example.com",      // Corresponding UID2 rotated in the last 90 days
        "user2@example.com",     // Corresponding UID2 rotated more than 90 days ago
        "invalid email string",  // Invalid identifier
        "optout@example.com"     // DII is opted out
    ]
}

Response:

{
    "body":{
        "email": [
            {
                "u": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
                "p": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
                "r": 1735689600000
            },
            {
                "u": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=",
                "p": null,
                "r": 1735862400000
            },
            { "e": "invalid identifier" },
            { "e": "optout" }
        ],
      "email_hash": [],
      "phone": [],
      "phone_hash": []
    },
    "status": "success"
}

Response Body Properties​

レスポンス本文には、以下の表に示すプロパティのいずれかが含まれます。

Body ParameterData TypeDescription
emailマッピングされた DII オブジェクトの配列リクエスト内のメールアドレスのリストに対応するマッピングされた DII オブジェクトのリスト。
email_hashマッピングされた DII オブジェクトの配列リクエスト内のメールアドレスハッシュのリストに対応するマッピングされた DII オブジェクトのリスト。
phoneマッピングされた DII オブジェクトの配列リクエスト内の電話番号のリストに対応するマッピングされた DII オブジェクトのリスト。
phone_hashマッピングされた DII オブジェクトの配列リクエスト内の電話番号ハッシュのリストに対応するマッピングされた DII オブジェクトのリスト。

DII が正常にマッピングされた場合、マッピングされたオブジェクトには以下の表に示すプロパティが含まれます。

PropertyData TypeDescription
ustringリクエストで提供されたメールアドレスまたは電話番号に対応する raw UID2。
pstring以下のいずれか:
  • 現在の raw UID2 が過去 90 日以内にローテーションされた場合: 以前の raw UID2。
  • それ以外の場合: null。
rnumberraw UID2 を更新する可能性がある時刻を示す Unix タイムスタンプ（ミリ秒）。raw UID2 はこのタイムスタンプまで有効です。
注記

raw UID2 はリフレッシュタイムスタンプの前では変化しません。リフレッシュタイムスタンプの後、DII を再マッピングすると新しいリフレッシュタイムスタンプが返されますが、raw UID2 は変化する場合もあれば変化しない場合もあります。raw UID2 が複数のリフレッシュ間隔にわたって変化しない可能性もあります。

マッピングできなかった入力値に対しては、マッピングされたオブジェクトに以下の表に示すプロパティが含まれます。

PropertyData TypeDescription
estringマッピングできなかった理由。次のいずれかの値:
  • optout
  • invalid identifier

Response Status Codes​

以下の表は、status プロパティの値とその HTTP ステータスコードの対応を示しています。

StatusHTTP Status CodeDescription
success200リクエストは成功しました。レスポンスは暗号化されます。
client_error400リクエストに欠落または無効なパラメーターが含まれていました。
unauthorized401リクエストにベアラートークンが含まれていない、無効なベアラートークンが含まれている、またはリクエストされた操作を実行する権限のないベアラートークンが含まれていました。

status プロパティの値が success 以外の場合、message フィールドには問題に関する追加情報が提供されます。

Migration from POST /v2/identity/map​

以下のセクションでは、以前のバージョンからバージョン 3 への移行に関する一般的な情報とガイダンスを提供します:

Version 3 Improvements​

POST /identity/map エンドポイントのバージョン 3 では、v2 から以下の改善が行われています:

  • Support for multiple identity types: 1 回のリクエストでメールアドレスと電話番号の両方を処理できます。
  • Simpler refresh management: ソルトバケットを監視する代わりに、リフレッシュのタイムスタンプに達した raw UID2 を再マッピングするだけで済みます。ソルトバケットの監視は、別の API 呼び出しです。
  • Availability of previous raw UID2: ローテーション後 90 日間、以前の UID2 を見ることができます。
  • Improved performance: 新しい API バージョンでは、同じ量の個人データに対して必要な帯域幅が大幅に削減されています。

Key Differences Between v2 and v3​

以下の表は、バージョン間の主な違いを示しています。

Featurev2 Implementationv3 Implementation
必要なエンドポイント/v2/identity/map + /v2/identity/buckets/v3/identity/map のみ
リクエストごとのアイデンティティタイプ単一のアイデンティティタイプのみ複数のアイデンティティタイプ
リフレッシュ管理/identity/buckets エンドポイントを介してソルトバケットのローテーションをモニターrefresh_from タイムスタンプを過ぎたときに再マッピング
前の UID2 アクセス利用不可90 日間利用可能

Required Changes​

以前のバージョンからバージョン 3 へのアップグレードは、以下の手順に従ってください。

  1. Update Endpoint URL
  2. Update v3 Response Parsing Logic
  3. Replace Salt Bucket Monitoring with Refresh Timestamp Logic

1. Update Endpoint URL​

エンドポイント URL を更新して、/v3/ 実装を参照するようにしてください。以下の例を参照してください。

# Before (v2)
url = '/v2/identity/map'

# After (v3) 
url = '/v3/identity/map'

2. Update v3 Response Parsing Logic​

以下の例に従って、レスポンスの解析ロジックを更新してください。

v2 Response Parsing:

# v2: Process mapped/unmapped objects with identifier lookup
for item in response['body']['mapped']:
    raw_uid = item['advertising_id']
    bucket_id = item['bucket_id']
    original_identifier = item['identifier']
    # Store mapping using identifier as key
    store_mapping(original_identifier, raw_uid, bucket_id)

v3 Response Parsing:

# v3: Process array-indexed responses
for index, item in enumerate(response['body']['email']):
    original_email = request_emails[index]  # Use array index to correlate
    if 'u' in item:
        # Successfully mapped
        current_uid = item['u']
        previous_uid = item.get('p')  # Available for 90 days after rotation, otherwise None
        refresh_from = item['r']
        store_mapping(original_email, current_uid, previous_uid, refresh_from)
    elif 'e' in item:
        # Handle unmapped with reason
        handle_unmapped(original_email, item['e'])

3. Replace Salt Bucket Monitoring with Refresh Timestamp Logic​

ソルトバケットのモニタリングを更新して、refresh_from タイムスタンプをチェックし、raw UID2 の更新が必要なものを判断するコードに置き換えます。

以下の例は、リフレッシュタイムスタンプをチェックするための v3 アプローチの実装を示しています:

import time

def is_refresh_needed(mapping):
    now = int(time.time() * 1000)  # Convert to milliseconds
    return now >= mapping['refresh_from']

# Check individual mappings for refresh needs
to_remap = [mapping for mapping in mappings if is_refresh_needed(mapping)]
remap_identities(to_remap)

Additional Resources​

アイデンティティマッピングの一般的な情報については、Advertiser/Data Provider Integration Overview を参照してください。

特定の SDK の移行ガイダンスについては、以下を参照してください:

Snowflake に関する情報は、Snowflake Integration Guide を参照してください。