拡張タスク

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

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リクエストとしてサポートします。

リクエストURLパスでは、マルチパート・キーを識別するなど、URIパートのエンコーディングを使用しないでください。リクエストでエンコードされたパスを使用すると、例外エラーが発生します。

次のサンプルは、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.

エンドポイント・リクエストのポーリングの有効化

ビジネス・オブジェクトの処理時にタイムアウトの問題が発生した場合、長時間実行エンドポイント・リクエストのポーリングを有効にする場合があります。

ポーリングは、実行時間が長いプロセスに関係する多くのコンテキストで有用であり、ゲートウェイまたはブラウザのタイムアウトが原因でクライアント/サーバー接続を中断するリスクがあります。たとえば、アプリケーションが外部サービスと統合されている場合、外部サービスに対するAPIコールを実行するトリガーを介して、プロセスが長時間実行されることがあります。また、アプリケーションのライフサイクル中に、ファイルから、またはあるデータベース(開発、ステージングまたはライブ)から別のデータベースに大量のデータをインポートするエンドポイント・リクエストを含めることもできます。ビジネス・オブジェクト・データの作成、問合せ、更新および削除など、データ関連エンドポイント・リクエストのほとんどは、ポーリングによるメリットが得られる長時間実行プロセスです。

ポーリングを有効にするには、エンドポイント・リクエストURLにvb-poll=true問合せパラメータを追加します。クライアントによってエンドポイント・リクエストが行われると、リクエストが完了するのを待機せずに、HTTPレスポンス(ステータス200またはそれ以外)を返すのではなく、クライアントがポーリングする新しいURLの詳細を含むHTTPレスポンス(ステータス202)を返します。これにより、サーバーはバックグラウンドでリクエストの処理を続行し、クライアントが新しいURLをポーリングできます。また、リクエストが完了してレスポンス(またはエラー)を取得するかどうかを確認する場合も同様です。

長時間実行エンドポイント・リクエストのポーリングを有効にするには:

vb-poll=true問合せパラメータをエンドポイント・リクエストURLに追加します。たとえば:

POST https://server.example.com/ic/builder/rt/hrapp/1.0/resources/data/Employee?vb-poll=true
ステータス202のHTTPレスポンスを受信する場合、値がポーリングURLになるPolling-Locationヘッダーを探します。

クライアントは、このURLをポーリングしてレスポンスをチェックできます。このレスポンスには、プロセスがまだ実行中であることを示すPolling-Locationヘッダーが含まれているか、最後のレスポンスになります。

長時間実行プロセスが完了すると、レスポンスは制限された期間使用可能のままになり、その後削除されます。プロセス自体は、この影響を受けませんが、デフォルトでは、この期間2分を超えて結果を使用することはできません。クライアントは、ポーリング・リクエストの頻度を決定するときに、この設定を考慮する必要があります。