REST API の使用

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

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

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

上部のメニューで、[utilities (ユーティリティ)] | [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 のバージョンに対応します。

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

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

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

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

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

{
  "Name" : "NewAccount1",
  "ShippingCity" : "San Francisco"
}

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

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

{
  "ShippingCity" : "San Francisco"
}

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

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

{
  "Name" : "NewAccount2",
  "ShippingCity" : "New York"
}

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

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

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

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

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

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);
});

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