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

POST /identity/map

複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 とソルトバケット ID にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます

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

Batch Size and Request Parallelization Requirements

知っておくべきことは以下のとおりです:

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

Request Format

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

IMPORTANT: すべてのリクエストは、秘密鍵を使用して暗号化する必要があります。詳細と Python スクリプトの例は、リクエストの暗号化とレスポンスの復号化 を参照してください。

Path Parameters

Path ParameterData TypeAttributeDescription
{environment}string必須テスト環境: https://operator-integ.uidapi.com
本番環境: https://prod.uidapi.com
リージョンごとのオペレーターを含む全リストは Environments を参照してください。

NOTE: インテグレーション環境と本番環境では、異なる APIキー が必要です。

Unencrypted JSON Body Parameters

IMPORTANT: リクエストを暗号化するときは、以下の 4 つの条件パラメータのうち、 1つ だけをリクエストの JSON ボディにキーと値のペアとして含める必要がります。

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

Request Examples

以下は、各パラメータの暗号化されていない JSON リクエストボディの例で、このうちの 1 つを ID マッピングリクエストに含める必要があります:

{
"email": [
"user@example.com",
"user2@example.com"
]
}
{
"email_hash": [
"eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=",
"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="
]
}
{
"phone": [
"+1111111111",
"+2222222222"
]
}
{
"phone_hash": [
"eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=",
"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="
]
}

以下は、メールアドレスハッシュに対する暗号化された ID マッピングリクエストの例です:

echo '{"phone": ["+1111111111", "+2222222222"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk= DELPabG/hsJsZk4Xm9Xr10Wb8qoKarg4ochUdY9e+Ow=

詳細と Python スクリプトの例は、リクエストの暗号化とレスポンスの復号化 を参照してください。

Decrypted JSON Response Format

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

復号化に成功すると、指定したメールアドレス、電話番号、またはそれぞれのハッシュに対する raw UID2 とソルトバケット ID が返されます。

{
"body": {
"mapped": [
{
"identifier": "eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=",
"advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
"bucket_id": "a30od4mNRd"
},
{
"identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=",
"bucket_id": "ad1ANEmVZ"
}
]
},
"status": "success"
}

一部の識別子が無効と判断された場合、それらの識別子は "unmapped" リストとしてレスポンスに含まれる。この場合でも、レスポンスステータスは "success" となります。すべての識別子がマッピングされた場合、"unmapped"リストはレスポンスに含まれません。

{
"body": {
"mapped": [
{
"identifier": "eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=",
"advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
"bucket_id": "a30od4mNRd"
}
],
"unmapped": [
{
"identifier": "some@malformed@email@hash",
"reason": "invalid identifier"
}
]
},
"status": "success"
}

一部の識別子が UID2 エコシステムからオプトアウトしている場合、オプトアウトした識別子は、見つかった無効な識別子とともに "unmapped" リストに移動されます。この場合でも、レスポンスステータスは "success" です。

{
"body": {
"mapped": [
{
"identifier": "eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=",
"advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
"bucket_id": "a30od4mNRd"
}
],
"unmapped": [
{
"identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"reason": "optout"
}
]
},
"status": "success"
}

Response Body Properties

PropertyData TypeDescription
identifierstringリクエストボディで指定されたメールアドレス、電話番号、またはそれぞれのハッシュです。
advertising_idstring対応する Advertising ID (raw UID2) です。
bucket_idstringraw UID2 の生成に使用したソルトバケットの ID です。

Response Status Codes

次の表は、status プロパティの値と、それに対応する HTTP ステータスコードの一覧です。

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

status の値が success 以外であれば、 message フィールドにその問題に関する追加情報が表示されます。