SOAP API 開発者ガイド
jcreate()
構文
1SaveResult[] = connection.create(sObject[] sObjects);使用方法
create() は、Account や Contact レコードなど、1 つ以上のレコードを組織の情報に追加するのに使用します。create() コールは SQL の INSERT ステートメントに類似しています。
オブジェクトを作成する際は、次のルールやガイドラインを考慮する必要があります。
権限
クライアントアプリケーションは、指定したオブジェクト内にレコードを作成するのに十分なアクセス権限でログインする必要があります。詳細は、「データアクセスに影響する要素」を参照してください。
特別な処理
特定のオブジェクト、またこれらのオブジェクト内にある特定の項目には、特別な処理または権限が必要です。たとえば、オブジェクトの親オブジェクトへのアクセス権限も必要となります。create() で特定のオブジェクトのレコードを作成する前に、必ず「標準オブジェクト」の説明を読んでください。
作成可能な項目
create() コールで作成できるのは、createable が true に設定されているオブジェクトのみです。指定されたオブジェクトが作成可能かどうかを確認するには、クライアントアプリケーションでオブジェクトに対する describeSObjects()describeSObjects() コールを実行し、createable プロパティを確認します。
自動的に保持される項目
API は ID 項目に一意な値を自動的に生成します。create() では、sObject に ID 値を明示的に指定することはできません。saveResult[] オブジェクトには、正常に作成された各レコードの ID が含まれます。ID についての詳細は、「ID データ型」を参照してください。
API は、CreatedDate、CreatedById、LastModifiedDate、LastModifiedById および SystemModstamp などの特定の項目を自動的に入力します。これらの値は明示的に指定できません。
必須項目
デフ��ルト値が事前に設定されていない必須項目には、値を指定する必要があります。詳細は、「必須項目」を参照してください。
デフォルト値
オブジェクトによっては、OwnerID などデフォルト値のある項目があります。そのような項目に値を指定しないと、API は項目にデフォルト値を入力します。たとえば、OwnerID を上書きしない場合、API はクライアントアプリケーションがログインユーザーに関連したユーザー ID を項目に入力します。
- デフォルト値が事前に設定されていない必須項目には、値を指定する必要があります。
- オブジェクトの他の項目では、値を明示的に指定しない場合は null (VT_EMPTY) となります。
参照整合性
クライアントアプリケーションは参照整合性に従う必要があります。たとえば、親オブジェクトの子であるオブジェクトのレコードを作成する場合、子を親にリンクする外部キー情報を指定する必要があります。たとえば、CaseComment を作成する場合、親の Case の有効なケース ID を指定する必要があり、また、親のケースはデータベース内に存在しなければなりません。
データ値の検証
整数項目については整数 (英字は不可)、項目のデータ型に対して有効な値を入力する必要があります。クライアントアプリケーションでは、使用しているプログラム言語および開発ツールに指定されたデータ形式ルールに従ってください (開発ツールは、SOAP メッセージのデータ型の適切な対応付けを処理します)。
文字列値
文字列項目に値を格納する場合、前後にある空白は API が切り捨てます。たとえば、名前項目の値に " ABC Company " と入力されると、その値はデータベースに "ABC Company" と保存されます。
API バージョン 15.0 以降、文字列を含む項目に値を指定し、値が項目に対して大きすぎる場合、コールは失敗してエラーが返されます。これまでのバージョンの API では、値は切り捨てられ、コールは正常に終了していました。バージョン 15.0 以降でもこの動作を保持する場合、AllowFieldTruncationHeader SOAP ヘッダーを使用してください。
割り当てルール
Account (取引先はテリトリー管理割り当てルールを実行)、Case、または Lead レコードを作成する場合、クライアントアプリケーションでは、Salesforce ユーザーインターフェースで設定された割り当てルールに基づいて 1 人以上のユーザーにケースまたはリードを自動的に割り当てるために、AssignmentRuleHeader にオプションを設定することができます。
最大作成レコード数
クライアントアプリケーションは、1 回の create() コールで最大 200 個のレコードを追加できます。create 要求が 200 レコードを超えると、操作全体が失敗します。
エラー時のロールバック
AllOrNoneHeader ヘッダーを使用すると、すべてのレコードが正常に処理されない限り、すべての変更をロールバックできます。このヘッダーは、API バージョン 20.0 以降で使用できます。正常に処理されないレコードがあった場合に、コールですべての変更をロールバックできます。
Chatter フィードの自動登録
作成するレコードを登録するには、ユーザーは個人設定の [作成したレコードを自動的にフォローする] オプションを有効にする必要があります。自動登録が有効化されている場合、ユーザーは自分が作成したレコードを自動的にフォローし、それらのレコードへの変更が [ホーム] タブの Chatter フィードに表示されます。
ユーザーはレコードまたは他のユーザーを登録できます。レコードへの変更とユーザーからの更新は、ユーザーのホームページの Chatter フィードに表示されます。これは、Salesforce で他のユーザーやレコードに加えられた変更の最新状況を把握するのに役立ちます。フィードは、API バージョン 18.0 以降で使用できます。EntitySubscription オブジェクトは、レコードまたは他のユーザーをフォローしているユーザーの登録を表します。
フィード通知の無効化
大量のレコードを処理していて、レコードに関連するさまざまな項目を追跡しない場合、DisableFeedTrackingHeader を使用します。このヘッダーは一括変更で特に役立ちます。
オブジェクト種別が異なるレコードの作成
API バージョン 20.0 以降では、1 回のコールで、カスタムオブジェクトも含め、複数のオブジェクト種別のレコードを作成できます。たとえば、取引先責任者と取引先を 1 回のコールで作成できます。1 回のコールで、最大 10 種類のオブジェクトのレコードを作成できます。
レコードは、sObjects 入力配列に入力された順序で保存されます。親子リレーションを持つ新規レコードを入力する場合、sObjects 配列内で親レコードを子レコードよりも前にする必要があります。たとえば、取引先責任者と取引先を同じコールで作成し、取引先責任者が取引先を参照する場合、sObjects 配列で取引先のインデックスは取引先責任者のインデックスよりも小さくする必要があります。取引先責任者は、[外部 ID] 項目を使用して取引先を参照します。
同じコールの中で、同じオブジェクト種別の別のレコードを参照するレコードは追加できません。たとえば、取引先責任者オブジェクトに、別の取引先責任者を参照する [上司] 項目があるとします。一方の取引先責任者が [上司] 項目を使用して sObjects 配列の別の取引先責任者を参照する場合、その両方の取引先責任者を 1 回のコールで追加することはできません。すでに作成された別の取引先責任者を参照する取引先責任者を作成することはできます。
Salesforce では、オブジェクト種別が異なるレコードは複数のチャンクに分けられます。1 つのチャンクは、sObjects 入力配列のサブセットで、各チャンクにはオブジェクト種別が同じレコードが含まれます。データは、チャンク単位にコミットされます。チャンクに含まれるレコードに関連する Apex トリガーは、チャンクごとに 1 回起動されます。次のレコードのセットを含む sObjects 入力配列があるとします。
1account1, account2, contact1, contact2, contact3, case1, account3, account4, contact4Salesforce は、レコードを次の 5 つのチャンクに分割します。
- account1, account2
- contact1, contact2, contact3
- case1
- account3, account4
- contact4
コールごとに最大 10 個のチャンクを処理できます。sObjects 配列に含まれるチャンクが 10 個よりも多い場合、レコードを複数のコールに分けて処理する必要があります。
create() と外部キー
外部 ID 項目を外部キーとして使用することによって、最初に親レコードの ID を照会するのではなく、レコードを作成して他の既存のレコードに関連付ける操作を 1 つの手順で実行できます。指定された外部 ID 項目のみを持つ親 sObject のインスタンスに外部キー項目を設定します。この外部 ID は親レコードの外部 ID の値と一致する必要があります。
次の Java および C# の例では、MyExtId__c というカスタム外部 ID 項目を使用して商談を作成して、既存の取引先に関連付ける方法を示します。各例では商談を作成し、必須項目を設定してから、指定された外部 ID 項目のみを持つ取引先オブジェクトに商談の外部 ID 項目を設定します。次に、コードは商談を作成します。商談が作成されると、取引先はその親になります。
Java の例
1public void createForeignKeySample() {
2 try {
3 Opportunity newOpportunity = new Opportunity();
4 newOpportunity.setName("OpportunityWithFK");
5 newOpportunity.setStageName("Prospecting");
6 Calendar dt = connection.getServerTimestamp().getTimestamp();
7 dt.add(Calendar.DAY_OF_MONTH, 7);
8 newOpportunity.setCloseDate(dt);
9
10 Account parentAccountRef = new Account();
11 parentAccountRef.setMyExtId__c("SAP1111111");
12 newOpportunity.setAccount(parentAccountRef);
13
14 SaveResult[] results = connection
15 .create(new SObject[] { newOpportunity });
16 } catch (ConnectionException ce) {
17 ce.printStackTrace();
18 }
19}C# の例
1public void createForeignKeySample()
2{
3 try
4 {
5 Opportunity newOpportunity = new Opportunity();
6 newOpportunity.Name = "OpportunityWithFK";
7 newOpportunity.StageName = "Prospecting";
8 DateTime dt = (DateTime)binding.getServerTimestamp().timestamp;
9 newOpportunity.CloseDate = dt.AddDays(7);
10 newOpportunity.CloseDateSpecified = true;
11
12 // Create the parent reference.
13 // Used only for foreign key reference
14 // and doesn't contain any other fields
15 Account accountReference = new Account();
16 accountReference.MyExtId__c = "SAP1111111";
17 newOpportunity.Account = accountReference;
18
19 // Create the account and the opportunity
20 SaveResult[] results = binding.create(new sObject[] {
21 newOpportunity });
22 }
23 catch (SoapException e)
24 {
25 Console.WriteLine("An unexpected error has occurred: " +
26 e.Message + "\n" + e.StackTrace);
27 }
28}外部キーを使用して 1 つのコールで親レコードと子レコードを作成する
外部キーとして外部 ID 項目を使用することによって、最初に親レコードを作成して、その ID を照会してから子レコードを作成するのではなく、他の種別の sObject の親レコードおよび子レコードを 1 つのコールで作成することができます。外部 ID 項目を外部キーとして使用し、1 回の呼び出しで異なる sObject 種別の親レコードと子レコードを作成する手順は、次のとおりです。
- 子 sObject を作成し、必須項目 (必要に応じて、その他の項目) を入力します。
- 子 sObject に対する親外部キー参照を設定するためにのみ使用される、親参照 sObject を作成します。この sObject には定義された外部 ID 項目のみがあり、その他の項目は設定されません。
- 作成した親参照 sObject に子 sObject の外部キー項目を設定します。
- create() コールに渡すその他の親 sObject を作成します。この sObject には、外部 ID 項目に加えて、必須項目 (必要に応じて、その他の項目) を設定する必要があります。
- 作成する sObject の配列を渡して、create() をコールします。親 sObject は配列の子 sObject の前に付ける必要があります、つまり、親の配列インデックスは子のインデックスより小さい必要があります。
親レコードと子レコードは、主従関係または参照関係など、事前定義された関係によって関連付けられているレコードです。最大 10 レベルの深度で関連レコードを作成できます。また、1 回のコールで作成される関連レコードには、他の種別の sObject が必要です。詳細は、「オブジェクト種別が異なるレコードの作成」を参照してください。
次の Java および C# の例では、1 回の create() コールで親取引先を持つ商談を作成する方法を示します。各例では、商談 sObject を作成し、その項目のいくつかに入力してから、2 つの取引先オブジェクトを作成します。最初の取引先は外部キーリレーションのみであり、2 番目の取引先は取引先作成のためのものであり、取引先項目が設定されています。両方の取引先には外部 ID 項目 MyExtID__c が設定されています。次に、このサンプルでは、sObject の配列を渡して、create() をコールします。配列の最初の要素は親 sObject で、2 番目は商談 sObject です。create() コールでは、1 回のコールで商談とその親取引先を作成します。最後に、このサンプルでは、コールの結果を確認し、作成されたレコードの ID をコンソールに書き込むか、レコードの作成が失敗した場合は最初のエラーを書き込みます。
Java の例
1public void createForeignKeySample() {
2 try {
3 Opportunity newOpportunity = new Opportunity();
4 newOpportunity.setName("OpportunityWithAccountInsert");
5 newOpportunity.setStageName("Prospecting");
6 Calendar dt = connection.getServerTimestamp().getTimestamp();
7 dt.add(Calendar.DAY_OF_MONTH, 7);
8 newOpportunity.setCloseDate(dt);
9
10 // Create the parent reference.
11 // Used only for foreign key reference
12 // and doesn't contain any other fields.
13 Account accountReference = new Account();
14 accountReference.setMyExtID__c("SAP111111");
15 newOpportunity.setAccount(accountReference);
16
17 // Create the Account object to insert.
18 // Same as above but has Name field.
19 // Used for the create call.
20 Account parentAccount = new Account();
21 parentAccount.setName("Hallie");
22 parentAccount.setMyExtID__c("SAP111111");
23
24 // Create the account and the opportunity.
25 SaveResult[] results = connection.create(new SObject[] {
26 parentAccount, newOpportunity });
27
28 // Check results.
29 for (int i = 0; i < results.length; i++) {
30 if (results[i].isSuccess()) {
31 System.out.println("Successfully created ID: "
32 + results[i].getId());
33 } else {
34 System.out.println("Error: could not create sobject "
35 + "for array element " + i + ".");
36 System.out.println(" The error reported was: "
37 + results[i].getErrors()[0].getMessage() + "\n");
38 }
39 }
40 } catch (ConnectionException ce) {
41 ce.printStackTrace();
42 }
43}C# の例
1public void createForeignKeySample()
2{
3 try
4 {
5 Opportunity newOpportunity = new Opportunity();
6 newOpportunity.Name = "OpportunityWithAccountInsert";
7 newOpportunity.StageName = "Prospecting";
8 DateTime dt = (DateTime)binding.getServerTimestamp().timestamp;
9 newOpportunity.CloseDate = dt.AddDays(7);
10 newOpportunity.CloseDateSpecified = true;
11
12 // Create the parent reference.
13 // Used only for foreign key reference
14 // and doesn't contain any other fields.
15 Account accountReference = new Account();
16 accountReference.MyExtID__c = "SAP111111";
17 newOpportunity.Account = accountReference;
18
19 // Create the Account object to insert.
20 // Same as above but has Name field.
21 // Used for the create call.
22 Account parentAccount = new Account();
23 parentAccount.Name = "Hallie";
24 parentAccount.MyExtID__c = "SAP111111";
25
26 // Create the account and the opportunity.
27 SaveResult[] results = binding.create(new sObject[] {
28 parentAccount, newOpportunity });
29
30 // Check results.
31 for (int i = 0; i < results.Length; i++)
32 {
33 if (results[i].success)
34 {
35 Console.WriteLine("Successfully created ID: "
36 + results[i].id);
37 }
38 else
39 {
40 Console.WriteLine("Error: could not create sobject "
41 + "for array element " + i + ".");
42 Console.WriteLine(" The error reported was: "
43 + results[i].errors[0].message + "\n");
44 }
45 }
46 }
47 catch (SoapException e)
48 {
49 Console.WriteLine("An unexpected error has occurred: " +
50 e.Message + "\n" + e.StackTrace);
51 }
52}レコード作成の基本手順
レコードは、次の基本手順に従って作成します。
- 1 つ以上のオブジェクトの sObject を作成します。各レコードに対し、追加するデータを項目に入力します。
- sObject[] 配列を作成し、作成するオブジェクトを配列に入力します。
- create() をコールし、sObject[] 配列を渡します。
- saveResult[] オブジェクトの結果を処理してレコードの作成が成功したかどうかを確認します。
サンプルコード — Java
このサンプルでは、レコードの作成方法を示します。ここでは、2 つの取引先オブジェクトを作成し、それらの項目を設定します。2 番目の取引先の Name は設定されていないため、作成時にエラーが発生します。これは、Name が必須項目であるためです。このサンプルでは、2 つの取引先を含む配列を渡して、create() コールを行った後、結果を反復処理して、新しい取引先の ID を書き込むか、または、取引先の作成が失敗した場合はエラーメッセージを書き込みます。最後に、新しい取引先 ID の配列を返します。この例では、1 つの ID のみが含まれています。
1public String[] createRecords() {
2 // Create two accounts
3 String[] result = new String[2];
4 Account account1 = new Account();
5 Account account2 = new Account();
6
7 // Set some fields on the account object
8 account1.setName("The Brick Hut");
9 account1.setBillingStreet("403 McAdoo St");
10 account1.setBillingCity("Truth or Consequences");
11 account1.setBillingState("NM");
12 account1.setBillingPostalCode("87901");
13 account1.setBillingCountry("US");
14 // Required Name field is not being set on account2,
15 // so this record should fail during create.
16 // account2.setName("Camp One Creations");
17 account2.setBillingStreet("25800 Arnold Dr");
18 account2.setBillingCity("Sonoma");
19 account2.setBillingState("CA");
20 account2.setBillingPostalCode("95476");
21 account2.setBillingCountry("US");
22 Account[] accounts = { account1, account2 };
23
24 try {
25 // Call create() to add the accounts
26 SaveResult[] saveResults = connection.create(accounts);
27 // Iterate through the results.
28 // There should be one successful creation
29 // and one failed creation.
30 for (int i = 0; i < saveResults.length; i++) {
31 if (saveResults[i].isSuccess()) {
32 System.out.println("Successfully created Account ID: "
33 + saveResults[i].getId());
34 result[i] = saveResults[i].getId();
35 } else {
36 System.out.println("Error: could not create Account "
37 + "for array element " + i + ".");
38 System.out.println(" The error reported was: "
39 + saveResults[i].getErrors()[0].getMessage() + "\n");
40 result[i] = saveResults[i].getId();
41 }
42 }
43 } catch (ConnectionException ce) {
44 ce.printStackTrace();
45 }
46 return result;
47}サンプルコード — C#
このサンプルでは、レコードの作成方法を示します。ここでは、2 つの取引先オブジェクトを作成し、それらの項目を設定します。2 番目の取引先の Name は設定されていないため、作成時にエラーが発生します。これは、Name が必須項目であるためです。このサンプルでは、2 つの取引先を含む配列を渡して、create() コールを行った後、結果を反復処理して、新しい取引先の ID を書き込むか、または、取引先の作成が失敗した場合はエラーメッセージを書き込みます。最後に、新しい取引先 ID の配列を返します。この例では、1 つの ID のみが含まれています。
1public String[] createRecords()
2{
3 // Create two accounts
4 String[] result = new String[2];
5 Account account1 = new Account();
6 Account account2 = new Account();
7
8 // Set some fields on the account object
9 account1.Name = "The Brick Hut";
10 account1.BillingStreet = "403 McAdoo St";
11 account1.BillingCity = "Truth or Consequences";
12 account1.BillingState = "NM";
13 account1.BillingPostalCode = "87901";
14 account1.BillingCountry = "US";
15 // Required Name field is not being set on account2,
16 // so this record should fail during create.
17 // account2.Name = "Camp One Creations";
18 account2.BillingStreet = "25800 Arnold Dr";
19 account2.BillingCity = "Sonoma";
20 account2.BillingState = "CA";
21 account2.BillingPostalCode = "95476";
22 account2.BillingCountry = "US";
23 Account[] accounts = { account1, account2 };
24
25 try
26 {
27 // Call create() to add the accounts
28 SaveResult[] saveResults = binding.create(accounts);
29 // Iterate through the results.
30 // There should be one successful creation
31 // and one failed creation.
32 for (int i = 0; i < saveResults.Length; i++)
33 {
34 if (saveResults[i].success)
35 {
36 Console.WriteLine("Successfully created Account ID: " +
37 saveResults[i].id);
38 result[i] = saveResults[i].id;
39 }
40 else
41 {
42 Console.WriteLine("Error: could not create Account " +
43 "for array element " + i + "."
44 );
45 Console.WriteLine(" The error reported was: " +
46 saveResults[i].errors[0].message + "\n");
47 result[i] = saveResults[i].id;
48 }
49 }
50 }
51 catch (SoapException e)
52 {
53 Console.WriteLine("An unexpected error has occurred: " +
54 e.Message + "\n" + e.StackTrace);
55 }
56
57 return result;
58}応答
saveResult[]