SalesforceのAPIを知って連携ツールを使いこなそう 【第３回】

  • Posted on

こんにちは、荒木です。

第１回では Apex Data Loader を例に、第２回では弊社のクラウド型連携サービス「SkyOnDemand」の読み取り系の処理を例に挙げて、使用しているAPIについて紹介してきました。

連載最後のエントリでは SkyOnDemand の書き込み系の処理を例に、使用しているAPIについて紹介したいと思います。

データ書き込み系のコンポーネント

SkyOnDemandでは Apex Data Loader と同じように、SOAP API と Bulk API から選択することができます。それぞれのAPIを使用するアダプタが個別に用意されています。

Bulk API についてはまたの機会として、今回は標準的な SOAP API を使用するアダプタについて紹介したいと思います。アダプタに用意されている書き込みコンポーネントは以下です。

■ Salesforce アダプタ　- SOAP API

コンポーネント名 コール 概要
データ書き込み（INSERT） create() データの追加を行います。
データ書き込み（UPDATE） update() データの更新を行います。
キーにはID以外を指定したり、一致するデータが存在しなかった場合に自動的に追加を行うことも可能です。この場合、アダプタが事前にIDの検索を行います。
データ書き込み（DELETE） delete() データの削除を行います。
キーにはID以外を指定することも可能です。この場合、アダプタが事前にIDの検索を行います。
データ書き込み（UPSERT） upsert() データの追加・更新を行います。
マルチデータ書き込み create()、
update()、
delete()		 複数のオブジェクトのレコードをまとめて追加・更新または削除します。入力データは決められたフォーマットのファイルに準備します。APIの仕様として最大200件ごとの扱いになります。


例えば、データ書き込み（INSERT）では次の画面のような設定GUIが用意されています。他のコンポーネントにも同じような設定GUIが用意されているため、簡単に使い分けることが可能です。

tec_skyondemand_21

考慮すべき点と解決する機能

APIからデータ書き込みの操作を行う場合、考慮しておかなければならない点があります。必ず知っておくべき3つの内容と、連携ツールに用意されている解決するための機能を紹介したいと思います。


バッチサイズとAPI要求数

SOAP API の書き込み系コールでは、一回のリクエストに最大200件までのレコードを含めることができます。この件数のことをバッチサイズと表現します。例えば更新元のデータセットが10,000件であった場合、200件毎に分割してリクエスト送信を50回に分けて送信する必要があります。アダプタでは設定するコンポーネント毎にバッチサイズを指定することができ、自動的に分割してリクエストを行います。

ここで注意すべき点は、24時間以内にリクエストできるAPI要求数の合計に制限があることです。制限値は組織ごとのライセンスにより変わります。ログインしている組織の制限値と要求数は、[設定]-[組織プロファイル]-[組織情報]の[API 要求数 (この 24 時間以内)]で確認することができます。ライセンスによる制限値の算出方法は、こちらを参照ください。

予め処理対象のトランザクション件数とバッチサイズから必要なAPI要求数を算出しておくべきでしょう。特に、他のユーザもAPIを使用している場合や、初期データ移行など大容量のデータを操作する場合には注意が必要です。

尚、第２回で紹介したクエリーコールでは、レスポンスのバッチサイズは最大2,000となっており、書き込み系コールよりも必要なAPI要求数は少なくなります。


更新結果をハンドリングする

更新操作は「1件ごと」もしくは「200件ごと」にコミットされます。APIの仕様ではデフォルトは「1件ごと」です。その場合、たとえばリクエストに正常なレコードと不正なレコードが含まれていると、正常なレコードのみ保存されます。よって、API要求元はどのレコード操作が成功・失敗したのかを判断し、警告を出すなどの対応が必要となります。

SOAP API では、リクエストの入力データセットに対応する結果データセットがレスポンスとして返されます。結果データセットには、採番されたID、成功フラグ、エラーメッセージなどが含まれます。

SkyOnDemandでは、アダプタが自動的に結果データセットを取得し入力データに紐付けます。処理の後続では次のような画面で必要な項目だけををマッピングして簡単に扱うことができます。例えば、失敗データだけをフィルタリングしてCSV出力したり、任意の項目とエラーメッセージからメール本文を作成したりなど自由にハンドリングすることが可能です。

tec_skyondemand_17



通信障害が発生したら？

Salesforceはクラウドサービスですのでネットワークを経由して接続を行います。では、APIのリクエスト中にネットワークの瞬断や遅延が発生した場合どうなるでしょう。

当然ですが、リクエストの送信元ではソケットレベルでの異常やタイムアウトなどを検知します。しかし、瞬間的なネットワークの状況に起因して連携処理が停止してしまうようでは、システム管理者はたまったものではありません。

このような場合、いきなり処理を停止するのではなく、数回通信を試みるべきです。

SkyOnDemandではリクエスト時に異常を検知した場合、通信をリトライする回数や間隔、対象とする例外の種類や条件など細やかに設定することができます。

tec_skyondemand_20


しかし、通信障害が発生した場合、送信元ではリクエストがサーバに到達したかどうは判断することができません。例えば、データ追加を行う create() コールをリトライすることで、重複データを作成してしまう可能性があります。

APIマニュアルでは、不要な重複レコードが作成されないようにするために、create() の代わりに upsert() を使用することが推奨されています。

まとめ

これまで3回の連載に渡り、連携ツールの裏側からSalesforceのAPIについて紹介してきました。

最後のエントリでは、書き込み系のAPIコールで考慮すべき内容や制限、対応する連携ツールの機能を知って頂けたと思います。 連携ツールは接続先のAPIを知らなくても簡単に扱うことができるというメリットがありますが、ほんの少しAPIを知るだけでも、さらに効果的な使い方ができるようになるります。 例えば、SkyOnDemandではAPIを標準的に使用する簡易的な設定はもちろんですが、APIの様々な機能に対応した設定を細やかに行うことも可能です。

これまで紹介できたAPIや機能はほんの一部ですが、みなさんが連携ツールを活用するための手助けに少しでもなれば幸いです。