この文章は Salesforce 機械翻訳システムを使用して翻訳されました。詳細はこちらをご参照ください。

Composite Graph

Composite Graph により、1 回のコールで一連の REST API 要求を実行する Composite 要求の実行が強化されます。

通常の Composite 要求では、一連の REST API 要求を単一のコールを実行できます。また、1 つの要求の出力を、後続の要求の入力として使用できます。
これは、Composite Graph がより複雑で完全な一連の関連オブジェクトおよびレコードを組み合わせることによって拡張されます。
また、Composite Graph では、特定の一連の操作のステップがすべて完了または終了していることが保証されます。これによって、成功と失敗が混在した結果を確認する必要がなくなりました。
通常の Composite 要求では、サブ要求の数は 25 に制限されています。Composite Graph はこの制限を 500 に拡大します。これによって、単一の API コールにはるかに大きな能力が与えられます。

Composite Graph の定義

一般に、グラフは接続されたノードのコレクションです。

Composite Graph 操作のコンテキストでは、ノードは Composite サブ要求です。たとえば、ノードは次のような Composite サブ要求になる場合があります。

1{
2    "url" : "/services/data/v56.0/sobjects/Account/",
3    "body" : {
4        "name" : "Cloudy Consulting"
5    },
6    "method" : "POST",
7    "referenceId" : "reference_id_account_1"
8}

各ノードで特徴的なのはレコードを表すエンドポイントです。

Composite Graph 操作の場合、次の URL のみが Composite 要求でサポートされます。

URL	サポートされている HTTP メソッド
`/services/data/vXX.X/sobjects/sObject`	POST 「sObject Basic Information」を参照してください。
`/services/data/vXX.X/sobjects/sObject/id`	DELETE、GET、PATCH 「sObject Rows」を参照してください。
`/services/data/vXX.X/sobjects/sObject/customFieldName/externalId`	DELETE、GET、PATCH、POST 「sObject Rows by External ID」を参照してください。

Composite Graph は方向付けされる場合があります。つまり、あるノードで他のノードの情報を使用する場合があります。たとえば、取引先責任者を作成するノードが取引先ノードの ID を使用して取引先責任者を取引先に関連付けることができます。

次に例を示します。

1{
2   "graphs": [{
3      "graphId": "graph1",
4      "compositeRequest": [{
5            "body": {
6               "name": "Cloudy Consulting"
7            },
8            "method": "POST",
9            "referenceId": "reference_id_account_1",
10            "url": "/services/data/v56.0/sobjects/Account/"
11         },
12         {
13            "body": {
14               "FirstName": "Nellie",
15               "LastName": "Cashman",
16               "AccountId": "@{reference_id_account_1.id}"
17            },
18            "method": "POST",
19            "referenceId": "reference_id_contact_1",
20            "url": "/services/data/v56.0/sobjects/Contact/"
21         }
22      ]
23   }]
24}

JSON での Composite Graph の定義

Composite Graph は JSON で次のように定義されます。

1{
2    "graphId" : "graphId",
3    graph
4}

つまり、次のようになります。ここで、各 compositeSubrequest は Composite サブ要求です。

1{
2    "graphId" : "graphId",
3    "compositeRequest" : [
4        compositeSubrequest,
5        compositeSubrequest,
6        ...
7    ]
8}

graphId パラメータにより、応答を表示するときにグラフを識別できます。数値である必要はありませんが、次の制限に従う必要があります。

各 Composite Graph 操作内で一意である必要があります。
英数字で始まる必要があります。
40 文字未満である必要があります。
ピリオド (「.」) を含めることはできません。

1 つの Composite Graph 要求で 1 つ以上の Composite Graph を使用できます。「Composite Graph の使用」を参照してください。

例: Composite Graph 要求を使用して Account、Contact、Campaign、Opportunity、Lead、CampaignMember を作成

この例では、次のアクションを実行する Composite Graph を示します。

Account 1 を作成する。
Account 1 の子として Account 2 を作成する。
作成:
1. Account 2 にリンクされる Contact 1。
2. Contact 1 の部下である Contact 2。
3. Contact 2 の部下である Contact 3。
Campaign を作成する。
Account 2 および Campaign にリンクされる Opportunity を作成する。
Lead を作成する。
Lead および Campaign にリンクされる CampaignMember を作成する。

ネストされたグラフの例

このグラフの JSON は次のようになります。

1{
2   "graphId" : "1",
3   "compositeRequest" : [
4      {
5         "url" : "/services/data/v56.0/sobjects/Account/",
6         "body" : {
7           "name" : "Cloudy Consulting",
8           "description" : "Parent account"
9         },
10         "method" : "POST",
11         "referenceId" : "reference_id_account_1"
12      },
13      {
14         "url" : "/services/data/v56.0/sobjects/Account/",
15         "body" : {
16           "name" : "Easy Spaces",
17           "description" : "Child account",
18          ."ParentId" : "@{reference_id_account_1.id}"
19         },
20         "method" : "POST",
21         "referenceId" : "reference_id_account_2"
22      },
23      {
24         "url" : "/services/data/v56.0/sobjects/Contact/",
25         "body" : {
26           "FirstName" : "Sam",
27           "LastName" : "Steele",
28           "AccountId" : "@{reference_id_account_2.id}"
29         },
30         "method" : "POST",
31         "referenceId" : "reference_id_contact_1"
32      },
33      {
34         "url" : "/services/data/v56.0/sobjects/Contact/",
35         "body" : {
36           "FirstName" : "Charlie",
37           "LastName" : "Dawson",
38           "ReportsToId" : "@{reference_id_contact_1.id}"
39         },
40         "method" : "POST",
41         "referenceId" : "reference_id_contact_2"
42      },
43      {
44         "url" : "/services/data/v56.0/sobjects/Contact/",
45         "body" : {
46           "FirstName" : "Nellie",
47           "LastName" : "Cashman",
48           "ReportsToId" : "@{reference_id_contact_2.id}"
49         },
50         "method" : "POST",
51         "referenceId" : "reference_id_contact_3"
52      },
53      {
54         "url" : "/services/data/v56.0/sobjects/Campaign/",
55         "body" : {
56           "name" : "Spring Campaign"
57         },
58         "method" : "POST",
59         "referenceId" : "reference_id_campaign"
60      },
61      {
62         "url" : "/services/data/v56.0/sobjects/Opportunity/",
63         "body" : {
64           "name" : "Opportunity",
65           "stageName" : "Value Proposition",
66           "closeDate" : "2025-12-31",
67           "CampaignId" : "@{reference_id_campaign.id}",
68           "AccountId" : "@{reference_id_account_2.id}"
69         },
70         "method" : "POST",
71         "referenceId" : "reference_id_opportunity"
72      },
73      {
74         "url" : "/services/data/v56.0/sobjects/Lead/",
75         "body" : {
76           "FirstName" : "Belinda",
77           "LastName" : "Mulroney",
78           "Company" : "Klondike Quarry",
79           "Email" : "bmulroney@example.com"
80         },
81         "method" : "POST",
82         "referenceId" : "reference_id_lead"
83      },
84      {
85         "url" : "/services/data/v56.0/sobjects/CampaignMember/",
86         "body" : {
87           "CampaignId" : "@{reference_id_campaign.id}",
88           "LeadId" : "@{reference_id_lead.id}"
89         },
90         "method" : "POST",
91         "referenceId" : "reference_id_campaignmember"
92      }
93    ]
94}

例: リソースに関する詳細を GET してから、Composite Graph 要求で使用

この例では、リソースで GET を使用してから、以降の要求でそのリソースのプロパティを使用する方法を示します。

1{
2   "graphs" : [
3      {
4         "graphId" : "graph1",
5         "compositeRequest" : [
6            {
7               "method" : "GET",
8               "url" : "/services/data/v56.0/sobjects/Account/001R0000003fSRrIAM",
9               "referenceId" : "refAccount"
10            },
11            {
12               "body" : {
13                  "name" : "Amazing opportunity for @{refAccount.Name}",
14                  "StageName" : "Stage 1",
15                  "CloseDate" : "2025-06-01T23:28:56.782Z",
16                  "AccountId" : "@{refAccount.Id}"
17               },
18               "method" : "POST",
19               "url" : "/services/data/v56.0/sobjects/Opportunity",
20               "referenceId" : "newOpportunity"
21            }
22         ]
23      }
24   ]
25}

グラフ深度

親を持たないノードは深度 1 とみなされます。
もう 1 つのノードの深度は深度 1 からそのノードまでのグラフのエッジの最大数です。2 つのノード間のエッジは、1 つのノードでもう 1 つのノードのプロパティ (@{reference_account.id} など) を使用している場合に発生します。

異なる深度でネストされたノードを示す Composite Graph の例

AllOrNone パラメータ

標準の Composite 操作では、エラーが発生した場合の動作を制御するのは allOrNone パラメータのみです。値が true の場合、Composite 要求全体がロールバックされます。値が false の場合、失敗したサブ要求に連動しない残りのサブ要求が実行されます。連動サブ要求は実行されません。これにより、処理済みのレコードと未処理のレコードが混在する場合があります。

Composite Graph には、各グラフがそのすべてのサブ要求を正常に完了するか、または完全にロールバックされるかが保証されるという利点があります。つまり、allOrNone パラメータは暗黙的に各グラフで true になっているとみなされます。したがって、グラフ内に処理済みのレコードと未処理のレコードが混在することはありません。

グラフの独立性を確保するために、次のルールが適用されます。

1 つのグラフのサブ要求がもう 1 つのグラフのサブ要求を参照することはない。
1 つの Composite Graph 操作の各グラフは独立している必要がある。1 つのグラフを正常に処理できなかった場合、それによって同じ操作内の他のグラフの処理が妨げられるようなことがあってはなりません。

ベストプラクティス

一般にグラフは、できるだけ小さくしてください。たとえば、500 個のノードを含む 1 個のグラフを作成するよりも、10 個のノードを含む 50 個のグラフを作成した方が効率的です。グラフを小さくすることには、次の 2 つの利点があります。

あるグラフ内で 1 つの項目が失敗した場合、ロールバックされるのは、そのグラフ内の項目のみです。このため、エラーの処理が容易になります。
サーバでグラフを処理するときは、グラフを複数に分けて小さくした方が、処理の速度や効率が向上します。

例: Composite Graph ジョブの送信

Composite Graph ジョブを送信する方法を示す例については、「Composite Graph の使用」を参照してください。

REST API 開発者ガイド