--- title: "バッチファイル形式" slug: "batch-file-format" abstract: "プロファイルインポート操作のための入力および出力ファイルフォーマット仕様。" --- # バッチファイル形式 > !重要機能の利用可能性は段階的に展開される一環です。あなたの組織はまだこの機能に気づいていないかもしれません。環境が導入された際に利用可能になります。 プロファイルインポートは、入力ファイルと出力ファイルの両方に対してJSONライン(JSONL)形式を使用します。ファイル内の各行は独立したJSONオブジェクトです。このトピックでは、入力レコードの構造、同一性解決の仕組み、更新動作、出力結果のフォーマットについて説明します。 ## 入力ファイル形式 入力ファイルは以下の要件を満たす必要があります: - *エンコーディング:* UTF-8。 - *フォーマット:* JSON行(JSONL)。1行につき1つのJSONオブジェクトで、後尾にコンマを付けないこと。 - *サイズ:* 1ファイルあたり最大100MBです。 入力ファイルの各行はインポートすべき単一のレコードを表します。 ### 記録構造 各レコードには以下の必須フィールドが含まれなければなりません: フィールド 種類 必須 概要 recordType ストリング はい レコードの種類。プロフィール記録には profile を使いましょう。大文字に区別されない。 identifiers アレイ はい 識別子オブジェクトの配列で、それぞれにproviderとidフィールドがあります。識別子は、設定された識別子ルールと空でないidに一致するproviderを持ちなければなりません。 各レコードには、以下のフィールドのうち少なくとも1つが含まれていなければなりません。 フィールド 種類 必須 概要 [contact](https://doc.sitecore.com/sai/ja/developers/sitecoreai/profile-import/batch-file-format.html#profile-contact) 目的 いいえ プロフィールの連絡先情報( firstName、 lastName、 emailなど)があります。 [extensions](https://doc.sitecore.com/sai/ja/developers/sitecoreai/profile-import/batch-file-format.html#profile-extensions) 目的 いいえ プロファイルのカスタム属性。組織が追跡する追加データにはこのフィールドをご利用ください。 > !重要レコードペイロードは、少なくとも1つの非ヌルフィールドをcontactまたはextensionsの中に含めなければなりません。更新可能なフィールドがないレコードはNO\_UPDATABLE\_FIELDSエラーコードで失敗します。 以下の表は、contactオブジェクトおよびextensionsオブジェクトで利用可能なフィールドを説明します。 #### profile.contact(プロフィール)連絡先 フィールド 種類 概要 例 firstName ストリング 個人の名前は空であってはならない。(1〜500文字) "John" lastName ストリング その人物の姓。(1〜500文字) "Smith" email ストリング ローカル部分、 @ 記号、ドメインを含む有効なメールアドレス形式。 "example@email.com" dateOfBirth 日付 生年月日はISO 8601規格(YYYY-MM-DD)で、年、月、日を表します。 "1995-01-01" gender ストリング 個人の性別。フリーテキストは受け入れられますが、推奨される値のいずれかが推奨されます。 推奨値は "male"、 "female"、 "unknown"、 "other" (1〜100文字) "male" language ストリング 言語コードはISO 639-1形式で表され、大文字2文字で表されていました。 "EN" title ストリング 個人のためのタイトルは、フリーテキストでも指定された列挙値のいずれかでも構いません。 推奨値: "Br"、 "Brigadier"、 "Capt"、 "Colonel"、 "Dame"、 "Dr"、 "Elder"、 "Fr"、 "General"、 "Hon"、 "Judge"、 "Lord"、 "Master"、 "Miss"、 "Mr"、 "Mrs"、 "Ms"、 "Mstr"、 "Prof"、 "Rabbi"、 "Rev"、 "Shaikha"、 "Sheikh"、 "Sir"、 "Sister"、 "Sr" (1〜100文字) "Mr" phoneNumbers 地図 自宅、職場、モバイルなど、さまざまな電話番号を構造化して表現したものです。 [参照 profile.contact.phoneNumbers](https://doc.sitecore.com/sai/ja/developers/sitecoreai/profile-import/batch-file-format.html#profile-contact-phonenumbers) address 目的 通り、市、州、郵便番号を含む物理的な場所の構造化された表現。 [参照 profile.contact.address](https://doc.sitecore.com/sai/ja/developers/sitecoreai/profile-import/batch-file-format.html#profile-contact-address) #### profile.contact.address フィールド 種類 概要 例 street ストリング 住所だ。(1〜500文字) "12 Baker Street" city ストリング その都市の名前。(1〜500文字) "Madrid" state ストリング 州名や地域のこと。(1〜500文字) "Colorado" postCode ストリング 郵便番号は国ごとにフォーマットされています。(1〜500文字) "AB 123" country ストリング 国コードだ。 address がいる場合は必須です。フォーマット:ISO 3166-1 alpha-2 "ES" #### profile.contact.phoneNumbers(プロフィール・連絡先・電話番号) フィールド 種類 概要 例 home ストリング 自宅電話番号はE.164形式、または空の番号でも構いません。 "+34911222333" work ストリング E.164形式の職場電話番号、または空の番号でもいいです。 "+34914445566" mobile ストリング 携帯電話番号はE.164形式、または空の番号もあります。 "+353861234567" #### profile.extensions 組織が特定のビジネスニーズに合わせて定義した汎用拡張可能な属性。 extensionsオブジェクトの中に任意の数のカスタムキー・値ペアを含めることができます。フィールド名はAPIではなく、あなた自身が定義します。 フィールド 種類 概要 例 文字列、ブール数、数、配列、オブジェクト、null 組織によって定義された名前と値を持つカスタムフィールドです。 "extensions": {"tier": "gold", "score": 42} extensionsの配列について以下の点に注目してください: - 各配列はフラットオブジェクト構造を使用する必要があります。 - 配列内のすべてのアイテムはオブジェクトでなければなりません。 - 配列は最大100個のオブジェクトを含めることができます。 - 特定の拡張機能の配列内のオブジェクトの形状は、組織によって定義されます。 - 各オブジェクトのプロパティはスカラー値(文字列、数値、ブール値、null)のみを含めることができます。 - contactやextensionsの最上位レベルでnullフィールドを削除[します](https://doc.sitecore.com/sai/ja/developers/sitecoreai/profile-import/batch-file-format.html#deleting-a-single-field)が、extensionsの配列アイテム内のnull値はそのまま保存され、フィールド自体は削除されません。 - 配列を [更新](https://doc.sitecore.com/sai/ja/developers/sitecoreai/profile-import/batch-file-format.html#update-behavior) する際、配列全体が既存の値を置き換えます。 - 配列アイテム内のネストされたオブジェクトや配列はサポートされていません。 以下の例はextensionsにおける有効な配列を示しています: "extensions": { "orders": { "amount": 149.99, "currency": "USD" }, { "amount": 49, "currency": "EUR" } , "preferences": { "name": "newsletter", "value": "weekly", "priority": 1, "enabled": true, "note": "paused" }, { "name": "channel", "value": "email", "priority": 2, "enabled": false, "note": null } } 例では、null値がextensionsの配列項目内にあるため、"note": nullはそのまま保存されます。 noteを削除するには、noteせずにpreferences配列内のオブジェクトを再送信します: { "name": "channel", "value": "email", "priority": 2, "enabled": false } preferencesを削除するには、preferences配列を再送し、値をnullに設定してください。 "preferences": null ### 入力例 以下の例は、12のプロファイルレコードを持つJSONLファイルを示しています。 {"recordType":"profile","identifiers":{"provider":"email","id":"alice1@example.com"},"contact":{"firstName":"Alice1","lastName":"Smith2"}, "extensions":{"where": "In the wonderland"}} {"recordType":"profile","identifiers":{"provider":"email","id":"alice2@example.com"},"contact":{"firstName":"Alice2","lastName":"Smith2"}, "extensions":{"where": "In the wonderland1"}} {"recordType":"profile","identifiers":{"provider":"email","id":"alice3@example.com"},"contact":{"firstName":"Alice3","lastName":"Smith2"}, "extensions":{"where": "In the wonderland2"}} {"recordType":"profile","identifiers":{"provider":"email","id":"alice4@example.com"},"contact":{"firstName":"Alice4","lastName":"Smith2"}, "extensions":{"where": "In the wonderland3"}} {"recordType":"profile","identifiers":{"provider":"email","id":"alice5@example.com"},"contact":{"firstName":"Alice5","lastName":"Smith2"}, "extensions":{"where": "In the wonderland4"}} {"recordType":"profile","identifiers":{"provider":"userid","id":"crm-0042"},{"provider":"email","id":"bob@example.com"},"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. 識別子の値は大文字差し区別がありません。例えば、 alice1@example.com と ALICE1@EXAMPLE.COM は同じプロファイルに解決されます。 3. システムは各適格識別子を検索し、一致するプロファイルを探します。 ### 解決の成果 一致するプロファイルが見つかりました 戦闘 概要 0 作成 システム生成のプロファイルIDで新しいプロファイルが作成されます。 1 アップデート 既存のプロファイルはレコードのデータで更新されます。 1人以上 失敗 識別子が複数の異なるプロファイルに解決されるため、 INCONSISTENT\_IDENTIFIERS エラーコードでレコードが失敗します。 ### 既存のプロファイルに新しい識別子を追加する > !重要バッチをアップロードする前に、SitecoreAI環境で [識別ルールを作成する](https://doc.sitecore.com/sai/en/users/sitecoreai/manage-identity-rules.html) 必要があります。認識されていないプロバイダーの識別子は無視されます。 複数のプロバイダーからの識別子を含むレコードの場合、プロファイルインポートはマッチしたプロファイルに新しい識別子を追加します。これにより、以前に別のプロバイダーによって識別されたプロファイルに新しい識別子タイプを関連付けることができます。 例えば、SitecoreAI環境でemailをデフォルトの識別子として使い、後にuseridの識別ルール(CRM ID)を作成する場合、各レコードにemailとuseridの両方の識別子を含むバッチをアップロードできます。プロファイルインポートは、email識別子を使って既存プロファイルに対してレコードを解決し、そのプロファイルに追加の識別子としてuseridを追加します。 ## 更新動作 レコードが既存のプロファイルと一致すると、システムはディープマージの意味論を用いてプロファイルを更新します: - オブジェクトフィールドは再帰的にマージされます。入力フィールドは既存のフィールドに追加または上書きされます。入受信記録に存在しないフィールドは保持されます。 - アレイフィールドはマージではなく置き換えられます。もし入受信レコードに配列のキーが含まれている場合(例えば、extensionsの中にorders)、配列全体がそのキーの既存の値を置き換えます。 - ヌル値は対応するフィールドをプロファイルから削除します。 - プロファイルには contact と extensions のみが書き込まれます。 - 受信データが既存プロファイルと同一で、追加すべき識別子が欠落していなければ書き込みは起こりません。プロフィールの modifiedAt タイムスタンプは更新されません。 ### 例 既存のプロファイルに以下が含まれている場合: { "contact": { "firstName": "Alice1", "lastName": "Smith2" }, "extensions": { "where": "In the wonderland" } } そして、入ってくる記録には以下が含まれます: { "contact": { "email": "alice1@example.com" }, "extensions": { "where": "Wonderland" } } 得られるプロファイルは次の通りです: { "contact": { "firstName": "Alice1", "lastName": "Smith2", "email": "alice1@example.com" }, "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": "alice1@example.com" } } そして、入ってくる記録には以下が含まれます: { "identifiers": { "provider": "email", "id": "alice1@example.com" }, { "provider": "crm", "id": "CRM-00042" } } 得られるプロファイルは次の通りです: { "identifiers": { "provider": "email", "id": "alice1@example.com" }, { "provider": "crm", "id": "CRM-00042" } } 既存の"email"識別子はそのまま残り、新しい"crm"識別子が付加されます。ここから、識別子の解決(IDENTITYイベントを通じて)は、[識別子](https://doc.sitecore.com/personalize/en/users/sitecore-personalize/configure-identity-rules.html)ルールで定義された順序で識別子が追加されたプロファイルをマッチングできます。 新しい識別子をアップロードする前に、新しい識別子で識別子ルールを作成する必要があります。 ## 削除動作 ### 単一のフィールドを削除する オブジェクト内の単一のフィールドを削除するには、そのキーをnullに設定してください。除去されるのは無効キーのみです。対象内の他のすべての場は保存されます。 既存のプロファイルに以下が含まれている場合: { "contact": { "firstName": "Alice1", "lastName": "Smith2", "email": "alice1@example.com" } } そして、入ってくる記録には以下が含まれます: { "identifiers": { "provider": "email", "id": "alice1@example.com" } , "contact": { "firstName": "Alice1", "lastName": null, "email": "alice1@example.com" } } 得られるプロファイルは次の通りです: { "identifiers": { "provider": "email", "id": "alice1@example.com" } , "contact": { "firstName": "Alice1", "email": "alice1@example.com" } } この例では、lastNameがnullに設定されているため削除されます。 firstNameとemailはヌル化されていないため保持されます。同じパターンが、extensionsの中の鍵にも当てはまります。 ### オブジェクト全体を削除する オブジェクト全体を削除するには、contactかextensionsをnullに設定してください。両方をnullに設定しないでください。識別子は既存のプロファイルに解決されなければならず、更新後もcontactまたはextensionsのうち少なくとも1つがプロファイルに残っている必要があります。 既存のプロファイルに以下が含まれている場合: { "identifiers": { "provider": "email", "id": "alice1@example.com" } , "contact": { "firstName": "Alice1", "lastName": "Smith2" }, "extensions": { "loyaltyTier": "Silver", "where": "Wonderland" } } そして、入ってくる記録には以下が含まれます: { "identifiers": { "provider": "email", "id": "alice1@example.com" } , "contact": { "firstName": "Alice1", "lastName": "Smith2" }, "extensions": null } 得られるプロファイルは次の通りです: { "identifiers": { "provider": "email", "id": "alice1@example.com" } , "contact": { "firstName": "Alice1", "lastName": "Smith2" } } この例では、extensionsオブジェクト全体がnullに設定されているため削除されます。 contactは保持されます。 ### 少なくとも1つのオブジェクトが必要です 記録は、contactとextensionsの両方をnullに記録するものは却下されます。 contactまたはextensionsのうち少なくとも1つは、レコードを処理するためのデータを含む必要があります。 以下のレコードはNO\_UPDATABLE\_FIELDSエラーコードで失敗します: { "identifiers": { "provider": "email", "id": "alice1@example.com" } , "contact": null, "extensions": null } すべての削除操作には以下の制約が適用されます: - すべてのレコードには有効な識別子が含まれなければなりません。 null または認識されない provider の識別子は解決時に無視され、有効な識別子が残らなければレコードは失敗します。 - contactまたはextensionsのうち少なくとも1つはコンテンツと共に存在しなければなりません。両方をnullに設定するとNO\_UPDATABLE\_FIELDSエラーコードが表示されます。 ## 出力ファイル形式 バッチが最終状態(COMPLETED、COMPLETED\_WITH\_ERRORS、またはFAILED)に達した後、**プロファイルインポート** ページで結果を見るか、以下のAPIリクエストで結果ファイルをダウンロードできます。 curl "{base\_url}/v1/batches/{batchId}/results" \\ -H "Authorization: ApiKey " \\ -o results.jsonl COMPLETED\_WITH\_ERRORS状態のバッチについては、組織の所有者や管理者も、バッチの**「レポートをダウンロード**」をクリックしてユーザーインターフェースから直接結果をダウンロードできます。 ### 出力レコード構造 各出力レコードには以下のフィールドが含まれています: フィールド 種類 概要 recordIndex 整数 入力ファイルのレコードのゼロベースのインデックスです。 id 文字列(UUID) 入力レコードからの相関ID(もし提供されていた場合)も含まれます。 recordType ストリング 入力レコードからのレコードタイプ、例えば profile。型を解析する前にレコードが失敗した場合は省略します。 outcome ストリング 処理の結果は、 CREATED、 UPDATED、または FAILED。 profileId 文字列(UUID) プロファイルID。 CREATED と UPDATED の結果のためにプレゼントしましょう。 errorCode ストリング エラーコード。 FAILED 結果のためだけに存在する。記録 [レベルのエラーコード](https://doc.sitecore.com/sai/ja/developers/sitecoreai/profile-import/profile-import-errors-and-troubleshooting.html#record-level-error-codes)を参照してください。 errorDescription ストリング 人間が読みやすい誤りの説明。 FAILED 結果のためだけに存在する。 ### 出力例 {"recordIndex":7,"recordType":"profile","outcome":"FAILED","errorCode":"INVALID\_RECORD","errorDescription":"No identifier with a valid id and a recognised provider"} {"recordIndex":8,"recordType":"profile","outcome":"FAILED","errorCode":"INVALID\_RECORD","errorDescription":"No identifier with a valid id and a recognised provider"} {"recordIndex":6,"recordType":"profile","outcome":"FAILED","errorCode":"INVALID\_RECORD","errorDescription":"No identifier with a valid id and a recognised provider"} {"recordIndex":9,"recordType":"profile","outcome":"FAILED","errorCode":"INVALID\_RECORD","errorDescription":"No identifier with a valid id and a recognised provider"} {"recordIndex":10,"recordType":"profile","outcome":"FAILED","errorCode":"INVALID\_RECORD","errorDescription":"No identifier with a valid id and a recognised provider"} {"recordIndex":11,"recordType":"profile","outcome":"FAILED","errorCode":"INVALID\_RECORD","errorDescription":"No identifier with a valid id and a recognised provider"} {"recordIndex":2,"recordType":"profile","outcome":"CREATED","profileId":"f66bf7c3-79e0-45f4-9862-777db6a1fe7d"} {"recordIndex":5,"recordType":"profile","outcome":"UPDATED","profileId":"3458e2eb-447a-4b41-a664-86fc4ce8564f"} {"recordIndex":3,"recordType":"profile","outcome":"CREATED","profileId":"29c63a5a-ef15-472c-a784-e1f16f4d80f7"} {"recordIndex":0,"recordType":"profile","outcome":"UPDATED","profileId":"a1ee5416-f002-4290-aa36-1f89abc3b32f"} {"recordIndex":1,"recordType":"profile","outcome":"UPDATED","profileId":"468154b0-98f6-4bb1-8e16-a5e6b53624bb"} {"recordIndex":4,"recordType":"profile","outcome":"CREATED","profileId":"a51637cd-da73-4967-b0ee-4210b2cf4b37"}