バッチファイル形式

記録構造

各レコードには以下の必須フィールドが含まれなければなりません:

フィールド

種類

必須

概要

recordType

ストリング

はい

レコードの種類。プロフィール記録には profile を使いましょう。大文字に区別されない。

identifiers

アレイ

はい

識別子オブジェクトの配列で、それぞれにproviderとidフィールドがあります。識別子は、設定された識別子ルールと空でないidに一致するproviderを持ちなければなりません。

各レコードには、以下のフィールドのうち少なくとも1つが含まれていなければなりません。

フィールド

種類

必須

概要

contact

目的

いいえ

プロフィールの連絡先情報( firstName、 lastName、 emailなど)があります。

extensions

目的

いいえ

プロファイルのカスタム属性。組織が追跡する追加データにはこのフィールドをご利用ください。

!重要レコードペイロードは、少なくとも1つの非ヌルフィールドをcontactまたはextensionsの中に含めなければなりません。更新可能なフィールドがないレコードはNO_UPDATABLE_FIELDSエラーコードで失敗します。

以下の表は、contactオブジェクトおよびextensionsオブジェクトで利用可能なフィールドを説明します。

入力例

以下の例は、12のプロファイルレコードを持つJSONLファイルを示しています。

{"recordType":"profile","identifiers":{"provider":"email","id":"[email protected]"},"contact":{"firstName":"Alice1","lastName":"Smith2"}, "extensions":{"where": "In the wonderland"}} {"recordType":"profile","identifiers":{"provider":"email","id":"[email protected]"},"contact":{"firstName":"Alice2","lastName":"Smith2"}, "extensions":{"where": "In the wonderland1"}} {"recordType":"profile","identifiers":{"provider":"email","id":"[email protected]"},"contact":{"firstName":"Alice3","lastName":"Smith2"}, "extensions":{"where": "In the wonderland2"}} {"recordType":"profile","identifiers":{"provider":"email","id":"[email protected]"},"contact":{"firstName":"Alice4","lastName":"Smith2"}, "extensions":{"where": "In the wonderland3"}} {"recordType":"profile","identifiers":{"provider":"email","id":"[email protected]"},"contact":{"firstName":"Alice5","lastName":"Smith2"}, "extensions":{"where": "In the wonderland4"}} {"recordType":"profile","identifiers":{"provider":"userid","id":"crm-0042"},{"provider":"email","id":"[email protected]"},"contact":{"firstName":"Bob","lastName":"Jones"}} {"recordType":"profile","identifiers":{"provider":"userid","id":"crm-0044"},"contact":{"firstName":"James","lastName":"Red"}} {"recordType":"profile","identifiers":{"provider":"userid","id":"crm-0044"},"contact":{"firstName":"James","lastName":"Red"}} {"recordType":"profile","identifiers":{"provider":"userid","id":"crm-0044"},"contact":{"firstName":"James","lastName":"Red"}} {"recordType":"profile","identifiers":{"provider":"userid","id":"crm-0044"},"contact":{"firstName":"James","lastName":"Red"}} {"recordType":"profile","identifiers":{"provider":"userid","id":"crm-0044"},"contact":{"firstName":"James","lastName":"Red"}} {"recordType":"profile","identifiers":{"provider":"userid","id":"crm-0044"},"contact":{"firstName":"James","lastName":"Red"}}

この例では:

• レコード1から5まではそれぞれ単一の email 識別子を使用し、 contact と extensionsの両方が含まれています。
• レコード6は異なるプロバイダーからの識別子(userid と email)を持ち、オプションの extensions フィールドは省略されています。
• レコード7から12までは同一で、それぞれ単一の userid 識別子を持ち、 extensions フィールドはありません。

アイデンティティ解決の仕組み

1. システムは、環境ごとに設定されたアイデンティティルールに provider 一致する識別子のみをチェックします。認識されていないプロバイダーの識別子は解決時に無視されます。
2. 識別子の値は大文字差し区別がありません。例えば、 [email protected] と [email protected] は同じプロファイルに解決されます。
3. システムは各適格識別子を検索し、一致するプロファイルを探します。

解決の成果

一致するプロファイルが見つかりました

戦闘

概要

0

作成

システム生成のプロファイルIDで新しいプロファイルが作成されます。

1

アップデート

既存のプロファイルはレコードのデータで更新されます。

1人以上

失敗

識別子が複数の異なるプロファイルに解決されるため、 INCONSISTENT_IDENTIFIERS エラーコードでレコードが失敗します。

既存のプロファイルに新しい識別子を追加する

!重要バッチをアップロードする前に、SitecoreAI環境で 識別ルールを作成する 必要があります。認識されていないプロバイダーの識別子は無視されます。

複数のプロバイダーからの識別子を含むレコードの場合、プロファイルインポートはマッチしたプロファイルに新しい識別子を追加します。これにより、以前に別のプロバイダーによって識別されたプロファイルに新しい識別子タイプを関連付けることができます。

例えば、SitecoreAI環境でemailをデフォルトの識別子として使い、後にuseridの識別ルール(CRM ID)を作成する場合、各レコードにemailとuseridの両方の識別子を含むバッチをアップロードできます。プロファイルインポートは、email識別子を使って既存プロファイルに対してレコードを解決し、そのプロファイルに追加の識別子としてuseridを追加します。

例

既存のプロファイルに以下が含まれている場合:

{ "contact": { "firstName": "Alice1", "lastName": "Smith2" }, "extensions": { "where": "In the wonderland" } }

そして、入ってくる記録には以下が含まれます:

{ "contact": { "email": "[email protected]" }, "extensions": { "where": "Wonderland" } }

得られるプロファイルは次の通りです:

{ "contact": { "firstName": "Alice1", "lastName": "Smith2", "email": "[email protected]" }, "extensions": { "where": "Wonderland" } }

この例では、firstNameとlastNameは記録に含まれていなかったため保持されます。 emailは新しいフィールドとして追加され、extensions.whereは新しい値で上書きされます。

拡張データの更新

データ拡張はビジネス固有のキーバリューデータを保持します。アップデート時には、キーが一つずつマージされます。

既存のプロファイルに以下が含まれている場合:

{ "extensions": { "loyaltyTier": "Silver", "where": "In the wonderland" } }

そして、入ってくる記録には以下が含まれます:

{ "extensions": { "where": "Wonderland", "favoriteColor": "Blue" } }

得られるプロファイルは次の通りです:

{ "extensions": { "loyaltyTier": "Silver", "where": "Wonderland", "favoriteColor": "Blue" } }

この例では、loyaltyTierは入受信レコードに含まれていなかったため保持されます。whereは新しい値で上書きされます。 favoriteColorは新しいフィールドとして追加されます。

識別子の追加

identifiersアレイはシステム間でゲストを認識するものです。各項目にはproviderとidがあります。新しい識別子を送信すると、配列を置き換えるのではなく、既存の識別子に加えて追加されます。既存の識別子が新しいidとともに送信された場合、システムはそれを新しいプロファイルとして扱います。

既存のプロファイルに以下が含まれている場合:

{ "identifiers": { "provider": "email", "id": "[email protected]" }

}

そして、入ってくる記録には以下が含まれます:

{ "identifiers": { "provider": "email", "id": "[email protected]" }, { "provider": "crm", "id": "CRM-00042" }

}

得られるプロファイルは次の通りです:

{ "identifiers": { "provider": "email", "id": "[email protected]" }, { "provider": "crm", "id": "CRM-00042" }

}

既存の"email"識別子はそのまま残り、新しい"crm"識別子が付加されます。ここから、識別子の解決(IDENTITYイベントを通じて)は、識別子ルールで定義された順序で識別子が追加されたプロファイルをマッチングできます。

新しい識別子をアップロードする前に、新しい識別子で識別子ルールを作成する必要があります。

単一のフィールドを削除する

オブジェクト内の単一のフィールドを削除するには、そのキーをnullに設定してください。除去されるのは無効キーのみです。対象内の他のすべての場は保存されます。

既存のプロファイルに以下が含まれている場合:

{ "contact": { "firstName": "Alice1", "lastName": "Smith2", "email": "[email protected]" } }

そして、入ってくる記録には以下が含まれます:

{ "identifiers": { "provider": "email", "id": "[email protected]" } , "contact": { "firstName": "Alice1", "lastName": null, "email": "[email protected]" } }

得られるプロファイルは次の通りです:

{ "identifiers": { "provider": "email", "id": "[email protected]" } , "contact": { "firstName": "Alice1", "email": "[email protected]" } }

この例では、lastNameがnullに設定されているため削除されます。 firstNameとemailはヌル化されていないため保持されます。同じパターンが、extensionsの中の鍵にも当てはまります。

オブジェクト全体を削除する

オブジェクト全体を削除するには、contactかextensionsをnullに設定してください。両方をnullに設定しないでください。識別子は既存のプロファイルに解決されなければならず、更新後もcontactまたはextensionsのうち少なくとも1つがプロファイルに残っている必要があります。

既存のプロファイルに以下が含まれている場合:

{ "identifiers": { "provider": "email", "id": "[email protected]" } , "contact": { "firstName": "Alice1", "lastName": "Smith2" }, "extensions": { "loyaltyTier": "Silver", "where": "Wonderland" } }

そして、入ってくる記録には以下が含まれます:

{ "identifiers": { "provider": "email", "id": "[email protected]" } , "contact": { "firstName": "Alice1", "lastName": "Smith2" }, "extensions": null }

得られるプロファイルは次の通りです:

{ "identifiers": { "provider": "email", "id": "[email protected]" } , "contact": { "firstName": "Alice1", "lastName": "Smith2" } }

この例では、extensionsオブジェクト全体がnullに設定されているため削除されます。 contactは保持されます。

少なくとも1つのオブジェクトが必要です

記録は、contactとextensionsの両方をnullに記録するものは却下されます。 contactまたはextensionsのうち少なくとも1つは、レコードを処理するためのデータを含む必要があります。

以下のレコードはNO_UPDATABLE_FIELDSエラーコードで失敗します:

{ "identifiers": { "provider": "email", "id": "[email protected]" } , "contact": null, "extensions": null }

すべての削除操作には以下の制約が適用されます:

• すべてのレコードには有効な識別子が含まれなければなりません。 null または認識されない provider の識別子は解決時に無視され、有効な識別子が残らなければレコードは失敗します。
• contactまたはextensionsのうち少なくとも1つはコンテンツと共に存在しなければなりません。両方をnullに設定するとNO_UPDATABLE_FIELDSエラーコードが表示されます。

出力レコード構造

各出力レコードには以下のフィールドが含まれています:

フィールド

種類

概要

recordIndex

整数

入力ファイルのレコードのゼロベースのインデックスです。

id

文字列(UUID)

入力レコードからの相関ID(もし提供されていた場合)も含まれます。

recordType

ストリング

入力レコードからのレコードタイプ、例えば profile。型を解析する前にレコードが失敗した場合は省略します。

outcome

ストリング

処理の結果は、 CREATED、 UPDATED、または FAILED。

profileId

文字列(UUID)

プロファイルID。 CREATED と UPDATED の結果のためにプレゼントしましょう。

errorCode

ストリング

エラーコード。 FAILED 結果のためだけに存在する。記録 レベルのエラーコードを参照してください。

errorDescription

ストリング

人間が読みやすい誤りの説明。 FAILED 結果のためだけに存在する。

出力例

{"recordIndex"