Digital Platform API - BSS AVRO ファイル形式
このドキュメントでは、AVRO ファイル形式を使用して対象ユーザー ファイルを準備し、データをプラットフォームにオンボードする方法について説明します。 拡張 ID と発行元が指定した ID を含む対象ユーザーをアップロードするには AVRO が必要であり、従来の BSS ファイル形式では、新しいユーザー ID の種類はサポートされていません。
- セグメントは、 セグメント サービスを使用して作成できます。
- 対象ユーザー ファイルは、 Batch Segment Service を介してセグメントにアップロードできます。
ベスト プラクティス
- 推奨されるファイル サイズ: 1 ファイルあたり 100 から 300 mb
- 推奨されるファイル圧縮: deflate
- 推奨される配信方法: パッシブ セグメントのアップロード (アカウント マネージャーにアクセスする)
- セグメントの更新: 完全な対象ユーザー メンバーシップを再度送信する代わりに、既存のセグメントの変更のみをアップロードできます。 これにより、データ サイズが縮小され、1 日のアップロード制限に達する可能性が高くなります。
手順の概要
- ユーザー セグメント レコードについて
- AVRO ツール ライブラリをインストールする
- Xandr AVRO スキーマ ファイルをダウンロードする
- AVRO 対象ユーザー ファイルを生成する
ユーザー セグメント レコード
ユーザー レコードには、最上位の 2 つの要素があります。
- ユーザー ID (uid)
- セグメントの配列
ユーザー ID の種類
uid レコードごとにアップロードできる ID の種類は 1 つだけです (Xandr ユーザー ID、IFA、デバイス ID、eid など)。
このセクションでは、サポートされているさまざまなユーザー ID の種類とその説明、および Java ライブラリと Python ライブラリの例を見つけます。
AppNexus/Xandr User ID (ANID)
Xandr ID (とも呼ばれます user_id_64)。
Java ライブラリの例:
{"uid":
{"long":12345},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}
Python ライブラリの例:
{'uid': 64, 'segments': [seg1]}
Device ID
ifa (広告用識別子) と同様のユーティリティ。 オンボードされているモバイル デバイスの種類を示します。 レコードは device_id 、次の 2 つのフィールドで構成されます。
- domain (enum) - 使用できる値は idfa、sha1udid、md5udid、openudid、aaid、windowsadid、rida、tifa、vida、lgudid です。
- id (string)
Java ライブラリの例:
{"uid":
{"device_id":
{"id":"958cba26-f338-43f3-8bb0-ed821582daae",
"domain":"idfa"}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}
Python ライブラリの例:
{'uid': {'id': 'qweqeqweq', 'domain': 'idfa'}, 'segments': [seg1]}
Extended ID's(eid) or Publisher-provided ID's(PPID)
拡張 ID - オンボードされているユニバーサル ID またはパブリッシャー ID の種類を示します。 eid レコードは、次の 2 つのフィールドで構成されます。
- source (string) - ID のソース。 許可される値は、アクセス許可を持つメンバー定義のソースです。
- id (string) - パブリッシャーまたは業界 ID。
現在、これらは、対象ユーザーのオンボードに使用できる唯一の 2 つです。
Java ライブラリの例:
{"uid":
{"eid":
{"source":"liveramp.com",
"id":"123123123"}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}
Python ライブラリの例:
{'uid': {'id': 'qweqeqweq', 'source': 'liveramp.com'}, 'segments': [seg1]}
External ID
外部 ID - オンボードされているメンバー定義識別子を示します。 レコードは external_id 、次の 2 つのフィールドで構成されます。
- member_id (int) - を所有
external_idするメンバーのメンバー ID。 - id (string) - の対応する値
member_id。
Java ライブラリの例:
{"uid":
{"external_id":
{"id":"clientid1",
"member_id":958}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}
Python ライブラリの例:
{'uid': {'id': 'extid1', 'member_id': 914}, 'segments': [seg1]}
Identifier for Advertising (or IFA)
アドバタイズの識別子 - オンボードされているデバイスの種類を示します。 ifa レコードは、次の 2 つのフィールドで構成されます。
- type (string) - ID の型。
- id (string) - IFA ID。UUID 形式の IFA を表します。
サポートされている ifa 型については、「 デバイス拡張機能オブジェクト 」を参照してください
Java ライブラリの例:
{"uid":
{"ifa":
{"id":"99136473264876328",
"type":"atif"}},
"segments":
[{"id":123,
"code":"",
"member_id":0,
"expiration":0,
"timestamp":0,
"value":0}]}
Python ライブラリの例:
{'uid': {'id': 'qweqeqweq', 'type': 'atif'}, 'segments': [seg1]}
Segments オブジェクト
セグメント オブジェクトの配列を作成することで、同じ uid レコード内の複数のセグメントにアップロードできます。
| File | 型 | 説明 |
|---|---|---|
code |
string | Xandr セグメント コード。 |
expiration |
int | セグメントの有効期限 (分単位)。 に設定します。 - 0 最大有効期限 (180 日)。 - -1 セグメントの削除。 - -2 既定のメンバーの有効期限。 |
id |
int | Xandr セグメント ID |
member_id |
int | セグメントのメンバー ID。 コードが指定されている場合は必須 |
timestamp |
long | セグメントのアクティブ化時間 (エポックからの秒数)。 セグメントが "ライブ" になるタイミングを指定します。 セグメントをすぐにアクティブにするには、0 に設定します |
value |
int | セグメント値 |
AVRO ツール ライブラリのインストール
- Java ライブラリ
curl -o http://archive.apache.org/dist/avro/avro-1.10.1/java/avro-tools-1.10.1.jar
- Python ライブラリ
python3 -m pip install avro
Xandr Avro スキーマをダウンロードする
Xandr Avro スキーマは 、ここからダウンロードできます。
AVRO 対象ユーザー ファイルを生成する
Java ライブラリと Python ライブラリの使用例については、以下を参照してください。
Java の例
対象ユーザー ファイルを作成する
{"uid":{"long":12345},"segments":[{"id":123,"code":"","member_id":0,"expiration":0,"timestamp":0,"value":0}]}
{"uid":{"external_id":{"id":"clientid1","member_id":958}},"segments":[{"id":123,"code":"","member_id":0,"expiration":0,"timestamp":0,"value":0}]}
{"uid":{"ifa":{"id":"99136473264876328","type":"atif"}},"segments":[{"id":123,"code":"","member_id":0,"expiration":0,"timestamp":0,"value":0}]}
{"uid":{"device_id":{"id":"958cba26-f338-43f3-8bb0-ed821582daae","domain":"idfa"}},"segments":[{"id":123,"code":"","member_id":0,"expiration":0,"timestamp":0,"value":0}]}
{"uid":{"eid":{"source":"liveramp.com","id":"123123123"}},"segments":[{"id":123,"code":"","member_id":0,"expiration":0,"timestamp":0,"value":0}]}
対象ユーザー ファイルを AVRO に変換する
次のコマンドを実行します。
java -jar avro-tools-1.10.1.jar fromjson --codec deflate --schema-file xandr_schema.avsc sample.json > sample.avro
場所
- xandr_schema.avsc = 指定された Xandr Avro スキーマ ファイル。
- sample.json = 対象ユーザー ファイル。
- and sample.avro = 出力 AVRO ファイル
Python の例
注:
この例は Python Avro ライブラリ用であり、 Fast Avro ライブラリと混同しないでください。
Python Avro ライブラリでは、uid 共用体の型名は使用されません。 代わりに、フィールド名の完全一致によって uid 型が決定されます。
例:
{'uid': {'id': 'qweqeqweq', 'domain': 'idfa'}, 'segments': […]}
- Fast Avro ライブラリでは、ヒントを使用して、Java ライブラリと同様の uid の正確な種類を指定します。
例:
{'uid': ('external_id', {'id':'exitd1', 'member_id': 914}), 'segments': [{'expiration': 259200, 'id': 25815407}]}
- DataFileWriter.append() は、JSON ではなく Python ディクショナリ (dict) 型を受け入れます。
AVRO 対象ユーザー ファイルの作成
Python Avro ライブラリを使用したサンプル スクリプト:
import avro.schema
from avro.datafile import DataFileReader, DataFileWriter
from avro.io import DatumReader, DatumWriter
# the supplied xandr schema
schema = avro.schema.parse(open("xandr_schema.avsc", "rb").read())
# output avro file
writer = DataFileWriter(open("sample.avro", "wb"), DatumWriter(), schema, codec=’deflate’)
# segments
seg1 = {'id': 1000, 'code': '', 'member_id': 0, 'expiration': 0, 'timestamp': 0, 'value': 0}
# anid
writer.append({'uid': 64, 'segments': [seg1]})
# external id
writer.append({'uid': {'id': 'exitd1', 'member_id': 914}, 'segments': [seg1]})
# idfa
writer.append({'uid': {'id': 'qweqeqweq', 'domain': 'idfa'}, 'segments': [seg1]})
# eid (or ppid)
writer.append({'uid': {'id': 'qweqeqweq', 'source': 'liveramp.com'}, 'segments': [seg1]})
writer.append({'uid': {'id': 'qweqeqweq', 'source': 'netid.de'}, 'segments': [seg1]})
writer.close()