Salesforce Web API について理解しよう #Salesforce

ゴール

Salesforce で利用されている Web API の概念を理解する

API（Application Programming Interface）

Salesforce には、様々なアプリケーションが存在します。Sales Cloud, Service Cloud, Slack, Tableau, Heroku など様々なアプリケーションは Web API というもので接続されています。例えば、Sales Cloud から商談オブジェクトのレコードが作成されたら API を介して Slack に通知するといったことが可能です。API とは、これらのアプリケーション同士を接続するものになります。

Web API とは何か

Web APIとは、API 提供者とAPI 利用者とのやりとりを HTTP／HTTPS ベースで実現する API になります。通常の API は、API 利用者が用いるプログラミング言語と同じ言語で提供されることが多いです。例えば、API がC言語で実装されていたら、API の利用者もC言語で実装する必要があります。
一方 Web API は HTTP／HTTPS ベースの API であるため、異なるプログラミング言語で開発されたアプリケーション間を連携させることが可能です。さらにウェブブラウザでも利用できるなど、他の API よりも汎用的に利用できます。Web API の代表的な実装方式として、REST と SOAP が存在します。Salesforce で提供されている Web API は、ほとんどが REST で提供されています。

以下の図は、よくあるクライアント／サーバモデルになりますが、クライアント（ウェブブラウザ）からの要求（リクエスト）をサーバで処理する際に Web API がサーバ側のインタフェースとしての役割になります。サーバ側は、Web API で受け取ったリクエストを処理して応答（レスポンス）を返します。上記の REST の場合は JSON 形式で値を返すことが多いです。

どの API を使用するか

インテグレーションのニーズに合わせて適切な Salesforce API を選択して使用します。Salesforce が提供する API の選択内容 (サポートされるプロトコル、データ形式、使用事例など) を確認しましょう。

API 名	プロトコル	データの形式	通信
REST API	REST	JSON、XML	同期
SOAP API	SOAP (WSDL)	XML	同期
Connect REST API	REST	JSON、XML	同期 (写真の処理は非同期)
Apex REST API	REST	JSON、XML、カスタム	同期
Apex SOAP API	SOAP (WSDL)	XML	同期
Analytics REST API	REST	JSON、XML	同期
ユーザインターフェース API	REST	JSON	同期
Tooling API	REST または SOAP (WSDL)	JSON、XML、カスタム	同期
Bulk API 2.0	REST	CSV	非同期
メタデータ API	SOAP (WSDL)	XML	非同期
ストリーミング API	Bayeux	JSON	非同期 (データのストリーム)

それぞれの API についての利用方法は、Trailhead に教材があります。こちらも併せて確認いただけると理解が深まると思います。

参考：Salesforce API を使用したソリューションの設計

RESTとSOAP

SOAP(Simple Object Access Protocol) とは、XML を利用したプロトコルになります（XMLについては後述）。XMLで記述された「SOAPメッセージ」と呼ばれるデータをやりとりすることで、メッセージを交換する手法となります。WSDL（Web Services Description Language）という Web サービスインタフェース記述言語で SOAP メッセージの構造を定義することができ、この WSDL による定義ファイルを API 利用者、API 提供者双方で保持することで、独自に定義した構造の SOAP メッセージをやりとりすることが可能となります。
REST とは Representational State Transfer の略称で、REST の考え方に従って実装された API を RESTful API（または REST API ）と呼びます。SOAP の手法に不満を持っていた Roy Fielding 氏が、2000 年に自身の博士論文で「REST」という代替案を提唱しました。REST は最も一般的な API の1つとなっており、Saleforce や Amazon、Facebook、Twitter、Google など、多くの主要なウェブ系企業で使われています。REST は、SOAP の欠点に対応して作成されたもう 1つの標準プロトコルなので新規で API 開発をする場合は REST を選択する場合が多いです。

REST API を使用するケース

REST API では、Salesforce を操作するための、強力、便利、そしてシンプルな REST ベースの Web サービスインターフェースを提供します。インテグレーションや開発が容易になるという利点があり、モバイルアプリケーションや Web プロジェクトで使用するためのテクノロジの選択としては最適です。特定のプロジェクトでは、REST API を他の Salesforce REST API と一緒に使用できます。リストビュー、アクション、および連動選択リストの UI の構築を含め、レコードの作成、参照、更新、削除用の UI を構築するには、ユーザインターフェース API を使用します。

参考：どの API を使用するか?

XMLとJSON

XML(Extensible Markup Language)は、HTML の記述方法に似ており、タグと呼ばれるものによってデータを囲み、更にデータを入れて入れ子構造にすることができるデータ構造です。一方、JSON(JavaScript Object Notation) は、辞書型と呼ばれ、1 対 1 対応のような記述方式になります。JSON は、名前からもわかるように JavaScript との親和性が高く、XML よりもデータの記述量が少ないので、読み込みが速いという特徴があり、REST API を使った通信では、JSON を用いる場合が多いです。

同期と非同期

Web API を使った通信方式して、同期通信と非同期通信があります。同期通信は、複数の処理を実行する際に、1 つずつ上から順番に実行します。前の処理が終わらないと新しい処理ができないという特徴がありますが、データの整合性がとれるため、通信の信頼性が高いです。同期通信の代表的な API は、REST や SOAP となります。
対して非同期通信は、複数の処理を並列で実行するため、処理速度が同期通信より速くなります。しかし、複雑なロジックが動作するような通信をする際にデッドロックが発生する可能性があるなど使用する場合は気をつける必要があります。複雑なロジックが動作しない場合で、大量のデータを処理する場合には効果的な通信方式であるといえます。代表的な API には、Bulk API があります。

CURLコマンド

CURL コマンドは、様々な通信プロトコルでデータの送受信を行うことができるコマンドです。Web API のエンドポイントへ HTTP/HTTPS リクエストをしてレスポンスを確認でき、API のテストでよく使われています。例えば、取引先レコード（Account）の取得は以下のように入力して cURL を実行します。

curl -X GET https://<Instance>.my.salesforce.com/services/data/v57.0/sobjects/Account/<RecordId> -H "Authorization: Bearer <sid>" | jq

● -X オプション - HTTPメソッドの指定
● GET - GET メソッド（データの取得）
● インスタンス名.my.salesforce.com：インスタンスのホスト名
● /services/data/vXX.X/sobjects/[オブジェクトのAPI名]/[レコードID]：リクエスト先のURL,vXX.Xは、API バージョンを指定
●"Authorization: Bearer "：Bearer（アクセストークン認証）
※アクセストークン認証は、ログインID・パスワードでユーザー認証を行なった後に、Salesforceのサーバから発行されるアクセストークンを受け取って、API のリクエスト時に送信する方式

Web API の開発・テストツール

Salesforce の Web API をテストするツールには、Workbench や Postman があります。Workbnech は、Salesforce にかかわる開発者が集まったオープンソースプロジェクトで開発されているウェブベースの開発・テストツールです。Postman は、Web API の開発・テストツールとしては広く使用されています。どちらのツールも無料で利用することが可能です。Workbench は、Salesforce 開発に特化したツールなのでこちらの方が使いやすいかもしれません。

Workbench

Workbench へのログインは下記の URL から実行できます。これは Salesforce の開発者向けサイト上に構築されています。サイトにアクセスすると [Environment] で本番環境（Production）と Sandbox環境（Snadbox）の選択が可能です。API Version は、最新のバージョンを選択しましょう。[Login with Salesforce] ボタンをクリックすると Salesforce の認証画面に遷移します。認証後は、各種 API を利用することが可能となります。2023 年 4 月現在、「Try the Salesforce APIs for Postman.」と画面に表示されています。Postman も使ってみようということでしょうか。

画面右上の [utilities] をクリックします。次に [REST Explorer] をクリックして、REST API を利用してみましょう。

REST API を利用するには、使用する URI を指定する必要があります。今回は、REST API を使用して SOQL クエリを実行してみます。

/services/data/v57.0/query?q=SELECT+Id+,+Name+FROM+Account

[Execute] ボタンをクリックすると、リクエストが実行され結果が画面に表示されます。コマンド操作に比べて、視覚的にもわかりやすいですね。裏側では、上記の CURL コマンドのようなアクセストークン認証が行われているのを理解しておきましょう。

Postman

Postman で Salesforce の API を叩く場合は、Salesforce APIs for Postman を利用します。

Postman を使用する場合は以下のサイトからご利用ください。

おそらく、以下の Quick Start がわかりやすいです。

参考：Quick Start: Connect Postman to Salesforce (Trailhead)

設定手順を記載しますので、やってみましょう。

Salesforce APIs for Postman - ワークスペースの作成

Postman のアカウントとワークスペースを作成します。Postman はブラウザで動作するアプリケーションになるため、ブラウザ上で操作します。ワークスペースはその名の通り、作業用のディレクトリになります。

Postman のアカウントを作成します。
画面左上の [Workspaces] をクリックします。
[Create Workspace] ボタンをクリックします。
ワークスペースの名前を [SalesforceCollection] とします。
[Visibility]は、[Personal] を選択します。
[Create Workspace] ボタンをクリックします。

Salesforce APIs のフォーク

続いて、公開されている [Salesforce Collection] を Fork します。 Fork とは、他の人のデータを自分のアカウントのワークスペースに複製することです。

Salesforce 開発者のワークスペースから [Salesforce APIs collection] を Fork します。以下のサイトにアクセスしましょう。

[Salesforce Platform APIs] を選択します。左側に表示される fork ボタンをクリックします。

[Fork label] に名前を入力します。「Salesforce APIs」など分かりやすい名前にしましょう。Workspace は上記で作成したものを使います。

fork が完了したら、ワークスペースに戻ります。fork した [Salesforce APIs] をクリックします。

右側の [Authorization] から [Get New Access Token] をクリックします。

Salesforce のアカウント認証画面が表示されます。
アカウント認証（OAuth 2.0）をします。
アクセストークンを設定します。
[Variables] タブで [_endpoint] にエンドポイントの URL を設定します。
設定例：https://<マイドメイン名>.my.salesforce.com

※アクセストークンは、API を使用する際、毎回、取得する必要があります。また、アクセストークンは認証情報なので、流出しないように注意してください。

Salesforce APIs の接続テスト

Postman から Salesforce REST API の接続テストをします。今回は、Trailhead に掲載されている REST API に対して GET リクエストを発行して、各種制限項目を確認してみましょう。

API の一覧から [REST] を選択します。
[GET Limits] を選択します。
[Send] ボタンをクリックします。
Salesforce の各種制限項目が表示されます。
ステータスが 200 であれば、成功です。

ここまでの流れは、Trailhead の「Quick Start: Connect Postman to Salesforce」で紹介されているのでやってみてください。

参考：Quik Start: Connect Postman to Salesforce (Trailhead)

参考：Postman API Client (Trailhead)

まとめ

Salesforce には、様々なアプリケーションが存在します。それらのアプリケーション同士や外部プログラムと接続するために Salesforce API が存在します。Web API の代表的なプロトコルには、SOAP と REST があります。SOAP の弱点を強化したプロトコルが REST になります。REST API では、XMLとJSONというデータ形式を扱うことができます。近年は、XML よりシンプルな JSON が用いられています。Web API を使った通信方式して、同期通信と非同期通信があります。基本的に信頼性が高い同期通信を利用しますが、複雑な処理を伴わない大量のデータ処理をする場合、非同期通信も利用されています。Web API を開発・テストする場合には、CURLコマンドを利用したり、Workbench や Postman などの Web ツールが使われています。

以上、Salesforce Web API について、まとめさせていただきました。

おわり。