REST API を使用する

学習の目的

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

• Postman アプリケーションにログインし、Salesforce API コレクションの [REST] フォルダーに移動する。
  
• GET SObject Describe リソースを使用する。
  
• REST API を使用して取引先を作成する。
  
• REST API を使用してクエリを実行する。
  

メモ

日本語で受講されている方へ
Challenge は日本語の Trailhead Playground で開始し、かっこ内の翻訳を参照しながら進めていってください。Challenge での評価は英語データを対象に行われるため、英語の値のみをコピーして貼り付けるようにしてください。日本語の組織で Challenge が不合格だった場合は、(1) この手順に従って [Locale (地域)] を [United States (米国)] に切り替え、(2) [Language (言語)] を [English (英語)] に切り替えてから、(3) [Check Challenge (Challenge を確認)] ボタンをクリックしてみることをお勧めします。

翻訳版 Trailhead を活用する方法の詳細は、自分の言語の Trailhead バッジを参照してください。

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 と入力します。
   

クエリの結果を見る前に、このリソースの 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 要求。
  

ここで [Save (保存)] をクリックして、[Send (送信)] をクリックします。

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

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

1. 要求ウィンドウで [Headers (ヘッダー)] をクリックします。
   
2. [Key (キー)] を Accept、[Value (値)] を application/xml として、新しいヘッダーを追加します。
   

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

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

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

取引先を作成する

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

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

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"
}

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

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

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

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

{
"ShippingCity" : "Melbourne"
}

2. [Send (送信)] をクリックします。
   
3. おやおや。「値を入力してください: [Name]」という応答が表示されましたか?
   

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

{
"Name": "Pirate Pete's Parrot Pellets",
"ShippingCity": "Melbourne"
}

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

成功です。

クエリの実行

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

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

SELECT Name From Account WHERE ShippingCity = 'Melbourne'

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

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

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

インテグレーションを記述するときには、応答からこの 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

リソース

• 開発者ガイド: REST API 開発者ガイド
• 外部サイト: HTML URL Encoding Reference (HTML URL エンコードリファレンス)
• 外部サイト: Postman Learning Center (Postman 学習センター)