Adobe Target Bulk Profile Update API

最終更新日： 2026年9月8日

トピック：
実装

作成対象：

開発者

Adobe Target 一括プロファイル更新APIを使用すると、バッチファイルを使用して、複数の訪問者のユーザープロファイルをWeb サイトに一括で更新できます。

Bulk Profile Update APIを使用すると、多くのユーザーのプロファイルパラメーターの形式で詳細な訪問者プロファイルデータを任意の外部ソースからTargetに簡単に送信できます。外部ソースには、顧客関係管理（CRM）システムや販売時点情報管理（POS）システムなどがあります。これらのシステムは、web ページでは通常は利用できません。

バージョン

URLの例

機能

http://CLIENTCODE.tt.omtrdc.net/m2/CLIENTCODE/profile/batchUpdate

プロファイルの一括更新のみサポートします。

http://CLIENTCODE.tt.omtrdc.net/m2/CLIENTCODE/v2/profile/batchUpdate

見つからない場合はプロファイルを作成します。
行ごとのステータス更新。

NOTE

Bulk Profile Update APIのバージョン 2 （v2）は現在のバージョンです。ただし、Targetは引き続きバージョン 1 （v1）をサポートします。

Target実装でExperience Cloud ID （ECID）を匿名訪問者のプロファイル IDの1つとして使用している場合は、バージョン 2 （v2）のバッチファイルでpcIdをキーとして使用しないでください。 pcIdをBulk Profile Update APIのv2と共に使用することは、ECIDに依存しないスタンドアロン Target実装のみを目的としています。
実装でプロファイル識別にECIDを使用し、バッチファイルのキーとしてpcIdを使用する場合は、APIのバージョン 1 （v1）を使用します。
実装でプロファイル識別にthirdPartyIdを使用する場合は、thirdPartyIdをキーとしてAPIのバージョン 2 （v2）を使用します。

Bulk Profile Update APIの利点

プロファイル属性の数に上限がありません。
サイト経由で送信されたプロファイル属性は、APIやその逆の方法で更新できます。

注意事項

バッチファイルの容量は 50 MB 未満にする必要があります。また、1 回にアップロードできる行数は 50 万行までです。
更新は通常1時間以内に行われますが、反映されるまでに24時間かかる場合があります。
以降のバッチで24時間にわたってアップロードできる行数に制限はありません。ただし、他のプロセスを効率的に実行するために、営業時間中は取り込みプロセスが調整される場合があります。
同じthirdPartyIdの間にmbox呼び出しがない連続したv2 バッチアップデート呼び出しは、最初のバッチアップデート呼び出しで更新されたプロパティを上書きします。
Adobeは、バッチプロファイルデータの100%がTargetにオンボーディングされて保持され、ターゲティングで使用できることを保証しません。現在の設計では、少数のデータ（大規模な生産バッチの最大0.1%）がオンボーディングまたは保持されない可能性があります。

バッチファイル

プロファイルデータを一括更新するには、バッチファイルを作成します。バッチファイルは、次のサンプルファイルと同様に、値をコンマで区切ったテキストファイルです。

batch=pcId,param1,param2,param3,param4
123,value1
124,value1,,,value4
125,,value2
126,value1,value2,value3,value4

NOTE

batch= パラメーターが必要です。ファイルの先頭で指定する必要があります。

POST呼び出しでこのファイルを参照して、Target サーバーにファイルを処理します。バッチファイルを作成する際は、次の点を考慮してください。

ファイルの最初の行では、列ヘッダーを指定する必要があります。
最初のヘッダーはpcIdまたはthirdPartyIdのいずれかである必要があります。 Marketing Cloud訪問者IDはサポートされていません。 pcIdはTargetが生成した訪問者IDです。 thirdPartyIdはクライアントアプリケーションで指定されたIDで、mbox呼び出しを通じてTargetにmbox3rdPartyIdとして渡されます。ここでthirdPartyIdと呼ぶ必要があります。
バッチファイルで指定するパラメーターと値は、セキュリティ上の理由から、UTF-8を使用してURL エンコードする必要があります。パラメーターと値は、HTTP リクエストを通じて処理するために他のエッジノードに転送できます。
パラメーターの形式はparamNameのみにする必要があります。パラメーターはTargetにprofile.paramNameとして表示されます。
Bulk Profile Update API v2を使用している場合は、各pcIdにすべてのパラメーター値を指定する必要はありません。プロファイルは、Targetに見つからないpcIdまたはmbox3rdPartyIdに対して作成されます。 v1を使用している場合、欠落しているpcIdまたはmbox3rdPartyIdのプロファイルは作成されません。詳しくは、以下の Bulk Profile Update API🔗の空の値の処理を参照してください。
バッチファイルの容量は 50 MB 未満にする必要があります。さらに、行の合計数は500,000を超えてはなりません。この制限により、サーバーに多すぎるリクエストが溢れるのを防ぐことができます。
アップロードできる属性の数に制限はありません。ただし、顧客属性、プロファイル API、Mbox内プロファイルパラメーター、プロファイルスクリプト出力を含む外部プロファイルデータの合計サイズは、64 KBを超えてはなりません。
パラメーターと値は、大文字と小文字を区別します。

URL エンコーディング要件 url-encoding

IMPORTANT

すべてのパラメーター名と値は、バッチを送信する前にURL エンコード済み（UTF-8）である必要があります。このバッチはContent-Type: application/x-www-form-urlencodedで送信され、本文はbatch=で始まります。エンコードされていない予約済み文字は、データではなくリクエスト構文として読み取られ、バッチを拒否、切り捨て、または破損する可能性があります。

batchIdが発行されていない「予期しないエラー」の応答が表示された場合は、トラブルシューティング手順について「プロファイルの一括更新APIが「予期しないエラー」を返す」を参照してください。

次の文字は、通常、プロファイル値に含まれますが、application/x-www-form-urlencoded データでは特別な意味を持ちます。エンコードされていないリクエストを送信すると、リクエストが失敗するか、明らかなエラーなしにデータが破損します。

文字

次としてエンコード

エンコードされていない送信の場合

%

%25

バッチ全体が却下されます。応答は、success=falseを含むHTTP 200を返し、「予期しないエラー」というメッセージが表示され、batchIdは発行されません。

&

%26

バッチは、最初の&で自動的に切り捨てられます。残りの行がドロップされ、部分的な更新または「バッチが空です」という応答が発生する可能性があります。

+

%2B

文字は無言でスペースに変換され、保存された値が破損します。

=

%3D

文字がフィールド境界と誤解釈される可能性があります。

例えば、値50% off & moreは50%25 off %26 moreとして送信する必要があります。

文字、数字、UTF-8 アクセント文字、および文字- . ! ~ _ * ( )はエンコーディングを必要としません。ただし、Adobeでは、曖昧さを避けるために、すべての値をエンコードすることをお勧めします。

HTTP POST リクエスト

Target エッジサーバーにHTTP POST リクエストを送信して、ファイルを処理します。次に、curl コマンドを使用したbatch.txt ファイルのHTTP POST リクエストの例を示します。

curl -X POST --data-binary @BATCH.TXT http://CLIENTCODE.tt.omtrdc.net/m2/CLIENTCODE/v2/profile/batchUpdate

要素の説明：

BATCH.TXTはファイル名です。 CLIENTCODEはTarget クライアントコードです。

クライアントコードがわからない場合は、Target ユーザーインターフェイスで、管理 > 実装をクリックします。クライアントコードは、アカウントの詳細セクションに表示されます。

応答を調べる

プロファイル APIは、「batchStatus」の下のリンクと共に、特定のバッチジョブの全体的なステータスを示す別のURLに処理用のバッチの送信ステータスを返します。

API応答の例

次のコードは、Profiles API応答の例です。

<response>
    <success>true</success>
    <batchStatus>http://mboxedge45.tt.omtrdc.net/m2/demo/profile/batchStatus?batchId=demo-1701473848678-13029383</batchStatus>
    <message>Batch submitted for processing</message>
</response>

エラーが発生した場合、応答にはsuccess=falseとエラーの詳細メッセージが含まれます。

デフォルトのバッチステータス応答

上記のbatchStatus URL リンクをクリックした場合のデフォルトの応答が成功すると、次のようになります。

<response><batchId>demo4-1701473848678-13029383</batchId><status>complete</status><batchSize>1</batchSize></response>

ステータスフィールドの期待値は次のとおりです。

ステータス

詳細

complete

プロファイルのバッチ更新リクエストが正常に完了しました。

不完全

プロファイルのバッチ更新リクエストはまだ処理中で、完了していません。

行き詰まり

プロファイルのバッチ更新リクエストが停止しているため完了できませんでした。

詳細なバッチステータス URL応答

上記のbatchStatus URLにパラメーターshowDetails=trueを渡すことにより、より詳細な応答を取得できます。

次に例を示します。

http://mboxedge45.tt.omtrdc.net/m2/demo/profile/batchStatus?batchId=demo-1701473848678-13029383&showDetails=true

詳細な回答

<response>
    <batchId>demo4-1701473848678-13029383</batchId>
    <status>complete</status>
    <batchSize>1</batchSize>
    <consumedCount>1</consumedCount>
    <successfulUpdates>1</successfulUpdates>
    <profilesNotFound>0</profilesNotFound>
    <failedUpdates>0</failedUpdates>
</response>

Bulk Profile Update APIでの空の値の処理 empty

Target Bulk Profile Update API （v1またはv2）を使用する場合は、システムが空のパラメーターまたは属性値をどのように処理するかを理解することが重要です。

期待される動作

既存のパラメーターまたは属性に空の値（“”"、null、または不足しているフィールド）を送信しても、プロファイルストアでそれらの値がリセットまたは削除されません。これは意図的なものです。

空の値は無視されます: APIは、不要または意味のない更新を避けるために、処理中に空の値をフィルタリングします。
既存のデータを消去しません: パラメーターに既に値がある場合、空の値を送信すると、値は変更されません。
空のみのバッチはスキップされます: バッチに空またはnull値のみが含まれる場合、完全に無視され、更新は適用されません。

追加情報

この動作は、Bulk Profile Update APIのv1とv2の両方に適用されます。

空の値を送信して属性をクリアまたは削除しようとすると、何の影響もありません。

明示的な属性削除のサポートは、APIの将来のバージョン（v3）で計画されていますが、現在は利用できません。

recommendation-more-help

target-dev-help-dev