Salesforce に CSV ファイルをインポートまたは更新するための準備

CSV ファイルの準備

CSV ファイルの最初の行 (ヘッダー行) には、処理するオブジェクトの項目名を記述します。2 行目以降は、Salesforce の各レコードに対応します。レコードは一連の項目で構成され、項目と項目の間はカンマで区切られます。1 つの CSV ファイルに複数のレコードを含めることができ、これを「バッチ」と呼びます。

CSV ファイル内のレコードは、すべて同一オブジェクトのレコードである必要があります。オブジェクトは、バッチに関連付けられたジョブで指定します。ある特定のジョブに関連付けられたすべてのバッチに含まれるレコードは、すべて同一オブジェクトのものである必要があります。

Bulk API を使用した CSV ファイルの処理:

• ファイルでは UTF-8 形式を使用します。
• Bulk API では区切り文字としてカンマのみがサポートされます。
  • 国際規格のコンピュータを使用している場合、Excel で生成される .CSV ファイルはほとんどの場合カンマで区切られていません。.CSV ファイルの区切り文字がカンマであるかどうかは、コンピュータのメモ帳アプリケーションでファイルを開けば確認できます。
  • 「Tom;Jones;buyer@salesforcesample.com」と表示された場合、現在の区切り文字はカンマではなくセミコロンです。この場合、ファイルでインポートの問題が発生します。
    • セミコロンをカンマに置換してください。たとえば、PC のキーボードで CTRL + H を実行し、[検索] と [置換] を行ってからファイルを保存します。
• Bulk API は大量のデータ処理に最適化されており、CSV ファイルの形式を厳格に定義しています。CSV ファイルを処理する最も簡単な方法は、データローダで Bulk API を有効にすることです。
• レコードを作成するときは、必須項目はもれなく含める必要があります。 
• レコードの更新では、CSV ファイルで定義されていない項目は無視されます。

ヘッダー行のリレーション項目

Salesforce のオブジェクトの多くは、別のオブジェクトに関連付けられています。たとえば、取引先は取引先責任者の親オブジェクトです。CSV ファイルでは、列ヘッダーでリレーションを示すことにより、関連付けられたオブジェクトへの参照を追加できます。

Bulk API でレコードを処理する場合、CSV ファイルの列ヘッダーで RelationshipName.IndexedFieldName という構文を使用して、オブジェクトとその親オブジェクトのリレーションを記述します。RelationshipName は項目のリレーション名、IndexedFieldName は親レコードを一意に識別するインデックス化された項目の名前を示します。項目の relationshipName プロパティの値を取得するには、SOAP ベースの SOAP API で describeSObjects() コールを使用します。

自身に関連付けられているオブジェクトもあります。たとえば、取引先責任者の [上司] 項目は、別の取引先責任者を参照します。このような場合、列ヘッダーで ReportsTo.Email と記述すると、[メール] 項目の値に基づいて、各取引先責任者の [上司] 項目を一意に識別できます。

列ヘッダーの ReportsTo の部分は、[上司] 項目の relationshipName プロパティの値です。

リレーションを使用した CSV ファイルの例を次に示します。
 

1 FirstName,LastName,ReportsTo.Email 
2 Tom,Jones,buyer@salesforcesample.com

注意:
 

1. 子から親へのリレーションを使用できます。親から子へのリレーションは使用できません。
2. 子から親へのリレーションを拡張して使用することはできません。つまり、子から親へのリレーションを参照し、さらに親からその親へのリレーションを参照することはできません。
3. 親の識別では、インデックス化された項目のみを使用できます。
   • カスタム項目は、外部 ID 属性が選択されている [外部 ID] 項目である場合、インデックス化されています。
   • 標準項目は、idLookup プロパティの値が true に設定されている場合、インデックス化されています。 
   • 詳細は、「標準オブジェクト」の項目テーブルの「項目のプロパティ」列を参照してください。

カスタムオブジェクトのリレーション項目

カスタムオブジェクトでは、カスタム項目を使用してオブジェクト間のリレーションを追跡します。2 つのカスタムオブジェクト間のリレーションを示すには、__r (アンダースコア 2 つと「r」) で終わるリレーション名を使用します。列ヘッダーでこのリレーションを指定して、関連オブジェクトへの参照を追加できます。

たとえば、子オブジェクトに、あるカスタムオブジェクトを親として参照する Mother_Of_Child__c という [API 参照名] を持つカスタム項目があり、親となるオブジェクトに External_ID__c という [API 参照名] を持つ項目がある場合は、Mother_Of_Child__r.External_ID__c  という列ヘッダーを記述することにより、親オブジェクトの [外部 ID] 項目を使用して、[Mother Of Child] 項目を一意に識別できます。列ヘッダー内のリレーション名では、子オブジェクトのカスタム項目の __c を __r で置き換えた値を入力します。

リレーションを使用した CSV ファイルの例を次に示します。
 

1 Name,Mother_Of_Child__r.External_ID__c 
2 CustomObject1,123456

詳細は、「SOQL および SOSL の概要」を参照してください。

多態的な項目でのリレーション

多態的な項目では、2 種類以上のオブジェクトを親として参照できます。たとえば、取引先責任者またはリードを ToDo の親にすることができます。つまり、ToDo の WhoId 項目に取引先責任者またはリードの ID を含めることができます。 

多態的な項目は柔軟性が高く、列ヘッダーの構文に、親オブジェクトの種別を定義する要素を追加できるようになっています。この構文は ObjectType:RelationshipName.IndexedFieldName です。

後続のサンプルには、次の 2 つの参照項目が含まれています。
 

1. WhoId 項目は多態的な項目であり、Who という relationshipName が使用されています。ここでは、リードを参照し、インデックス化された [メール] 項目を使用して親レコードを一意に識別します。
2. OwnerId 項目は多態性を持たず、Owner という relationshipName が使用されています。ユーザを参照し、インデックス化された Id 項目を使用して親レコードを一意に識別します。
    

多態的な項目を使用した CSV ファイルの例を次に示します。

1 Subject,Priority,Status,Lead:Who.Email,OwnerId 
2 Test Bulk API polymorphic reference field,Normal,NotStarted,lead@salesforcesample.com,005D0000001AXYz

CSV のレコード行の有効な形式

項目の列ヘッダーで使用する ObjectType: という要素は、多態的な項目でのみ必須となります。多態的な項目でこの要素を省略するとエラーが返されますが、それ以外の項目でこの要素を使用した場合もエラーが返されます。

Bulk API は、大量データの処理用に最適化されており、項目の値の形式に厳格な制限を設けています。Salesforce レコードを含む CSV ファイルを作成する場合は、次の点に注意してください。
 

• 行内で項目の値を区切る場合は、必ずカンマを使用します。
• 値にカンマ、改行文字、二重引用符などが含まれる場合は、二重引用符で囲む必要があります。たとえば、"Director of Operations, Western Region" のように記述します。
• 値に二重引用符が含まれる場合は、それぞれの二重引用符の前にもう 1 つ二重引用符を挿入してエスケープする必要があります。たとえば、"This is the ""gold"" standard" のように記述します。
• 値は切り詰められることはありません。区切り文字のカンマの前後に空白文字が挿入されている場合、それらも値の一部とみなされます。ただし、二重引用符の前後に空白文字が挿入されている場合は、その行がエラーになります。
  • たとえば、John,Smith は有効な値です。John, Smith も、空白文字が含まれていますが有効です。一方、" Smith"、"John", "Smith" は無効な値となります。
• 項目の値が空である場合、レコードの更新時にはその項目は無視されます。値を null に設定するには、項目値 #N/A を使用します。
• double 型の項目には、小数値を含めることができます。W3C XML Schema Part 2: Datatypes Second Edition に記載されているとおり、相応に大きな数値の場合は、値を科学的記数法で保存できます。
• Excel は .CSV ファイルから先行ゼロを削除することで知られています。必ずインポート前に数値 (郵便番号など) を確認してください。

注意:

• 回避策として、ユーザは .CSV ファイルを Excel で開いてから [保存] を試みることができます。これにより、特定の形式の問題が修正される場合があります。
• 無効な行が 1 つあるだけでも全体のインポートが失敗する可能性があります。CSV をより小さなファイルに分割して、エラーやインポートの問題の原因となっているレコードや列を特定することもできます。

サンプルの CSV ファイル

次に示すサンプルの CSV ファイルには、取引先責任者オブジェクトのレコードが 2 つ含まれています。各レコードの項目は 6 つです。処理対象のオブジェクトの項目であればすべて追加できます。このファイルを使用して既存のレコードを更新する場合、CSV ファイル内に定義されていない項目は無視されます。

レコードを作成するときは、必須項目はもれなく含める必要があります。
 

1 FirstName,LastName,Title,ReportsTo.Email,Birthdate,Description 
2 Tom,Jones,Senior Director,buyer@salesforcesample.com,1940-06-07Z,"Self-described as ""the top"" branding guru on the West Coast" 
3 Ian,Dury,Chief Imagineer,cto@salesforcesample.com,,"World-renowned expert in fuzzy logic design.
4 Influential in technology purchases."

最後のレコードの Description 項目には改行が含まれるため、項目値が二重引用符で囲まれています。
 

データを別のオブジェクトにインポートするときの考慮事項

• 参照項目 - ID (Salesforce ID) とは、大文字と小文字を区別する 15 字または 18 字の英数字の文字列で、特定のレコードを一意に識別します。データの品質を確保するため、データローダに入力するすべての Salesforce ID について大文字と小文字が正しく指定されていることを確認してください。
• 選択リスト項目: 項目値は選択リストのいずれかの値と完全に一致している必要があります。選択リストにない他の新しい値を指定すると、レコードでエラーが発生することはありませんが、選択リストに追加されません。
• 日付項目: 日付項目は「CSVファイルの「日付」データと「日時」データの形式設定」で説明されているように書式設定されている必要があります。その他の点では、データインポートウィザードで日付または時間項目の形式を変更する必要はありません。
• Boolean 項目: True または False のいずれかの値を使用できます。たとえば、レコードにチェックボックス項目がある場合、true または false の値を使用して、それぞれオンまたはオフにすることができます。
• 通貨項目: カンマや通貨記号を追加する必要はありません。Salesforce により、組織のデフォルト通貨設定に応じて自動的に形式が選択されます。
• メールアドレス: RFC 5321 に従ってメールが正しく書式設定されていて、メールの国際規約で許可されていない無効な文字がメールに含まれていないことを確認します。以下に、無効なメールの例をいくつか示します。
  • Abc.example.com (@ 文字がない)
  • A@b@c@example.com (引用符の外側で使用できる @ は 1 つのみ)
  • a"b(c)d,e:f;g<h>i[j\k]l@example.com (このローカル部のどの特殊文字も引用符の外側では使用できない)
  • just"not"right@example.com (引用符で囲まれた文字列はドットで区切られているか、ローカル部の構成要素のみである必要がある)
  • this is"not\allowed@example.com (空白文字、引用符、バックスラッシュは、引用符で囲まれた文字列内で先頭にバックスラッシュが付いている場合にのみ使用できる)
  • this\ still\"not\\allowed@example.com (エスケープしても (バックスラッシュを先頭に付けても)、空白文字、引用符、バックスラッシュは引用符で囲む必要がある)
  • john..doe@example.com (@ の前のダブルドット)
  • 注意: Gmail ではメールアドレスのローカル部のすべてのドットが無視されます。
  • john.doe@example..com (@ の後のダブルドット)
  • 先頭に空白文字がある有効なアドレス
  • 末尾に空白文字がある有効なアドレス
• 入力規則: 入力規則が項目に適用されているかどうか、その入力規則の条件に準拠しているかどうかを確認します。準拠していないと、レコードでエラーが発生します。または、アップロードの前に入力規則を上書きして無効化することもできます。
• トリガ: レコードをインポートまたは更新するオブジェクトにトリガがあるかどうか、特定の条件を満たしていないためにレコードでエラーが発生するかどうかを確認します。アップロードの前にトリガを無効化してバイパスし、アップロードが完了したら再度有効化することもできます。

Apex データローダを使用してファイルを挿入、削除、または更新するときに、[Mapping Dialog] ウィンドウを使用して、Salesforce 項目を CSV ファイルの列に対応付けます。

1. 項目と列を自動的に一致させるには、[Auto-Match Fields to Columns] をクリックします。データローダは、項目と列の名前の類似性に基づき、ウィンドウの下部にリストを表示します。削除操作の場合、自動的に一致させるのは [ID] 項目のみです。
2. 項目と列を手動で一致させるには、上部にある Salesforce 項目のリストから、下部にある CSV 列のヘッダーの名前の部分に項目をドラッグします。たとえば、新しい取引先の名前が含まれる CSV ファイルに新しい取引先レコードを挿入する場合は、[Name] 列ヘッダー項目の右端に [Name] 項目をドラッグします。
3. この対応付けを再利用するために保存するには、[Save Mapping] をクリックします。SDL マッピングファイルの名前を指定します。既存のファイルを選択した場合、ファイルの内容が置き換えられます。このアクションを確定するには [はい] をクリックします。別のファイルを選択するには [いいえ] をクリックします。
4. 現在の操作でこの対応付けを使用するには、[OK] をクリックします。

これらのルールを満たしていない CSV ファイルからデータをインポートするには、CSV ファイルのデータ項目を Salesforce データ項目に対応付けます。「データ項目の対応付け」を参照してください。


関連情報:

• スプレッドシートをCSV形式に変換（英語）
• インポートファイルへの既存のレコードの ID の追加
• CSV データのインポートでセミコロンをカンマに置換する

Salesforce YouTube 動画

• Data Import: Clean and Prepare Your Data Using Excel (データインポート: Excel を使用したデータのクリーニングと準備) 
• How to Prepare a CSV File to Insert Using Data Loader (データローダを使用して挿入する CSV ファイルの準備方法)
• How to Prepare Your CSV File Using Vlookup in Excel（ExcelでVlookup 関数を使用してCSVファイル置換する方法）