機械翻訳について

6 拡張タスク

REST APIを使用して、リソース・コレクション内のリソース・アイテムの数の取得、カスタム・アクションの実行、およびバッチ・リクエストの実行などの高度な操作を実行できます。

ビジネス・オブジェクト・アイテムの推定数の返却

REST APIは、リソース・コレクション内の推定アイテム数の取得をサポートします。

次の例では、Employeeコレクションの最初の2つのアイテムの合計レコード数を推定し、問合せを行います。 問合せパラメータtotalResultsは、レスポンス・ペイロードにtotalResults属性が含まれることを保証します。

リクエスト

  • URL

    <base_url>/Employee?totalResults=true&limit=2

  • HTTPメソッド

    GET

  • 問合せのパラメータ

    totalResults

    このパラメータにtrueを設定すると、リソース・コレクションのレスポンスに推定アイテム数が含まれます。 それ以外の場合、カウントは含まれません。 デフォルト値はfalseです。

  • Content-Type

    none

  • ペイロード

    none

レスポンス

  • HTTPコード

    200

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • ペイロード

    {
      "items" : [ {
        "EmployeeId" : 101,
        "FirstName" : "Neena",
        "LastName" : "Smith",
        "Email" : "NSMITH",
        "JobId" : "AD_VP",
        "DepartmentId" : 90,
        "Salary" : 2000,
        "links" : [ {
          "rel" : "self",
          "href" : "<base_url>/Employee/NSMITH",
          "name" : "Employee",
          "kind" : "item"
        } ]
      }, {
        "EmployeeId" : 102,
        "FirstName" : "Lex",
        "LastName" : "De Haan",
        "Email" : "LDEHAAN",
        "JobId" : "AD_VP",
        "DepartmentId" : 90,
        "Salary" : 3000,
        "links" : [ {
          "rel" : "self",
          "href" : "<base_url>/Employee/LDEHAAN",
          "name" : "Employee",
          "kind" : "item"
        } ]
      } ],
      "totalResults" : 5,
      "count" : 2,
      "hasMore" : true,
      "limit" : 2,
      "offset" : 0,
      "links" : [ {
        "rel" : "self",
        "href" : "<base_url>/Employee",
        "name" : "Employee",
        "kind" : "collection"
      } ]
    }
    

バッチ・リクエストの作成

REST APIは、バッチ・リクエストを使用して1回のラウンドトリップで複数の操作を実行することをサポートします。 データはリクエストの終了時にコミットされます。 ただし、バッチ・リクエストの1つのリクエスト部分が失敗した場合は、すべての変更がロールバックされ、エラー・レスポンスが返されます。

バッチ・リクエストは、作成、更新、取得、削除、カスタム・メソッドの呼び出し、および記述リクエストの組み合わせで構成できます。 パス・パラメータとペイロードは、リクエストを直接呼び出すために使用するものと同じである必要があります。 getメソッドは、バッチ・リクエスト内の同じURLパラメータを個別のHTTPリクエストとしてサポートします。

次のサンプルは、4つの部分で操作を実行するバッチ処理が成功したことを示しています: 1)従業員101の更新、2)従業員102の更新、3)従業員103の更新、4)従業員104の問合せ。

リクエスト

  • URL

    <base_url>

  • HTTPメソッド

    POST

  • Content-Type

    application/vnd.oracle.adf.batch+json

  • ペイロード

    {
    	"parts": [{
    		"id": "part1",
    		"path": "/Employee/101",
    		"operation": "update",
    		"payload": {
    			"Salary": 10000
    		}
    	}, {
    		"id": "part2",
    		"path": "/Employee/102",
    		"operation": "update",
    		"payload": {
    			"Salary": 10000
    		}
    	}, {
    		"id": "part3",
    		"path": "/Employee/103",
    		"operation": "update",
    		"payload": {
    			"Salary": 10000
    		}
    	}, {
    		"id": "part4",
    		"path": "/Employee?q=EmployeeId%3D101",
    		"operation": "get"
    	}]
    }

レスポンス

  • HTTPコード

    200

  • Content-Type

    application/vnd.oracle.adf.batch+json

  • ペイロード

    {
    	"parts": [{
    		"id": "part1",
    		"path": "<base_url>/Employee/101",
    		"operation": "update",
    		"payload": {
    			"EmployeeId": 101,
    			"FirstName": "Neena",
    			"LastName": "Smith",
    			"Email": "NSMITH",
    			"JobId": "AD_VP",
    			"DepartmentId": 90,
    			"Salary": 10000,
    			"links": [{
    				"rel": "self",
    				"href": "<base_url>/Employee/101",
    				"name": "Employee",
    				"kind": "item"
    			} ]
    		}
    	}, {
    		"id": "part2",
    		"path": "<base_url>/Employee/102",
    		"operation": "update",
    		"payload": {
    			"EmployeeId": 102,
    			"FirstName": "Lex",
    			"LastName": "De Haan",
    			"Email": "LDEHAAN",
    			"JobId": "AD_VP",
    			"DepartmentId": 90,
    			"Salary": 10000,
    			"links": [{
    				"rel": "self",
    				"href": "<base_url>/Employee/102",
    				"name": "Employee",
    				"kind": "item"
    			} ]
    		}
    	}, {
    		"id": "part3",
    		"path": "<base_url>/Employee/103",
    		"operation": "update",
    		"payload": {
    			"EmployeeId": 103,
    			"FirstName": "Alexander",
    			"LastName": "Hunold",
    			"Email": "AHUNOLD",
    			"JobId": "IT_PROG",
    			"DepartmentId": 60,
    			"Salary": 10000,
    			"links": [{
    				"rel": "self",
    				"href": "<base_url>/Employee/103",
    				"name": "Employee",
    				"kind": "item"
    			} ]
    		}
    	}, {
    		"id": "part4",
    		"path": "<base_url>/Employee",
    		"operation": "get",
    		"payload": {
    			"EmployeeId": 101,
    			"FirstName": "Neena",
    			"LastName": "Smith",
    			"Email": "NSMITH",
    			"JobId": "AD_VP",
    			"DepartmentId": 90,
    			"Salary": 10000,
    			"links": [{
    				"rel": "self",
    				"href": "<base_url>/Employee/101",
    				"name": "Employee",
    				"kind": "item"
    			} ]
    		}
    	}]
    }

エラー・レスポンスの処理

エラー・レスポンスは、HTTPステータス・コードとエラー・メッセージの形式でJSONペイロードの形式で取得できます。

HTTPステータス・コードとエラー・メッセージに加えて、REST APIフレームワーク・バージョン4を使用できるようにリクエストが有効化され、application/vnd.oracle.adf.error+jsonまたはapplication/jsonメディア・タイプに対してリクエストが行われると、レスポンスで例外の詳細を取得できます。 フレームワーク・バージョン4を使用すると、レスポンスは例外詳細ペイロードの形式になり、Webアプリケーションに対して次の利点があります:

  • 1つのリクエストで複数のエラーが発生した場合は、各エラーの詳細が階層構造で表示されます。

  • 各エラーに対応する例外を特定する、アプリケーション固有のエラー・コードが存在する場合があります。

  • リクエスト・ペイロード構造内の各エラーのロケーションを特定するエラー・パスが存在する場合があります。

注意:

例外の詳細には、アプリケーション固有のエラー・コードやリクエスト・ペイロードのエラー・パスなど、特定の詳細が示されるかどうかがあります。

たとえば、フレームワーク・バージョン3 (またはそれ以前)が有効で、フレームワーク・バージョン4 (またはそれ以降)が有効な場合や、フレームワーク・バージョンが有効な場合に、発行されたPOSTのエラー・レスポンスと書式設定されていない次の日付フィールドが含まれている場合を比較します。

{    "EmpNum" : 5027,
     "EmpName" : "John",
     "EmpHireDate" : "not a date"
}

標準エラー・レスポンス、バージョン3以下

フレームワーク・バージョンがない4では、レスポンス・ペイロードは生成されず、かわりにリクエスト・ペイロードを参照していない単一のエラー・メッセージのみがレスポンスに返されます。

"An instance of type oracle.jbo.domain.Date cannot be created from string not a date. The string value must be in format YYYY-MM-DDTHH:MI:SS.sss+hh:mm."

例外ペイロード・エラー・レスポンス、バージョン4以降

フレームワーク・バージョン4を有効にすると、次の例外詳細ペイロードがレスポンスに対して生成されます。 ペイロードには通常のHTTPステータス・コードが含まれ、配列構造で1つ以上の例外の詳細が書式設定されます。

{    "title" : "Bad Request",
    "status" : "400",
    "o:errorDetails" : [ {
     "detail" : "An instance of type oracle.jbo.domain.Date cannot be created from string not a date. 
               The string value must be in format YYYY-MM-DDTHH:MI:SS.sss+hh:mm.",
       "o:errorCode" : "26099",
       "o:errorPath" : "/EmpHireDate"
    } ]
 }

例外ペイロード・エラー・レスポンスの理解

次の条件が存在する場合、例外の詳細ペイロードがREST APIエラー・レスポンス用に生成されます:
  • REST APIフレームワークのバージョンは、バージョン4です。

  • application/vnd.oracle.adf.error+jsonまたはapplication/jsonのいずれかがレスポンスのメディア・タイプです。

例外の詳細ペイロードは、次の構造を持つJSONオブジェクトです:

{   "title" : "Message as per HTTP status code",
    "status" : "HTTP error code",
    "o:errorDetails" : [
     ...
        {
            "detail" : "Message of detail error",
            "o:errorCode" : "error code"
            "o:errorPath" : "JSON pointer to the location of the error in the request payload"
        },
        ...
    ]
}

フレームワーク・バージョン4を使用してapplication/vnd.oracle.adf.error+jsonメディア・タイプまたはapplication/jsonメディア・タイプのリクエストを作成することで、例外ペイロードをエラー・レスポンスとしてオプトインします。

例外ペイロード内で、o:errorDetailsは、発生したエラーの数とタイプによって異なることに注意してください。 さらに、エラー・コードとエラー・パスは、レスポンス・ペイロードに存在することが保証されていないため、Webアプリケーションに頼らざるを得ません。

例外ペイロード・エラー・レスポンスの取得

REST APIは、リクエストが適切なメディア・タイプで行われたときに、レスポンス内の例外の詳細を取得することをサポートします。

REST APIフレームワークのバージョン4から、Webアプリケーションは詳細な例外ペイロードを使用してエラー・レスポンスを取得する場合があります。

次のサンプルでは、新しい部門アイテムを持つ部門オブジェクトを作成しようとしています。 ただし、この例では、部門のアイテムがすでに存在するため、リクエストは失敗します。

例外ペイロードでは、o:errorDetails配列は、リクエスト・オブジェクトでエラーが発生した場所のエラー・パスを提供します。ただし、これらの特定の詳細がWebアプリケーションで常に利用可能なわけではありません。

リクエストの例1

  • URL

    <base_url>/Department

  • HTTPメソッド

    POST

  • 受入れヘッダー

    application/vnd.oracle.adf.resourceitem+json,application/json

  • ペイロード

    {
    	"DeptNum" : 50,	
    	"DeptName" : "SALES",
    }

レスポンスの例 1

  • HTTPコード

    400

  • Content-Type

    application/json

  • ペイロード

    {
       "title" : "Bad Request",
       "status" : "400",
       "o:errorDetails" : [ {
          "detail" : "A department with the same name already exists. Please provide a different name.",
          "o:errorCode" : "Dept_Rule_0"
      } ]
    }

次のサンプルでは、新しい部門アイテムを持つ部門オブジェクトを作成しようとしています。 ただし、この例では、入力された従業員名がEmpNameフィールドに定義されている検証ルールで許可されている文字数を超えているため、リクエストは失敗します。

リクエストの例2

  • URL

    <base_url>/Department

  • HTTPメソッド

    POST

  • 受入れヘッダー

    application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json

  • ペイロード

    {
       "DeptNum" : 52,       
       "DeptName" : "newDept522",
       "Employee" : [ {
            "EmpNum" : 501,
            "EmpName" : "MILLERSxxxxxxxxxxxxxxxxx"
        }, {
            "EmpNum" : 502,
            "EmpName" : "JONESPxxxxxxxxxxxxxxxxx"
          } ]
    }

レスポンスの例 2

  • HTTPコード

    400

  • Content-Type

    application/vnd.oracle.adf.error+json

  • ペイロード

    {
       "title" : "Bad Request",
       "status" : "400",
       "o:errorDetails" : [ {
          "detail" : "Value MILLERSxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.",
          "o:errorCode" : "27040",
          "o:errorPath" : "/Employee/0/EmpName"
       }, {
          "detail" : "Value JONESPxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.",
          "o:errorCode" : "27040",
          "o:errorPath" : "/Employee/1/EmpName"
       } ]
    }

次のサンプルは、バッチ操作を実行しようとしています。 ただし、この例では、エラー・レスポンスの例外詳細ペイロードに示されている理由により、バッチ操作が失敗します。

リクエストの例3

  • URL

    <base_url>

  • HTTPメソッド

    POST

  • コンテンツ・タイプ・ヘッダー

    application/vnd.oracle.adf.batch+json

  • ペイロード

    {
        "parts": [
            {
                "id": "part1",
                "path": "/Employee",
                "operation": "create",
    	    "payload" : {
    		"EmpNum" : 1299,
    		"EmpJob" : "CLERK",
    		"EmpMgr" : 7566,
    		"EmpHireDate" : null,
    		"EmpSal" : 245,
    		"EmpComm" : 0,
    		"EmpDeptNum" : 30
    	    }
            },
            {
                "id": "part2",
                "path": "/Employee",
                "operation": "create",
                "payload": {
                    "EmpNum" : 7589,
    		"EmpName" : "SampleEmpxxxxxxxxxxxxxxxxxx",
    		"EmpJob" : "CLERK",
    		"EmpMgr" : 7566,
    		"EmpHireDate" : null,
    		"EmpSal" : 245,
    		"EmpComm" : 0,
    		"EmpDeptNum" : 30
                }
            },
            {
                "id": "part3",
                "path": "/Department",
                "operation": "create",
                "payload": {
                   "DeptNum" : 52,       
                   "DeptName" : "newDept522",
                   "Employee" : [
                       {
                           "EmpNum" : 7588,
                           "EmpName" : "SampleEmpxxxxxxxxxxxxxxxxxx",
                           "EmpJob" : "CLERK",
                           "EmpMgr" : 7566,
                           "EmpHireDate" : null,
                           "EmpSal" : 245,
                           "EmpComm" : 0,
                           "EmpDeptNum" : 30
                       }
                   ]
               }
           },
    	{
                "id": "part4",
                "path": "/Department/10/child/Loc",
                "operation": "get"
            },
    	{
                "id": "part5",
                "path": "/Department?invQP=invVal",
                "operation": "get"
            },
    	{
                "id": "part6",
                "path": "/Department/54",
                "operation": "delete"
            },
    	{
                "id": "part7",
                "path": "/Department/54",
                "operation": "get"
            }
        ]
    }

レスポンスの例 3

  • HTTPコード

    400

  • Content-Type

    application/vnd.oracle.adf.error+json

  • ペイロード

    {
    	"title" : "Bad Request",
    	"status" : "400",
    	"o:errorDetails" : [ {
    		"detail" : "URL request parameter invQP cannot be used in this context.",
    		"o:errorCode" : "27520"
    	}, {
    		"detail" : "Attribute EmpName in Emp is required.",
    		"o:errorCode" : "27014",
    		"o:errorPath" : "/parts/0"
    	}, {
    		"detail" : "Value SampleEmpxxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.",
    		"o:errorCode" : "27040",
    		"o:errorPath" : "/parts/1/payload/EmpName"
    	}, {
    		"detail" : "Attribute EmpName in Emp is required.",
    		"o:errorCode" : "27014",
    		"o:errorPath" : "/parts/1"
    	}, {
    		"detail" : "Value SampleEmpxxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.",
    		"o:errorCode" : "27040",
    		"o:errorPath" : "/parts/2/payload/Employee/0/EmpName"
    	}, {
    		"detail" : "Attribute EmpName in AM.Dept_empWorksIn_deptToEmpQA_EmpViewDef is required.",
    		"o:errorCode" : "27014",
    		"o:errorPath" : "/parts/2"
    	}, {
    		"detail" : "Not Found",
    		"o:errorCode" : "11404",
    		"o:errorPath" : "/parts/3"
    	} ]
    }

標準エラー・メッセージ・レスポンスの取得

REST APIでは、リクエストがREST APIフレームワーク・バージョン1から3対応可能である場合の検証またはシステム・エラーを説明するエラー・メッセージの生成がサポートされています。

REST APIフレームワークのバージョン4の前に、エラー・レスポンスは単一のエラー・メッセージとHTTPステータス・コードを返します。 バージョン4以降では、Webアプリケーションが詳細な例外ペイロードを使用してエラー・レスポンスを取得できます。

次の例では、Departmentsリソースを新しい部門リソース・アイテムで更新しようとしています。 ただし、この例では、部門の品目がすでに存在するため、更新は失敗します。 REST APIフレームワーク・バージョン4 (以上)が有効になっていないため、レスポンスはエラー・メッセージです。

フレームワーク・バージョンを使用したリクエストの例3

  • URL

    http://server/demo/rest/11.2/Departments

  • HTTPメソッド

    POST

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • 受入れヘッダー

    application/vnd.oracle.adf.resourceitem+json,application/json

  • ペイロード

    {
    	"DeptNum" : 50,	
    	"DeptName" : "SALES",
    }

フレームワーク・バージョンからのレスポンスの例3

  • HTTPコード

    400

  • エラー・レスポンス

    A department with the same name already exists. Please provide a different name.