nkjmkzk.net

Force.comにREST APIでデータをインサートしたいな、と思ったとき、標準APIだと単一レコードしかインサートすることができません。今のところ複数レコードをインサートする場合はApex REST（オレオレAPI）を定義する必要があります。またはSOAP APIか。

複数レコード、特に大量のデータをインサートしたい場合は素直にBulk APIを利用するのが賢明でしょう。

Bulk APIは太古の昔から（Summer’10かな？）ある機能ですが、OAuth2.0で得たアクセストークンで利用するBulk APIの使い方をまとめておきたいと思います。（ドキュメントではSOAP APIのlogin()で取得したSESSION IDを使う、という記載しかないので）

なお、コマンドラインで簡単に試せるように例はcurlを使っています。

認証

まずOAuth2.0でアクセストークンとインスタンスURLを取得します。これはこの記事の範疇を超えるのでこのあたりの記事を別途参照ください。
また、以下の例はではインスタンスURLはhttps://na14.salesforce.comとして話を進めます。

ジョブの登録

Bulk APIではまずジョブを登録し、そのジョブに後からバッチとよばれるデータのリストをアサインすることで処理を進めます。ジョブ登録時には最低限下記のような指示をおこないます。

• object : 操作対象のオブジェクト
• operation : 操作 => delete, insert, query, upsert, update, hardDelete
• contentType : バッチ（データリスト）のフォーマット => XML,CSV あるいはそのZIPアーカイブ

例

curl https://na14.salesforce.com/services/async/26.0/job/ -H 'X-SFDC-Session: あなたのアクセストークン' -H "X-PrettyPrint:1" -H "Content-Type: application/xml" -d @register_job.xml -X POST

通常のREST APIでは、URLがhttps://インスタンス.salesforce.com/services/data/v26.0/からはじまりますが、Bulk APIではhttps://インスタンス.salesforce.com/services/async/26.0/からはじまることに注意してください。data => async, v26.0 => 26.0です。後者はややこしいですね。

そして、アクセストークンはX-SFDC-Session:というヘッダーにセットします。通常のRESTだとここは　Authorization: Bearer アクセストークン　となりますよね。

そして、上記のcurlコマンドではregister_job.xmlというファイルをジョブの指示書として指定しています。このファイルの中身も見ておきましょう。

<?xml version="1.0" encoding="UTF-8"?>
<jobInfo xmlns="http://www.force.com/2009/06/asyncapi/dataload">
    <operation>insert</operation>
    <object>myObject__c</object>
    <contentType>CSV</contentType>
</jobInfo>

myObject__cというオブジェクトに、CSVフォーマットのデータをインサートするジョブですよ、という指定ですね。

このジョブ登録が完了するとXMLのレスポンスが返ってきます。特に重要なのはその中のid要素です。このid要素にはジョブIDがセットされており、このジョブIDはジョブにバッチを追加する際に必要になります。

ジョブにバッチを追加

先ほど登録したジョブにデータをアップロードして処理を開始させます。データはジョブ登録の際にcontentTypeで指定したフォーマットでなければなりません。 例

curl https://na14.salesforce.com/services/async/26.0/job/ジョブID/batch -H 'X-SFDC-Session: あなたのアクセストークン' -H "Content-Type:text/csv" -X POST --data-binary @myData.csv

上記コマンドではmyData.csvというファイルをデータリストとして指定しています。CSVファイルは一行目にフィールドのAPI名、二行目以降にそのフィールドに対応するデータが記載されたものになります。
また、curlコマンドでの注意点ですが、ファイルを指定するときに-dオプションで指定してしまうとCSVファイルの改行が削除され、フォーマットが崩れてしまいます。–data-binaryオプションで指定することによって改行を維持したままアップロードできます。

ジョブの終了

ジョブは一つのバッチが終了しても、放っておいてはオープンされたままになります。用が済んだら閉じましょう。

例

curl https://na14.salesforce.com/services/async/26.0/job/ジョブID -H 'X-SFDC-Session: あなたのアクセストークン' -H "X-PrettyPrint:1" -H "Content-Type: application/xml" -d @close_job.xml -X POST

上記コマンドではジョブの指示書としてclose_job.xmlというファイルを指定しています。
このファイルも同様にみておきましょう。

<?xml version="1.0" encoding="UTF-8"?>
<jobInfo xmlns="http://www.force.com/2009/06/asyncapi/dataload">
    <state>Closed</state>
</jobInfo>

シンプルですね。state要素をClosedにセットするだけです。

これでBulk APIの一つのトランザクションが完了します。
より詳細な情報はドキュメントを参照ください。
Bulk API Developer’s Guide

Enjoy.

先日、Force.comのREST APIをphpから利用する際に便利なOAuth Toolkitを抜本的に書き直しました。新しくなってさらに簡単になったこのツールの使い方をご紹介しておきます。

まずはダウンロード。こちらからどうぞ。Webサーバの適当なディレクトリに保存してください。

https://github.com/nkjm/Force.com-OAuth-Toolkit-for-PHP

次に認証が必要なスクリプトにoauth.phpをインポートします。

$ vi index.php
require_once 'oauth.php';

同スクリプトでoauthクラスのインスタンスを作成します。

$oauth = new oauth(CLIENT_ID, CLIENT_SECRET, CALLBACK_URL, [LOGIN_URL], [CACHE_DIR]);

• LOGIN_URLとCACHE_DIRはオプショナルです。
• CACHE_DIRは認証後に発行されるaccess token, refresh token, instance urlを保存するためのディレクトリです。auth_with_password()を用いた場合のみ利用されます。

oauthのインスタンスメソッドでOAuth認証を実施します。認証には2通りあります。1つはアクセスコードを用いる方法で、ユーザごとに認証を要する場合に利用します。

$oauth->auth_with_code([LIFETIME]);

LIFETIMEはオプショナルで、アクセストークンをリフレッシュする間隔を分単位で指定できます。

もう1つはusername/passwordを用いる方法で、不特定のユーザからアクセスを受け付ける場合に利用します。HomePageのバックエンドとしてForce.comを接続し、問い合わせ情報などをForce.comに取り込みたい場合などに適しています。

$oauth->auth_with_password(USERNAME, PASSWORD);

USERNAME, PASSWORDはあるユーザをゲストアカウントと見たてて、その情報をセットします。

認証が成功すると$oauthには下記のパラメータにそれぞれaccess token, refresh token, instance urlの情報がセットされ、この情報を使ってREST APIにアクセスできます。

• $oauth->access_token
• $oauth->refresh_token
• $oauth->instance_url

oauth_with_password()を使用する場合は事前にCACHE_DIRにしているディレクトリ（デフォルトではスクリプトと同じディレクトリ）が存在し、適切なパーミッションが設定されている必要があります。パーミッションはWebサーバプロセスのオーナーユーザー／グループの（一般的にはnobodyなど）からのRead/Writeアクセスが必要です。

OAuth Toolkitのセットアップと実行はこれだけです。

下記のサンプルコードで全体の流れをつかんでいただければ幸いです。

require_once "oauth.php";

// You have to change following paramenter depending on your remote access setting.
define('CLIENT_ID', '3MVG9rFJvQRVOvk40dRq5u_ZA0eT2KvZCvZq.XeA1hFtgc3PITGlLMp3V_kKIwtc6IaEGWkIO3cOu0IgVmujh');
define('CLIENT_SECRET', '1136279981407985294');
define('CALLBACK_URL', 'https://sugoisurvey.nkjmkzk.net');

$oauth = new oauth(CLIENT_ID, CLIENT_SECRET, CALLBACK_URL);
$oauth->auth_with_code();

$query = "select name from session__c";
$url = $oauth->instance_url . "/services/data/v24.0/query?q=" . urlencode($query);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Authorization: OAuth " . $oauth->access_token));
$response = json_decode(curl_exec($curl), true);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ( $status != 200 ) {
    die("curl failed");
}
curl_close($curl);
return($response);

2012.05追記

OAuth Toolkitはスクラッチから再開発されました。この記事は古いものです。

あたらしいOAuth Toolkitの使い方はこちら。

Force.comの外部にホストしているWebサービスからForce.comに対してREST APIでアクセスするためには認証が必要です。

自分でOAuth認証クライアントのコードをスクラッチから書くのはホネの折れる作業なので、php実行環境でのToolkitを作成してGithubに公開しておきました。

Force.com OAuth Toolkit for PHP

使い方をざっくりと説明します。

必要なもの

• Force.comの外部で稼動しているphp実行環境
• cURLがphp実行環境で有効になっていること
• JSONがphp実行環境で有効になっていること
• SSLがphp実行環境で有効になっていること
• アクセスするForce.comの組織
• APIがForce.com組織およびプロファイルで有効になっていること

インストールとセットアップ

php実行環境のドキュメントルートにoauthディレクトリを作成。

$ export DOCUMENT_ROOT='/srv/nginx/html/test'
$ mkdir ${DOCUMENT_ROOT}/oauth

作成したoauthディレクトリ配下にGithubからoauth.phpとconfig.phpをダウンロードして保存。

[何らかの方法でoauth.phpとconfig.phpをダウンロード]

$ ls ${DOCUMENT_ROOT}/oauth
config.php
oauth.php

Force.com側でRemote Accessレコードを作成。
[あなたの名前]->Setup->Develop->Remote Accessから。重要なのはCallback URL。下記のフォーマットで。プロトコルはHTTPSである必要があります。

https://[あなたのサーバ]/oauth/oauth.php

php実行環境のconfig.phpを編集してCLIENT_IDとCLIENT_SECRETを設定。それぞれの値はRemote Accessレコードを参照。

$ vi ${DOCUMENT_ROOT}/oauth/config.php
<?php
define("CLIENT_ID", "[あなたのConsumer Key]");
define("CLIENT_SECRET", "[あなたのConsumer Secret]");
define("LOGIN_URI", "https://login.salesforce.com");
?>

認証が必要なphpファイルの最上部に下記を追記

# vi ${DOCUMENT_ROOT}/index.php
<?php
session_start();
if (!isset($_SESSION['access_token']) || !isset($_SESSION['instance_url'])) {
     $_SESSION['oauth_return'] = $_SERVER['PHP_SELF'];
     header( 'Location: oauth/oauth.php' );
} 

[あなたのコードが続く]
?>

これで完了。

ブラウザで認証が必要なコンテンツにアクセスすれば、未認証の場合は一度Salesforceのログインサイトにリダイレクトされます。そこで認証または認可を行い、リダイレクト元に再度リダイレクトされます。

その後のアクセスでは$_SESSION['access_token']にアクセストークンが、$_SESSION['instance_url']にインスタンスのURLが保存されますので、この2つをもってForce.comのREST APIをつつくことで認可済みの状態を維持することができます。

このOAuthのアクセストークンを用いてREST APIにアクセスするサンプルコードを最後に紹介しておきます。下記はChatterからFeedとその発信者を取得して表示するコードです。

$url = $_SESSION['instance_url'] . "/services/data/v23.0/chatter/feeds/news/me/feed-items";
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Authorization: OAuth " . $_SESSION['access_token']));

$json_response = curl_exec($curl);
$response = json_decode($json_response, true);

echo "<!DOCTYPE html><html><head><meta http-equiv='Content-Type' content='text/html; charset=UTF-8'></head><body>\n";
foreach ((array) $response['items'] as $feed) {
    echo $feed['actor']['name'] . " says \n";
    echo $feed['body']['text'] . "<br/>\n";
}
echo "</body></html>\n";

参考情報

• Interact with the Force.com REST API from PHP