Apex 開発者ガイド
jApex REST のメソッド
Apex REST は、リソースを表現するために、JSON と XML の 2 つの形式をサポートしています。JSON による表現は、要求またはレスポンスボディにデフォルトで渡され、形式は、HTTP ヘッダーの Content-Type プロパティで示されます。本文は、Apex メソッドへのパラメータがない場合、HttpRequest オブジェクトから Blob として取得できます。パラメータが Apex メソッドに定義されている場合、リクエストボディをそれらのパラメータに並列化する試行が行われます。Apex メソッドの戻り値が non-void である場合、リソースの表現はレスポンスボディに逐次化されます。
次の戻り型とパラメータ型を使用できます。
- Apex プリミティブ (sObject と Blob を除く)
- sObjects
- Apex プリミティブまたは sObject のリストまたは対応付け (String キーの対応付けのみをサポート)
- 上記の型のメンバー変数を含むユーザ定義型
@HttpGet または @HttpDelete アノテーションのあるメソッドには、パラメータがありません。これは、GET 要求と DELETE 要求にはリクエストボディがなく、並列化するものがないためです。
1 つの Apex クラスにアノテーション @RestResource が付加されている場合、同一の HTTP 要求メソッドでアノテーションが付加されたメソッドを複数含めることはできません。たとえば、同じクラスにアノテーション @HttpGet が付加されたメソッドを 2 つ含めることはできません。
Apex REST メソッドに関する考慮事項
Apex REST メソッドを定義する場合、次の事項を考慮してください。
-
RestRequest オブジェクトおよび RestResponse オブジェクトは、静的 RestContext オブジェクトによってデフォルトで Apex メソッドで利用できます。この例では、RestContext によってこれらのオブジェクトにアクセスする方法を示します。
- Apex メソッドにパラメータがない場合、Apex REST は HTTP リクエストボディを RestRequest.requestBody プロパティにコピーします。メソッドにパラメータがある場合、Apex REST はデータをそれらのパラメータに並列化しようとします。ただし、データは RestRequest.requestBody プロパティには並列化されません。
- Apex REST は、応答に同様の逐次化ロジックを使用します。Apex メソッドの戻り値の型が non-void である場合、そのメソッドの戻り値は、RestResponse.responseBody に逐次化されます。
- Apex REST メソッドは、管理パッケージと未管理パッケージで使用できます。管理パッケージに含まれる Apex REST メソッドをコールする場合、REST のコール URL に管理パッケージの名前空間を含める必要があります。たとえば、packageNamespace という管理パッケージ名前空間にクラスが含まれており、Apex REST メソッドが /MyMethod/* という URL 対応付けを使用している場合、これらのメソッドをコールするために REST によって使用される URL は、https://instance.salesforce.com/services/apexrest/packageNamespace/MyMethod/ という形式になります。管理パッケージの詳細は、「パッケージとは?」を参照してください。
- 期限切れのパスワードまたは一時的なパスワードを持つユーザのログインコールが API から行われた場合、カスタム Apex REST Web サービスメソッドへの後続の API コールはサポートされず、MUTUAL_AUTHENTICATION_FAILED エラーが発生します。Apex Web サービスメソッドをコールするには、ユーザのパスワードをリセットして、期限が切れていないパスワードでコールを行います。
ユーザ定義型
ユーザ定義型を Apex REST メソッドのパラメータとして使用できます。Apex REST は、ユーザ定義型の public、private、または global クラスメンバー変数に要求データを並列化します。ただし、変数が static または transient として宣言されている場合は、並列化されません。たとえば、ユーザ定義型パラメータを含む Apex REST メソッドは次のように記述されます。
このメソッドの有効な JSON および XML 要求データは、次のように記述されます。
staticString または transientString の値が上記例の要求データに提供されている場合、HTTP 400 状況コード応答が生成されます。public、private、または global クラスメンバー変数は、次の Apex REST が許可する型である必要があります。
- Apex プリミティブ (sObject と Blob を除く)
- sObjects
- Apex プリミティブまたは sObject のリストまたは対応付け (String キーの対応付けのみをサポート)
Apex REST メソッドのパラメータとして使用されるユーザ定義型を作成する場合、実行時に、ユーザ定義型でサイクルとなるクラスメンバー変数の定義 (相互に依存する定義) を挿入しないようにしてください。次に、簡単な例を示します。
要求および応答データの考慮事項
Apex REST メソッドにおける要求データの考慮事項をいくつか示します。
-
Apex パラメータの名前は重要です。ただし、順番は考慮されません。たとえば、XML と JSON の有効な要求は次のようになります。
- URL パターンである URLpattern と URLpattern/* の URL は一致します。あるクラスには URLpattern の urlMapping があり、別のクラスには URLpattern/* の urlMapping がある場合、この URL パターンに対する REST 要求は、最初に保存されたクラスに解決されます。
- 一部のパラメータと戻り値の型は、要求の Content-Type として、または応答の許容形式として XML で使用することはできないため、これらのパラメータまたは戻り値の型を使用したメソッドを XML で使用することはできません。List<List<String>> など、コレクションのリスト、対応付けまたはコレクションはサポートされていません。ただし、これらの型を JSON で使用することはできます。パラメータリストに XML では無効な型が含まれており、その XML が送信されると、HTTP 415 の状況コードが返されます。戻り値の型が XML で無効な型であり、XML が要求された応答形式である場合、HTTP 406 の状況コードが返されます。
- JSON または XML の要求データについては、Boolean パラメータの有効な値は、true、false (これらは大文字と小文字を区別しません)、1 および 0 (文字列「1」または「0」ではなく数値) です。Boolean パラメータにその他の値が渡されると、エラーになります。
- JSON または XML 要求データに同じ名前のパラメータが複数含まれる場合は、HTTP 400 状況コードエラー応答が返されます。たとえば、メソッドが x という入力パラメータを指定した場合、次の JSON 要求データはエラーになります。同様に、ユーザ定義型についても、要求データに同一のユーザ定義型メンバー変数が複数含まれる場合、エラーになります。たとえば、次の Apex REST メソッドとユーザ定義型があるとします。次の JSON 要求データもエラーになります。
- 要求データのパラメータの 1 つに null 値を指定する必要がある場合、すべてのパラメータを省略するか、null 値を指定できます。JSON では、null を値として指定できます。XML では、nil 値と共に http://www.w3.org/2001/XMLSchema-instance 名前空間を使用する必要があります。
- XML 要求データについては、メソッドが使用する Apex 名前空間を参照する XML 名前空間を指定する必要があります。たとえば、Apex REST メソッドを次のように定義するとします。次の XML 要求データを使用できます。
応答の状況コード
応答の状況コードは、自動的に設定されます。この表では、一部の HTTP 状況コードと HTTP 要求メソッドでの意味を説明します。応答状況コードの完全なリストは、「statusCode」を参照してください。
| 要求メソッド | 応答の状況コード | 説明 |
|---|---|---|
| GET | 200 | 要求は成功しました。 |
| PATCH | 200 | 要求は成功しました。戻り値の型は non-void です。 |
| PATCH | 204 | 要求は成功しました。戻り値の型は void です。 |
| DELETE、GET、PATCH、POST、PUT | 400 | 未処理のユーザ例外が発生しました。 |
| DELETE、GET、PATCH、POST、PUT | 403 | 指定された Apex クラスにアクセスできません。 |
| DELETE、GET、PATCH、POST、PUT | 404 | URL は既存の @RestResource アノテーションで対応付けられていません |
| DELETE、GET、PATCH、POST、PUT | 404 | URL 拡張はサポートされていません。 |
| DELETE、GET、PATCH、POST、PUT | 404 | 指定された名前空間を使用する Apex クラスは見つかりませんでした。 |
| DELETE、GET、PATCH、POST、PUT | 405 | 要求メソッドには対応する Apex メソッドがありません。 |
| DELETE、GET、PATCH、POST、PUT | 406 | ヘッダーの Content-Type プロパティは JSON または XML 以外の値に設定されました。 |
| DELETE、GET、PATCH、POST、PUT | 406 | HTTP 要求に指定されたヘッダーはサポートされていません。 |
| GET、PATCH、POST、PUT | 406 | 形式に指定された XML の戻り値の型はサポートされていません。 |
| DELETE、GET、PATCH、POST、PUT | 415 | XML パラメータの型はサポートされていません。 |
| DELETE、GET、PATCH、POST、PUT | 415 | HTTP 要求のヘッダーに指定された Content-Header 型はサポートされていません。 |
| DELETE、GET、PATCH、POST、PUT | 500 | 未処理の Apex 例外が発生しました。 |