レコードを編集するための UI の作成

学習の目的

この単元を完了すると、次のことができるようになります。

ユーザインターフェース API に対する要求を実行してレコードを更新する。
複合項目の特殊な点を説明する。
ユーザインターフェース API に対する要求を実行して複合項目を更新する。

ワークベンチを使用したユーザインターフェース API のコール

ワークベンチを使用して API コールを実行し、Universal Containers レコードを更新します。

ワークベンチは、API を使用して Salesforce 組織を操作するためのツールです。REST 要求は任意の HTTP 送信元から行うことができるため、使用できるツールは他にも多数あります (cURL や Postman など)。ただし、ワークベンチは Salesforce API に特化した分かりやすいフレームワークであるため、完全なインテグレーションを記述する準備が整う前にいろいろ試すのに最適な方法です。

まずは、ワークベンチにログインします。

Trailhead Playground にログインします。別のブラウザタブで、ワークベンチに移動します。
[Environment (環境)] で [Production (本番)] を選択します。
[API Version (API バージョン)] で、使用可能な最大の番号を選択します。
必ず [I agree to the terms of service (サービス契約条件に同意します)] を選択します。
[Login with Salesforce (Salesforce でログイン)] をクリックします。

ワークベンチのホームページが表示されます。このモジュールでは、ワークベンチの数あるツールの 1 つである REST Explorer のみを使用します。

上部のメニューで、[utilities (ユーティリティ)] | [REST Explorer] を選択します。

REST Explorer からのユーザインターフェース API コールは、他の HTTP インターフェースから行うのと同じようにできます。

/ui-api/object-info リソースへのワークベンチコール。

API コールを行うには、リソース URI を入力し、HTTP メソッドを選択し、必要に応じてリクエストボディを追加し、[Execute (実行)] をクリックします。

今度はワークベンチを使用して要求を実行しましょう! この URI を入力し、[GET] を選択し、[Execute (実行)] をクリックします。

/services/data/v50.0/ui-api/object-info

応答は、ユーザインターフェース API および Trailhead Playground でサポートされるすべてのオブジェクトのリストです。

メモ

エラーが発生した場合は、URI に Workbench に表示される API バージョンが含まれていることを確認します。

レコードの編集

Record Viewer アプリケーションでユーザがクリックしてレコードを作成すると、/ui-api/record-ui/{recordIds} への要求で表示モードと編集モードの両方が要求されます。JSON 応答には各モードのレイアウトが含まれるため、ユーザが実際にレコードを編集するときには、アプリケーションには編集用のフォームを作成するのに十分な情報があります。

let recordViewUrl = action.creds.instanceUrl + '/services/data/v50.0/ui-api/record-ui/' 
  + action.recordId + '?formFactor=' + action.context.formFactor + '&layoutTypes=Full&modes=View,Edit';

ユーザがレコードを編集できるように、アプリケーションでは編集可能な項目を含むフォームが表示されます。ユーザが [Save (保存)] をクリックすると、recordUpdater.js saga が /ui-api/records/{recordId} リソースに対する PATCH 要求を実行して更新を行います。

let recordDataUrl = action.creds.instanceUrl + '/services/data/v50.0/ui-api/records/' + action.recordId;

では、ワークベンチを使用してレコードを更新し、変更を Record Viewer アプリケーションと Salesforce で表示してみましょう。まず、更新するレコードの ID が必要です。

Record Viewer アプリケーションの [Recent Items (最近使ったデータ)] で、Universal Containers をクリックします。PATCH 要求で使用するレコード ID をコピーします。アプリケーションの上部で項目から ID をコピーすることも、[Show JSON (JSON を表示)] をクリックし、[records (レコード)] をクリックしてレコード ID を表示することもできます。次のサンプルに似た JSON が表示されます。

"records": {
    "0010V00002JoU6hQAF": {
      "apiName": "Account",
      "childRelationships": {},
      "eTag": "412642214dd7ef34eb3e2bae5e645dcc",

ワークベンチで [Utilities (ユーティリティ)] | [REST Explorer] をクリックします。
次の設定を入力します。
- HTTP メソッド: PATCH
- リソース URI: /services/data/v50.0/ui-api/records/{recordId}
  {recordId} を Universal Containers レコードの ID に置き換えます。
- リクエストボディ:
```
{
    "fields" : {
        "Website": "www.example.com",
        "Rating" : "Hot"
    }
}
```
[実行] をクリックします。
Record Viewer アプリケーションに戻り、[View Record (レコードを表示)] をクリックして Universal Containers レコードを再読み込みします。
[Website (Web サイト)] および [Rating (評価)] 項目が更新されています。Salesforce 組織でもこの変更を表示できます。

複合項目の編集

複合項目の更新には少し注意が必要です。複合項目は、数値や文字列などプリミティブデータ型の複数の項目をグループ化して、場所や住所などの複雑なデータ型を表します。複合項目はコンポーネント項目で構成されます。

たとえば、BillingAddress は複合項目です。そのコンポーネント項目は、BillingStreet、BillingCity、BillingState、BillingCountry です。複合項目の値と、コンポーネント項目の値は、どちらも Salesforce に保存されている同じ基礎データに対応付けられ、その値は常に同じです。

複合項目は参照のみです。複合項目を編集するには、そのコンポーネント項目を更新する必要があります。

項目が複合項目の場合、その objectInfo.fields[fieldName].compound プロパティは true です。

"BillingAddress" : {
  "apiName" : "BillingAddress",
  "calculated" : false,
  "compound" : true,
  "compoundComponentName" : null,
  "compoundFieldName" : null,
  ...

項目が複合項目のコンポーネントである場合、その objectInfo.fields[fieldName].compoundComponentName プロパティにコンポーネント名が含まれ、その objectInfo.fields[fieldName].compoundFieldName プロパティに複合項目の名前が含まれます。

"BillingCity": {
  "apiName": "BillingCity",
  "calculated": false,
  "compound": false,
  "compoundComponentName": "City",
  "compoundFieldName": "BillingAddress",
  ...

住所を更新するには、コンポーネント項目を別個の入力として指定します。たとえば、BillingAddress は複合項目であるため参照のみです。更新するには、その各部分を更新する必要があります。

ワークベンチで [Utilities (ユーティリティ)] | [REST Explorer] をクリックします。
次の設定を入力します。
- HTTP メソッド: PATCH
- リソース URI: /services/data/v50.0/ui-api/records/{recordId}
  {recordId} を Universal Containers レコードの ID に置き換えます。
- リクエストボディ:
```
{
  "fields" : {
    "BillingPostalCode": "98112",
      "BillingState": "WA",
      "BillingCity": "Seattle",
      "BillingStreet" : "123 Main Street",
      "BillingCountry" : "USA"
  }
}
```
[実行] をクリックします。
Record Viewer アプリケーションに戻り、[View Record (レコードを表示)] をクリックして Universal Containers レコードを再読み込みします。

Record Viewer アプリケーションで更新されたレコードを表示します。

表示モードでは、複合項目を 1 つの項目として表示すると見やすくなります。表示モードの複合項目。

編集モードでは、ユーザが変更できるようにコンポーネント項目を表示します。レコードを編集モードで表示するには、[Edit (編集)] をクリックします。編集モードの複合項目に各コンポーネント項目が表示されています。

ETag

ETag は応答を一意に識別する HTTP ヘッダーです。アプリケーションは、If-None-Match HTTP 要求ヘッダーを使用して、ETag を Salesforce に渡します。

Salesforce が返送しようとしている JSON が手元の JSON と同じである場合、HTTP 304 (変更なし) が発生します。つまり、アプリケーションでもう一度ペイロードを並列化する必要はありません。

ETag を使用すると、ネットワークトラフィックとデータ使用が削減され、アプリケーションのパフォーマンスが向上します。オブジェクトおよびレイアウトメタデータペイロードの場合、頻繁に変更されるものではないため有効です。

ユーザインターフェース API からのすべての応答には eTag プロパティがあります。このプロパティには、リソースに対応する不透明な識別子である ETag HTTP ヘッダーが含まれます。/ui-api/record-ui/{recordIds} からの折りたたまれた応答で eTag プロパティと識別子を確認できます。

root:{} 5 items
eTag:19d49d8dfba088456235a7cacc38138a
layoutUserStates:{} 1 item
layouts:{} 1 item
objectInfos:{} 1 item
records:{} 1 item

JSON 応答の layouts、objectInfos、および records を展開すると、そうしたネストされた応答にもそれぞれ eTag プロパティが含まれていることがわかります。これは、UI API に、こうしたネストされた各応答を最上位の応答として返すリソースがあるためです。/ui-api/record-ui/{recordIds} のような集約されたペイロードでは、ペイロードのチャンクごとに ETag があります。

次のリソースは、ネストされた応答を最上位の応答として返します。

/ui-api/layout/{objectApiName}
/ui-api/object-info/{objectApiName}
/ui-api/records/{recordId}

リソース

User Interface API Developer Guide (ユーザインターフェース API 開発者ガイド)

トピック