REST API を使用する

学習の目的

この単元を完了すると、次のことができるようになります。
  • Postman アプリケーションにログインし、Salesforce API コレクションの [REST] フォルダーに移動する。
  • GET SObject Describe リソースを使用する。
  • REST API を使用して取引先を作成する。
  • REST API を使用してクエリを実行する。

REST のリソースとメソッド

「陸だぞー! 船長、前方に REST 島が見えます。」停泊して API の使用を開始する前に、REST のリソースとメソッドについて説明しましょう。

REST リソースは、1 つのデータレコード、レコードのコレクション、またはクエリなどの情報またはアクションを抽象化したものです。REST API の各リソースは、名前付きの Uniform Resource Identifier (URI) で識別され、標準 HTTP メソッド (HEAD、GET、POST、PATCH、DELETE) を使用してアクセスされます。REST API は、リソース、その URI、およびそれらの間のリンクの使用状況に基づきます。

リソースは、Salesforce 組織との連携に使用します。たとえば、次のような操作が可能です。
  • 使用できる API バージョンに関する概要情報を取得する。
  • Account (取引先)、User (ユーザー) などの Salesforce オブジェクトやカスタムオブジェクトに関する詳細情報を取得する。
  • クエリまたは検索を実行する。
  • レコードを更新または削除する。

REST 要求は、リソース URI、HTTP メソッド、要求ヘッダー、およびリクエストボディの 4 つのコンポーネントで構成されます。要求ヘッダーは要求のメタデータを指定します。リクエストボディは、必要に応じて要求のデータを指定します。指定するデータがない場合は、ボディは要求から除外されます。

先へ進む前に

ここでは、Postman を使用して API コールを行います。REST 要求は任意の HTTP 送信元から行うことができます。Postman は、API を介して Salesforce 組織とやりとりするために使用できる多くのツールの 1 つにすぎません。  

最初のステップは、新しい Trailhead Playground を作成し、それを Postman アプリケーションに接続し、クロスオリジンリソース共有を設定し、Salesforce API コレクションへのフォークを作成することです。「Quick Start: Connect Postman to Salesforce (クイックスタート: Postman を Salesforce に接続する)」を修了することでこれを実行できます。 

Postman アプリケーションの Salesforce コレクションの [REST] フォルダーでリソースを使用して、他の HTTP インターフェースから行うのと同じように Trailhead Playground に対して REST API コールを実行できます。Salesforce API コレクションのリソースを選択すると、メインウィンドウの上部に URI が作成されます。 

Account オブジェクトに対する Describe

では、このしくみを見てみましょう。

SObject Describe リソースを使用します。このリソースは、GET メソッドと組み合わせると、オブジェクトおよびその項目に関するメタデータを返します。Account オブジェクトに describe を行うことにしましょう。 

  1. コレクションで、Salesforce APIs コレクションのフォークを選択します。
  2. [REST] フォルダーをクリックします。
  3. [SObject] をクリックします。
  4. [GET SObject Describe] をクリックします。
  5. メインパネルで [Params (パラメーター)] タブを開きます。
  6. [Path Variables (パス変数)] の下の [SOBJECT_API_NAME] 行の [VALUE (値)] 列に Account と入力します。

SObject Describe の URI が表示されている Postman の要求ウィンドウ。


クエリの結果を見る前に、このリソースの URI を詳しく見てみましょう。

  • GET — この API コールに使用される HTTP メソッド。
  • {{_endpoint}} — 要求が実行される場所。この例では、Salesforce に接続するために 変数の [_endpoint] 項目に Trailhead Playground の URL を追加しました。
  • /services/data — REST API 要求を行うことを指定します。
  • /v {{version}} — API バージョン番号。二重中括弧は、これを変数として設定できることを示します。
  • /sobjects — sObject グルーピングの下のリソースにアクセスすることを指定します。
  • /:SOBJECT_API_Name — アクションの対象となる sObject。この例では Account。
  • /describe — アクション。この例では Describe 要求。
     7.[Save (保存)] をクリックします。
     8.[Send (送信)] をクリックします。

Account オブジェクトのメタデータが表示されている Postman の応答ウィンドウ。

船長、うまくいきました!Account メタデータが画面に表示され、応答は見やすいように書式設定されています。未加工の JSON 応答を表示するには、[Raw (未加工)] をクリックします。

Account メタデータが JSON で表示されます。REST API は JSON と XML の両方をサポートしているため、XML 応答を指定するように要求ヘッダーを変更しましょう。 

  1. 要求ウィンドウで [Headers (ヘッダー)] をクリックします。
  2. [Content-Type] 行の [VALUE (値)] 列の [application/json]application/xml に置き換えます。

要求ヘッダーは次のようになります。

[Headers (ヘッダー)] の [VALUE (値)] 項目が「application/xml」に設定されている Postman の要求ウィンドウ。

     3.[Send (送信)] をクリックします。

未加工の XML 応答が返されます。成功です。

取引先の作成

次に、SObject リソースと POST メソッドを使用して取引先を作成しましょう。 

その前にまず Content-Type ヘッダーを JSON に戻しましょう。

  1. 要求ウィンドウで [Headers (ヘッダー)] をクリックします。
  2. [Content-Type] 行の [VALUE (値)] 列の [application/xml]application/json に置き換えます。
  3. [Save (保存)] をクリックします。

[Headers (ヘッダー)] の [VALUE (値)] 項目が [application/json] に戻されている Postman の要求ウィンドウ。

取引先を作成する手順は次のとおりです。

  1. [REST] の下の [SObject] を選択し、[POST SObject Create] を選択します。
  2. [Params (パラメーター)] タブを開きます。
  3. [Path Variables (パス変数)] の下の [SOBJECT_API_NAME] 行の [VALUE (値)] 列に Account と入力します。
  4. [Body (ボディ)] タブを開きます。
  5. ボディのテキストを次のコードに置き換えます。
{
"Name": "Captain Bly’s Finest Treasure Chests",
"ShippingCity": "Lisbon"
}

SObject POST の URI と、作成する取引先の詳細を含む [Body (ボディ)] 項目が表示されている Postman の要求ウィンドウ。

6.[Save (保存)] をクリックします。
7.[Send (送信)] をクリックします。

作成された取引先の ID が表示されている Postman の応答ウィンドウ。

success: true の場合、返された ID を持つ取引先が作成されています。 

試しに取引先名を指定せずに 2 つ目の取引先も作ってみましょう。 

  1. リクエストボディ内のテキストを次のテキストで置き換えます。
{
"ShippingCity" : "Melbourne"
}

新しい取引先の新しい詳細が表示されている Postman の要求ウィンドウ。

2.[Send (送信)] をクリックします。

おやおや。「値を入力してください: [Name]」という応答が表示されましたか? 

要求に [Name] 項目がないというエラーが表示されている Postman の応答ウィンドウ。

Name は取引先作成の必須項目であるため、サーバーは要求を処理せず、エラーが表示されます。幸い、要求を修正するために必要な情報はすべてエラー応答の中にあります。リクエストボディで、名前を「Pirate Pete's Parrot Pellets」と指定しましょう。 

  1. リクエストボディ内のテキストを次のテキストで置き換えます。
{
"Name": "Pirate Pete's Parrot Pellets",
"ShippingCity": "Melbourne"
}

     2.[Save (保存)] をクリックします。
     3.[Send (送信)] をクリックします。

成功です。

クエリの実行

ここでは、ユーザーが何百もの取引先を作成した場合を想像してみましょう。市区郡 (納入先) がメルボルンになっているすべての取引先の名前を調べたいとします。その場合、Query リソースを使用して SOQL クエリを実行すれば、目的のレコードを正確に見つけることができます。まるで、カスタマイズされた宝の地図です。

  1. [REST] の下の [GET Query] を選択します。
  2. [Params (パラメーター)] タブを開きます。
  3. [Query Params (クエリパラメーター)] の下の [q] 行の [VALUE (値)] 列に次のテキストを貼り付けます。
SELECT Name From Account WHERE ShippingCity = 'Melbourne'

[Params (パラメーター)] タブのキー [q] の値で市区郡 (納入先) がメルボルンである取引先名を求めている Postman の要求ウィンドウ。

4.[保存] をクリックします。
5.[Send (送信)] をクリックします。

クエリは、先ほど作成した取引先 [Pirate Pete's Parrot Pellets] を返します。うまくいきました。

属性を見てみましょう。“url” の横にあるのが、返された取引先のリソース URI です。応答は次のようになります。

市区郡 (納入先) がメルボルンになっている 1 件の取引先が返されたことを示す Postman 応答ウィンドウ。取引先は Pirate Pete's Parrot Pellets。

インテグレーションを記述するときには、応答からこの URI を取得して、取引先に関する詳細にアクセスできます。

Node.js および Ruby の例

ここまでで、REST API を使用して何ができるかということを見てきました。もちろん、Postman からコードの記述へ移行すると、選択したプログラム言語を使用して REST API を操作することになります。幸いにも、エキスパートの Salesforce 開発者によって、REST API の消費プロセスを簡略化するラッパーがいくつかの言語で記述されています。Node.js および Ruby で記述された 2 つのサンプルクエリを次に示します。それぞれ、JSforce および Restforce のラッパーを使用しています。

JSforce を使用した Node.js の例

const jsforce = require("jsforce");const conn = new jsforce.Connection({
  // you can change loginUrl to connect to sandbox or prerelease env.
  // loginUrl : "https://test.salesforce.com"
});
// Log in with basic SOAP login (see documentation for other auth options)
conn.login(
  process.env.USERNAME,
  process.env.PASSWORD + process.env.SECURITY_TOKEN,
  (err, res) => {
    if (err) {
      return console.error("Failed to log in to Salesforce: ", err);
    }
    console.log("Successfully logged in!");
    // Run a SOQL query
    conn.query("SELECT Id, Name FROM Account LIMIT 5", (err, result) => {
      if (err) {
        return console.error("Failed to run SOQL query: ", err);
      }
      // Display query results
      const { records } = result;
      console.log(`Fetched ${records.length} records:`);
      records.forEach(record => {
        console.log(`- ${record.Name} (${record.Id})`);
      });
    });
  }
);

Restforce を使用した Ruby の例

require 'restforce'
# create the connection with the Salesforce connected app
client = Restforce.new :username => ENV['USERNAME'],
  :password       => ENV['PASSWORD'],
  :security_token => ENV['SECURITY_TOKEN'],
  :client_id      => ENV['CLIENT_ID'],
  :client_secret  => ENV['CLIENT_SECRET']
# execute the query
accounts = client.query("select id, name from account limit 5")
# output the account names
accounts.each do |account|
  p account.Name
end
無料で学習を続けましょう!
続けるにはアカウントにサインアップしてください。
サインアップすると次のような機能が利用できるようになります。
  • 各自のキャリア目標に合わせてパーソナライズされたおすすめが表示される
  • ハンズオン Challenge やテストでスキルを練習できる
  • 進捗状況を追跡して上司と共有できる
  • メンターやキャリアチャンスと繋がることができる