REST API 開発者ガイド
jComposite サブ要求の結果
Composite サブ要求の結果では、サブ要求の結果を記述します。
プロパティ
| 名前 | 型 | 説明 |
|---|---|---|
| body | データ型は、サブ要求の応答種別によって異なります。 |
このサブ要求のレスポンスボディ。詳細は、サブ要求リソースのドキュメントを参照してください。 サブ要求がエラーを返す場合、ボディにはエラーコードとエラーメッセージが含まれます。エラー応答についての詳細は「状況コードとエラー応答」を参照してください。 |
| httpHeaders | Map<String, String> | このサブ要求のレポートヘッダーとその値。Composite リソースは Content-Length ヘッダーをサポートしないため、サブ要求のレスポンスにも最上位レベルのレスポンスにもこのヘッダーは含まれません。 |
| httpStatusCode | Integer | このサブ要求の HTTP 状況コード。Composite 要求で allOrNone が true に設定されていて、サブ要求がエラーを返す場合、他のすべてのサブ要求は 400 HTTP 状況コードを返します。 |
| referenceId | String | サブ要求で指定された参照 ID。このプロパティにより、サブ要求をその結果に容易に関連付けることができます。 |
例
1{
2 "body": {
3 "id": "001R00000064wdtIAA",
4 "success": true,
5 "errors": []
6 },
7 "httpHeaders": {
8 "Location": "/services/data/v60.0/sobjects/Account/001R00000064wdtIAA"
9 },
10 "httpStatusCode": 201,
11 "referenceId": "refAccount"
12}次の例は、Contact の作成中にエラーが発生したサブ要求への応答を示します。
1{
2 "body" : [ {
3 "message" : "Email: invalid email address: Not a real email address",
4 "errorCode" : "INVALID_EMAIL_ADDRESS",
5 "fields" : [ "Email" ]
6 } ],
7 "httpHeaders" : { },
8 "httpStatusCode" : 400,
9 "referenceId" : "badContact"
10}参照 ID に無効な文字が含まれていた場合の動作および応答
referenceId には、文字、数字、アンダースコア (「_」) のみを使用する必要があります。
無効な文字があった場合の API の動作は、API バージョンとリリースによって異なります。(API バージョンは、Composite 要求の作成に使用されたものです。ただし、このバージョンはサブ要求の url パラメーターに指定された API バージョンと必ずしも同じではありません)。
たとえば、以下の要求を検討します。この要求では、次の操作が試みられます。
- 「Cloudy Consulting」という取引先を作成する。
- 取引先「Mary Smith」を作成して、取引先 Cloudy Consulting にリンクする。
- さらに、「Easy Spaces」という新しい取引先を作成する。
1{
2 "allOrNone": false,
3 "compositeRequest": [
4 {
5 "method": "POST",
6 "body": {
7 "name": "Cloudy Consulting"
8 },
9 "url": "/services/data/vXX.X/sobjects/Account/",
10 "referenceId": "refNewAccount[1]"
11 },
12 {
13 "method": "POST",
14 "body": {
15 "AccountId": "@{refNewAccount[1].id}",
16 "FirstName": "Mary",
17 "LastName": "Smith”
18 },
19 "url": "/services/data/vXX.X/sobjects/Contact",
20 "referenceId": "refNewContact"
21 },
22 {
23 "method": "POST",
24 "body": {
25 "name": "Easy Spaces"
26 },
27 "url": "/services/data/vXX.X/sobjects/Account/",
28 "referenceId": "refNewAccount2"
29 }
30 ]
31}バージョン 51.0 以前
API バージョン 51.0 以前の場合、参照 ID に無効な文字が含まれていると、その参照 ID を使用するすべてのサブ要求が失敗します。この例の場合の応答を次に示します。
1HTTP/1.1 200 OK
2{
3 "compositeResponse" : [
4 {
5 "body" : {
6 "id" : "001R0000006hfeZIAQ",
7 "success" : true,
8 "errors" : [ ]
9 },
10 "httpHeaders" : {
11 "Location" : "/services/data/v51.0/sobjects/Account/001R0000006hfeZIAQ"
12 },
13 "httpStatusCode" : 201,
14 "referenceId" : "refNewAccount[1]"
15 },
16 {
17 "body" : [
18 {
19 "errorCode" : "PROCESSING_HALTED",
20 "message" : "Invalid reference specified. No value for refNewAccount[1].id found in refNewAccount.
21 }
22 ],
23 "httpHeaders" : { },
24 "httpStatusCode" : 400,
25 "referenceId" : "refNewContact"
26 },
27 {
28 "body" : {
29 "id" : "001R0000006hfeeIAA",
30 "success" : true,
31 "errors" : [ ]
32 },
33 "httpHeaders" : {
34 "Location" : "/services/data/v51.0/sobjects/Account/001R0000006hfeeIAA"
35 },
36 "httpStatusCode" : 201,
37 "referenceId" : "refNewAccount2"
38 }
39 ]
40}2 つの取引先が作成されます (最初の取引先が参照 ID 内の無効な文字を使用していても)。ただし、(無効な文字を含む参照 ID を使用して) 取引先を作成する試みは失敗します。
以前のリリースでのバージョン 51.0 以前の応答
上記の応答は、Summer ’21 以降のリリースのものです。Summer ’21 より前のリリースの場合、応答内の「(」または「[」を含む問題のある参照 ID は、切り捨てられました。したがって、応答は次のようになりました。
1{
2 "compositeResponse" : [
3 {
4 "body" : {
5 "id" : "001R0000006hfeZIAQ",
6 "success" : true,
7 "errors" : [ ]
8 },
9 "httpHeaders" : {
10 "Location" : "/services/data/v51.0/sobjects/Account/001R0000006hfeZIAQ"
11 },
12 "httpStatusCode" : 201,
13 "referenceId" : "refNewAccount"
14 },
15 ...
16}Summer ’21 リリース以降、参照 ID は、問題があっても切り捨てられなくなりました。この変更により、応答と要求の各部をより簡単に突き合わせることができます。
バージョン 52.0 以降
API バージョン 52.0 以降の場合、参照 ID に無効な文字が含まれていると、要求全体が失敗します。上記の例に対する応答を次に示します。
1HTTP/1.1 400 Bad Request
2[
3 {
4 "message" : "Provided referenceId ('refNewAccount[1]') must start with a letter or a number, and it can contain only letters, numbers and underscores ('_').",
5 "errorCode" : "JSON_PARSER_ERROR"
6 }
7]まとめ
Null 項目への参照に関する動作
Null 項目への参照がある場合の API の動作は、API のバージョンによって異なります。(API バージョンは、Composite 要求の作成に使用されたものです。ただし、このバージョンはサブ要求の url パラメーターに指定された API バージョンと必ずしも同じではありません)。
たとえば、次の要求について考えてみましょう。この要求は、既存の取引先責任者を探して、@{refContact.FirstName} と @{refContact.LastName} を使用してレコードを作成します。
1POST https://MyDomainName.my.salesforce.com/services/data/vXX.X/composite -H "Authorization: Bearer token"
2
3 "compositeRequest" : [
4 {
5 "method" : "GET",
6 "url" : "/services/data/v51.0/sobjects/Contact/003RO0000016kOuYAI?fields=FirstName,LastName",
7 "referenceId" : "refContact"
8 },
9 {
10 "method" : "POST",
11 "url" : "/services/data/v51.0/sobjects/Contact",
12 "referenceId" : "newContact",
13 "body" : {
14 "FirstName" : "@{refContact.FirstName}",
15 "LastName" : "@{refContact.LastName}",
16 "AccountId" : "001RO000001nGCdYAM"
17 }
18 }
19 ]
20}では、取引先責任者の名が NULL (未設定) の場合はどうなるかについて考えてみます。
バージョン 51.0 以前の応答
API バージョン 51.0 以前では、取引先責任者の FirstName 項目が null であることが原因で、連動サブ要求が失敗します。
1{
2 "compositeResponse" : [
3 {
4 "body" : {
5 "attributes" : {
6 "type" : "Contact",
7 "url" : "/services/data/v51.0/sobjects/Contact/003RO0000016kOuYAI"
8 },
9 "FirstName" : null,
10 "LastName" : "Wong",
11 "Id" : "003RO0000016kOuYAI"
12 },
13 "httpHeaders" : { },
14 "httpStatusCode" : 200,
15 "referenceId" : "refContact"
16 },
17 {
18 "body" : [
19 {
20 "errorCode" : "PROCESSING_HALTED",
21 "message" : "Invalid reference specified. No value for refContact.FirstName found in refContact.
22 Provided referenceId ('refContact.FirstName') must start with a letter or a number,
23 and it can contain only letters, numbers and underscores ('_')."
24 }
25 ],
26 "httpHeaders" : { },
27 "httpStatusCode" : 400,
28 "referenceId" : "newContact"
29 }
30 ]
31}この例では、allOrNone が false に設定されていることを想定しています。true の場合、Composite 要求全体がロールバックされます。「Composite 要求および Collections 要求の allOrNone パラメーター」を参照してください。
バージョン 52.0 以降の応答
API バージョン 52.0 以降では、要求が成功します。
1{
2 "compositeResponse" : [
3 {
4 "body" : {
5 "attributes" : {
6 "type" : "Contact",
7 "url" : "/services/data/v51.0/sobjects/Contact/003RO0000016kOuYAI"
8 },
9 "FirstName" : null,
10 "LastName" : "Wong",
11 "Id" : "003RO0000016kOuYAI"
12 },
13 "httpHeaders" : { },
14 "httpStatusCode" : 200,
15 "referenceId" : "refContact"
16 },
17 {
18 "body" : {
19 "id" : "003RO0000016kRAYAY",
20 "success" : true,
21 "errors" : [ ]
22 },
23 "httpHeaders" : {
24 "Location" : "/services/data/v51.0/sobjects/Contact/003RO0000016kRAYAY"
25 },
26 "httpStatusCode" : 201,
27 "referenceId" : "newContact"
28 }
29 ]
30}親要求で指定されていない項目への参照に関する動作
連動サブ要求では、常に親リクエストで明示的に選択されている項目のみを使用する必要があります。この方法のとおりに設定しなかった場合、API の動作は API バージョンによって異なります。(API バージョンは、Composite 要求の作成に使用されたものです。ただし、このバージョンはサブ要求の url パラメーターに指定された API バージョンと必ずしも同じではありません)。
たとえば、以下の要求を検討します。この要求では、次の操作が試みられます。
- 特定の取引先責任者を見つけます。
- @{refContact.records[0].AccountId} を使用して取引先責任者の取引先 ID を取得します。
ただし、親要求は AccountId を明示的に照会していません。
1POST https://MyDomainName.my.salesforce.com/services/data/vXX.X/composite -H "Authorization: Bearer token"
2
3{
4 "compositeRequest" : [
5 {
6 "method" : "GET",
7 "url" : "/services/data/v51.0/query?q=select Id, Account.Name from Contact where Id='003RO0000016kOuYAI'",
8 "referenceId" : "refContact"
9 },
10 {
11 "method" : "GET",
12 "url" : "/services/data/v50.0/query?q=select Name from Account where Id = '@{refContact.records[0].AccountId}'",
13 "referenceId" : "refAccount"
14 }
15 ]
16}バージョン 51.0 以前の応答
API バージョン 51.0 以前では、まれにこのような要求が成功する場合があります。
バージョン 52.0 以降の応答
API バージョン 52.0 以降では、次の要求は常に失敗します。
1{
2 "compositeResponse" : [
3 {
4 "body" : {
5 "totalSize" : 1,
6 "done" : true,
7 "records" : [
8 {
9 "attributes" : {
10 "type" : "Contact",
11 "url" : "/services/data/v51.0/sobjects/Contact/003RO0000016kOuYAI"
12 },
13 "Id" : "003RO0000016kOuYAI",
14 "Account" : {
15 "attributes" : {
16 "type" : "Account",
17 "url" : "/services/data/v51.0/sobjects/Account/001RO000001nGbUYAU"
18 },
19 "Name" : "City Medical Center"
20 }
21 }
22 ]
23 },
24 "httpHeaders" : { },
25 "httpStatusCode" : 200,
26 "referenceId" : "refContact"
27 },
28 {
29 "body" : [
30 {
31 "errorCode" : "PROCESSING_HALTED",
32 "message" : "Invalid reference specified. No value for refContact.records[0].AccountId found in refContact.
33 Provided referenceId ('refContact.records[0].AccountId') must start with a letter or a number, and it can contain
34 only letters, numbers and underscores ('_')."
35 }
36 ],
37 "httpHeaders" : { },
38 "httpStatusCode" : 400,
39 "referenceId" : "refAccount"
40 }
41 ]
42}このような要求が正常に機能するには、親要求で AccountId を明示的に取得する必要があります。
1{
2 "compositeRequest" : [
3 {
4 "method" : "GET",
5 "url" : "/services/data/v51.0/query?q=select Id, Account.Name, AccountId from Contact where Id='003RO0000016kOuYAI'",
6 "referenceId" : "refContact"
7 },
8 {
9 "method" : "GET",
10 "url" : "/services/data/v50.0/query?q=select Name from Account where Id = '@{refContact.records[0].AccountId}'",
11 "referenceId" : "refAccount"
12 }
13 ]
14}