📢 Attention Salesforce Certified Trailblazers! Maintain your credentials and link your Trailhead and Webassessor accounts by April 19th. Learn more.
close

REST API の使用

学習の目的

この単元を完了すると、次のことができるようになります。
  • ワークベンチにログインし、REST Explorer に移動する。
  • 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 つのコンポーネントで構成されます。要求ヘッダーは要求のメタデータを指定します。リクエストボディは、必要に応じて要求のデータを指定します。指定するデータがない場合は、ボディは要求から除外されます。

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

では取り掛かりましょう。ワークベンチを使用して API コールを行います。ワークベンチは、API を使用して Salesforce 組織を操作するためのツールです。REST 要求は任意の HTTP 送信元から行うことができるため、使用できるツールは他にも多数あります (cURL や Postman など)。ただし、ワークベンチは Salesforce API に特化した分かりやすいフレームワークであるため、完全なインテグレーションを記述する準備が整う前にいろいろ試すのに最適な方法です。
まずは、ワークベンチにログインします。
  1. Trailhead Playground にログインして、ワークベンチに移動します。
  2. [Environment (環境)] で [Production (本番)] を選択します。
  3. [API Version (API バージョン)] で、使用可能な最大の番号を選択します。
  4. 必ず [I agree to the terms of service (サービス契約条件に同意します)] を選択します。
  5. [Salesforce でログイン] をクリックします。

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

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

ワークベンチの REST Explorer

REST Explorer からの REST API コールは、他の HTTP インターフェースから行うのと同じようにできます。テキストボックス内のテキストはリソース URI を表します。便宜上、最上位ドメインは表示された URI から省略されています。たとえば、この URI テキストボックスにあらかじめ入力されているリソースの完全な URI は、https://foo.my.salesforce.com/services/data/v36.0 です。

URI の上のラジオボタンは標準 HTTP メソッドを表します。API コールを行うには、リソース URI を入力し、適切なメソッドを選択し、必要に応じてヘッダーを追加し、[実行] をクリックします。

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

Account オブジェクトに describe を行うことにします。URI テキストボックスの既存のテキストを /services/data/vXX.0/sobjects/account/describe に置き換えます。ここで、XX は使用している API のバージョンに対応します。

Account に describe を行うための URI
ここで、このリソースの URI を詳しく見てみましょう。
  • /services/data — REST API 要求を行うことを指定します
  • /v36.0 — API バージョン番号
  • /sobjects — sObject グルーピングの下のリソースにアクセスすることを指定します
  • /account — アクションの対象となる sObject。この例では Account
  • /describe — アクション。この例では describe 要求

GET メソッドが選択されていることを確認して、[実行] をクリックします。

Account オブジェクトへの describe を行った後の応答

船長、うまくいきました。Account メタデータが画面に表示されます。ワークベンチにより、応答が見やすい形式になっています。未加工の JSON 応答を表示するには、[未加工の応答を表示] をクリックします。

Account オブジェクトへの describe を行った後の JSON 応答

Account メタデータが、HTTP 応答ヘッダーの下に JSON で表示されます。REST API は JSON と XML の両方をサポートしているため、XML 応答を指定するように要求ヘッダーを変更しましょう。HTTP メソッドの横にある [ヘッダー] をクリックします。Accept ヘッダー値の application/jsonapplication/xml に置き換えます。要求ヘッダーは次のようになります。

XML を指定する要求ヘッダー。

[実行] をクリックします。未加工の XML 応答が返されます。成功です。

取引先の作成

次に、SObject リソースと POST メソッドを使用して取引先を作成しましょう。URI テキストボックスの既存のテキストを /services/data/vXX.0/sobjects/account に置き換えます。ここで、XX は使用している API のバージョンに対応します。[POST] を選択します。[Request Body (リクエストボディ)] テキストエリアが表示されます。ここで新しい取引先の項目値を指定します。その前にまず Accept ヘッダーを JSON に戻しましょう。

[ヘッダー] をクリックします。Accept: application/xmlAccept: application/json に戻します。要求は次のようになります。

REST 要求ヘッダー
リクエストボディに次のテキストを入力します。
{
  "Name" : "NewAccount1",
  "ShippingCity" : "San Francisco"
}

[実行] をクリックします。次のような応答が表示されます。

REST API での取引先作成成功の応答

success: true の場合、返された ID を持つ取引先が作成されています。エラーフォルダを展開して、エラーを確認します。

試しに取引先名を指定せずに 2 つ目の取引先も作ってみましょう。リクエストボディ内のテキストを次のテキストで置き換えます。
{
  "ShippingCity" : "San Francisco"
}

[実行] をクリックします。

おやおや、REQUIRED_FIELD_MISSING 応答が表示されましたか? [REQUIRED_FIELD_MISSING] フォルダを展開し、[fields (項目)] フォルダを展開します。展開した応答は次のようになります。

取引先名を指定しないとエラーが表示されます
[名前] は取引先作成の必須項目であるため、サーバは要求を処理せず、エラーが表示されます。幸い、要求を修正するために必要な情報はすべてエラー応答の中にあります。リクエストボディで、名前を「NewAccount2」と指定し、市区郡(納入先) を変更しましょう。リクエストボディ内のテキストを次のテキストで置き換えます。
{
  "Name" : "NewAccount2",
  "ShippingCity" : "New York"
}

[実行] をクリックします。成功しました。

クエリの実行

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

URI テキストボックスのテキストを /services/data/vXX.0/query/?q=SELECT+Name+From+Account+WHERE+ShippingCity='San+Francisco' に置き換えます。ここで、XX は使用している API のバージョンに対応します。

URI を正しくエンコードするために、クエリ文字列の空白を + 文字に置き換えました。HTML URL のエンコードについては、「リソース」セクションのリンクから参照できます。GET メソッドが選択されていることを確認して、[実行] をクリックします。

[records] フォルダを展開します。最初に作成した取引先 NewAccount1 の名前が付いたフォルダが表示されましたか? いいですね。クリックします。次に [attributes (属性)] フォルダをクリックします。URL の横にあるのが、返された取引先のリソース URI です。応答は次のようになります。

Query 応答は 1 つの取引先レコードを返します

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

Node.js および Ruby の例

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

Nforce を使用した Node.js の例

var nforce = require('nforce');

// create the connection with the Salesforce connected app
var org = nforce.createConnection({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET,
  redirectUri: process.env.CALLBACK_URL,
  mode: 'single'
});

// authenticate and return OAuth token
org.authenticate({
  username: process.env.USERNAME,
  password: process.env.PASSWORD+process.env.SECURITY_TOKEN
}, function(err, resp){
  if (!err) {
    console.log('Successfully logged in! Cached Token: ' + org.oauth.access_token);
    // execute the query
    org.query({ query: 'select id, name from account limit 5' }, function(err, resp){
      if(!err && resp.records) {
        // output the account names
        for (i=0; i<resp.records.length;i++) {
          console.log(resp.records[i].get('name'));
        }
      }
    });
  }
  if (err) console.log(err);
});

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 開発者ガイド

Java での Salesforce REST の使用開始

HTML URL エンコードリファレンス

ワークベンチ
Salesforce Classic のコンテンツであることを示すには花のアイコンが使用されます

このモジュールは Salesforce Classic 向けです。ハンズオン組織を起動するときには、Salesforce Classic に切り替えてから、この Challenge を実行してください。

retargeting