SalesforceにおけるRESTのクラス、アノテーションなどを紹介

SalesforceにおけるRESTとは

SalesforceにおけるRESTは、URIにHTTPメソッドでアクセスすることでデータの送受信などを行う設計モデルです。Salesforceでは、RESTとそれに準じるREST APIが提供されています。RESTを使用してSalesforceのApex クラスを、REST Webサービスとして公開することができます。 REST（Representational State Transfer）はロイ・フィールディング氏が提唱した分散システムにおける設計原則ですが、分散システム上で複数のソフトウェアを連携させるのに適しているため、狭義の意味ではWebシステムに適用したソフトウェアの設計モデルをさします。

SalesforceにおけるREST でできること

RESTは、リソース URI、HTTPメソッド、要求ヘッダー、リクエストボディの4つのコンポーネントで構成され、Salesforce組織と連携し、以下の操作を実行できます。 ＜RESTリソースで実行できること＞ ・使用できる APIバージョンの概要情報を取得する。 ・Salesforceオブジェクトやカスタムオブジェクトの詳細情報を取得する。 ・クエリおよび検索を実行する。 ・レコードを更新および削除を実行する。 RESTリソースは、データレコード、レコードのコレクション、クエリなどの情報やアクションをモデル化されています。 Salesforce組織との連携に使用するREST APIのリソースは、リソースURIの名前で識別され、HEAD、GET、POST、PATCH、DELETEの標準 HTTPメソッドを用いてアクセスします。REST APIは、リソースとURI、両者の間のリンク状況に基づいて機能します。

Salesforce Apex RESTで使えるクラスとメソッド

Apexを利用することで、Salesforceのさまざまな機能にプログラム経由でアクセスして、REST Webサービスと統合できます。 Apexコードはアトミックトランザクションで実行され、多くの方法で活用できます。テキスト文字列を使用した一般的なユーティリティに加えて、JSON、XML、データセキュリティ、符号化用のユーティリティが用意されています。

Apex REST で使用できるRestContext クラス

Apex RESTで使用できるRestContext クラスを紹介します。RestContext クラスには、Apex RESTメソッドのRestRequestオブジェクトおよびRestResponseオブジェクトが含まれています。

RestRequest オブジェクト

RestRequestオブジェクトは、System.RestRequestクラスを使用して、RESTful Apexメソッドで要求データにアクセスし、データを返します。 署名：public RestRequest request {get; set;} プロパティ値： System.RestRequest

RestResponse オブジェクト

RestResponse オブジェクトは、HTTP応答にデータを渡す際に使用される RestRequestを返します。 署名：public RestResponse response {get; set;} プロパティ値: System.RestResponse

Salesforce Apex REST のメソッド

Apex REST は、JSONとXMLをサポートしています。JSONでは要求もしくはレスポンスボディにデフォルトで渡され、形式としてはHTTPヘッダーの Content-Typeプロパティで示されます。パラメータの状況により、以下のように対応します。 ・Apexメソッドへのパラメータがない場合 →　HttpRequest オブジェクトから Blob として取得できる。 ・パラメータがApexメソッドに定義されている場合 →　パラメータにリクエストボディを並列化するを試みる。 ・Apexメソッドの戻り値がnon-voidである場合 →　リソースをレスポンスボディに逐次化する。

Salesforce Apex REST でサポートされないもの

Apex RESTでは、以下についてはサポートされていません。 ・Connect in Apexオブジェクトの XML 逐次化および並列化 ・Connect in Apexオブジェクトの JSON 逐次化および並列化 ・XMLにおける対応づけ、リストなどの一部のコレクション型

Salesforce Apex REST アノテーションの種類

ここでは、Apex REST アノテーションを紹介します。 Apex RESTアノテーションを使用して、Apexクラスとメソッドを公開することができます。例えば、Apex クラスの公開は、RestResourceアノテーションを定義することで実行できます。その他のアノテーションについても、メソッドに追加してREST を通じて公開できます。

ReadOnly アノテーション

@ReadOnly ReadOnly アノテーションは、要求に対して返される行数の上限を 100,000 に増加します。その他の制限には変更なく、すべて適用されます。これによりLightningプラットフォームデータベースの制限が緩和され、100,000レコードまでのクエリを実行できます。 REST、SOAP Webサービス、Schedulableインターフェースで使用できます。但し、最上位レベルの要求が、スケジュール実行もしくは Web サービスの呼び出しに含まれることが前提です。 すべての HTTP 要求の Apex RESTアノテーションがサポートされます。但し、要求内の DML 操作、System.scheduleへのコール、キューに追加された非同期 Apex ジョブ操作はブロックされます。

RestResource アノテーション

@RestResource(urlMapping=’/yourUrl’) RestResource アノテーションは、ApexクラスをRESTリソースとして公開します。クラスレベルで使用します。ApexクラスにRestResourceアノテーションが付加されている場合、同じクラスに同一のアノテーションを2 つ以上含めることはできません。

RestResouseアノテーション使用時の留意点

RestResouseアノテーションを使用する際の留意点を説明します。 ・URL 対応づけは以下と相対的でなければならない。 https://instance.salesforce.com/services/apexrest/ ・ワイルドカード文字 (*) を使用できる。 ・大文字と小文字は区別され、常に完全一致が優先される。 ・使用する際は、Apexクラスがグローバル定義されている必要がある。 ・URL のパスは ‘/’ で開始する。 ・URL に’*’を含む場合は、必ず前後に’/’をつける。（末尾の場合は不要） ・完全一致がない場合はワイルドカードを使用して検索し、文字列が最も長いものが選択される。 ・一致するものがない場合は、HTTP応答状況コード 404 が返される。 ・名前空間にあるクラスは名前空間を含むURLに変更される。 ・URL が競合する場合、名前空間にあるクラスが常に使用される。

メソッドレベルで使用するアノテーション

メソッドレベルで使用する4つのアノテーションを紹介します。これらのアノテーションは、Apexメソッドがグローバルで静的に定義されている場合に使用できます。 ・HttpDelete アノテーション　@HttpDelete HTTP DELETE 要求に対して、指定されたリソースを削除します。 ・HttpGet アノテーション　@HttpGet HTTP GET 要求に対して、指定されたリソースを返します。HTTP要求にHEAD 要求メソッドを使用すると、このアノテーションを付加したメソッドも同時にコールされるため、注意が必要です。 ・HttpPost アノテーション　@HttpPost HTTP POST 要求に対して、新しいリソースを作成します。 ・HttpPut アノテーション　@HttpPut HTTP PUT 要求に対して、指定されたリソースを作成もしくは更新します。

Salesforce RESTを活用してクラス、メソッドを公開

今回は、SaelesforoceにおけるRESTについて説明しました。 RESTにより、Salesforce 組織との連携を実現できます。REST API を活用してインテレグレーションを考える際には、RESTのリソースとメソッドについて理解しておくことが必要です。 まずは、SaelesforoceのRESTに関する理解を深めましょう。]]>