Oracle Fusion Cloud Applications共通機能のためのREST API

RESTフレームワーク・バージョンの設定

Fusion Applications REST APIは、REST APIフレームワークを内部的に利用して開発エクスペリエンスを容易にします。このフレームワークは、ADFビジネス・コンポーネントに基づくRESTリソースとの対話をサポートします。このフレームワークを使用するすべてのREST APIは、カスタムHTTPヘッダーREST-Framework-Versionをサポートしています。これにより、RESTクライアントはREST APIの動作を制御できます。

RESTフレームワーク・バージョンの選択

アプリケーション開発では、9つのRESTフレームワーク・バージョン(1から9)のいずれか1つのバージョンを選択できます。クライアント用に選択するバージョンは、ビジネス・ニーズによって異なります。

デフォルト・フレームワーク・バージョン

Fusion Applications REST APIでは、デフォルトでフレームワーク・バージョン1が使用されます。ビジネス・ニーズにあわせて適切な場合は、すべてが揃っています。そうでない場合は、クライアントで別のフレームワーク・バージョンを指定できます。 Oracleでは、最新の機能を利用するために最新のフレームワーク・バージョンを使用することをお薦めします。 APIのフレームワーク・バージョン情報は、リソース・エンドポイントの<context root>に対するGETリクエストのレスポンス本文で、defaultFrameworkVersionおよびallowedFrameworkVersionsプロパティにあります。たとえば、

{
    "items" : [
        {
            "version" : "11.13.18.05",
            "isLatest" : true,
            "adf:extension" : {
                    "defaultFrameworkVersion" : "3",
                    "allowedFrameworkVersions" : [ "1", "2", "3", "4" ]            
            },
		}
	]
}

ノート:

各フレームワーク・バージョンで導入された変更は、下位互換性がありません。したがって、ビジネス要件を評価し、それらをサポートするフレームワーク・バージョンを使用します。

クライアント・リクエストのRESTフレームワーク・バージョンを設定するには:

サポートされている9つのフレームワーク・バージョンのいずれかを選択します:

フレームワーク	説明
バージョン1	クライアント・リクエストの処理に使用されるベース・フレームワーク・バージョン。
バージョン2	クライアント・リクエストの拡張問合せ式の構文をサポートします。バージョン2は、`q`問合せパラメータを異なる方法で解釈します。
バージョン3	アイテムの配列ではなく、リソース・コレクション(JSONオブジェクト)としてのクライアント・リクエストのネストされた子リソースの取得をサポートします。 `expand`および`fields`問合せパラメータを使用して親リソースに対してGETメソッドを使用し、親と一緒にネストされた子アイテムを返します。レスポンス・ペイロードの子には、`hasMore`フィールドなどの追加のページング情報が含まれるようになりました。これを使用して、後続のリクエストで追加の子アイテムを取得できるかどうかを判断できます。
バージョン4	バージョン4より前のレスポンス・ペイロードには、RESTリクエストが失敗した場合のみ、エラー・メッセージが文字列として含まれます。バージョン4以上では、エラー・レスポンス・ペイロードには、アプリケーション固有のエラー・コード、エラーが発生した箇所をピン・ポイントするエラー・パス、他のエラーが原因である場合は詳細などのより詳細な情報が含まれます。
バージョン5	このバージョンでは、次の2つの変更が導入されています: 文字列以外の値を返すカスタム・メソッドの場合、レスポンス・ペイロードには、文字列として表示するのではなく、実際のデータ型の値が表示されます。フィールドが依存する値リスト(LOV)フィールドの場合、そのLOVリソースURLがサブリソースからルート・リソースに変更される場合があります。 LOVは、フィールドの有効な値のリストを提供します。たとえば、`businessPlans`リソースには`PeriodTypeCode`フィールドがあり、その有効な値は別の`/salesGLPeriodTypes`リソースから取得されます。依存LOVは、別のフィールドの値に基づいて有効な値を提供します。たとえば、`PeriodStartDisplayName`フィールドの有効な値は、`PeriodTypeCode`の値によって異なります。バージョン5より前のすべての依存LOVリソースは、`/salesGLPeriodTypes/{PeriodTypeCode}/child/salesGLStartPeriodTimes`などのサブリソースです。バージョン5では、一部の依存LOVリソースが`/salesGLStartPeriodTimesLOV`などのルート・リソースになります。ただし、クライアントは、ファインダ問合せパラメータ`?finder=StartPeriodFinder;bindPeriodType={PeriodTypeCode}`の使用など、依存するフィールド値に基づいて依存するLOVリソースをフィルタできます。
バージョン6	新しいフィールド`@context`が導入され、レスポンス・ペイロード内にすべてのアイテム・コンテキスト情報が配置されます。この新しい`@context`フィールドは、通常のフィールドの兄弟です。これはJSONオブジェクト・タイプで、キー、ヘッダー、リンクおよび警告(ある場合)が含まれます。ノート: リンクは以前のバージョンでも使用できますが、バージョン6では`@context`セクションに移動されます。
バージョン7	行レベルのLOVを非表示にします。ルート・レベルのLOVリソース・リンクのみがリソース・メタデータおよびリソース・データに表示されます。行レベルのLOVリソースは、`/invoices/180428/lov/BusinessUnitVVO1`などの`lov`を含むURLを持つサブリソースです。この例では、`invoices`リソースに`BusinessUnit`フィールドがあります。有効な`BusinessUnit`値は、別のリソースから取得されます。この行レベルの`BusinessUnitVVO1` LOVリソースは常に、請求書`180428`などの既存の請求書リソースのサブリソースです。したがって、新しい請求書の作成時に行レベルのLOVは値を選択する際には役立ちません。かわりに、クライアントはルート・レベルのLOVリソースを使用して、作成操作と更新操作の両方をカバーする必要があります。
バージョン8	このバージョンでは、次の変更が導入されています: タイプClobDomainのデータを、base64でエンコードされた値ではなくプレーン文字列として格納および取得するためのサポート。複数選択固定選択リスト(FCL)フィールドに送信されるリクエストの場合、レスポンスで返される値は、カンマ区切りの値リストではなく配列に表示されます。属性がリソースURLで識別子属性として使用され、属性値に特殊文字が含まれている場合、リソースURLが正しく構築されるように属性値がエンコードされます。
バージョン9	このバージョンでは、次の変更が導入されています: レスポンス本文では、高精度の数値がJSON ' `string` 'データ型として扱われ、フィールド長の制約のためにRESTクライアントが値を誤って解釈したり、端数処理するのを防ぐことができます。有効化されていないアクセサで問合せパラメータを指定してGETリクエストを送信すると、404エラーが表示されます。 LIKE演算子を`q`問合せパラメータとともに使用する場合は、バックスラッシュの`(\)`エスケープ文字を使用してワイルドカード文字を表すことができます。

クライアント・リクエストのREST-Framework-VersionカスタムHTTPヘッダーを使用して、フレームワークのバージョンを指定します。たとえば、フレームワーク・バージョン3を使用する場合は、リクエストにヘッダー-H 'REST-Framework-Version:3'を含めます。

フレームワークのバージョンの詳細は、次を参照してください:

ノート:

RESTフレームワークのバージョンは、SCIMおよびBPMリソースには適用できません。

例

次に、リクエストの処理用に選択されたフレームワーク・バージョンに応じて、REST APIの動作がどのように変化するかの例を示します。

例: RESTフレームワーク・バージョン1および2

RESTフレームワーク・バージョン1では、問合せパラメータは例による問合せ構文に制限されており、演算子は制限されており、子に基づくフィルタはありません。次に例を示します: q=deptno>=10 and <= 30;loc!=NY. RESTフレームワーク・バージョン2以降では、拡張問合せ構文がサポートされています: より多くの演算子、子リソース・フィールドに基づくフィルタリングおよびUPPER関数。たとえば、q=Deptno > 5 and (Emps.Job = 'MANAGER' or Emps.DirectReports.Sal >= 2000)です。

フレームワーク・バージョン2に基づいてこの例を見てみましょう。リクエストでは、複数の式を含むフィルタを使用して、accountsリソースから特定のレコードを取得します。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:2' https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/accounts?q=OwnerName like 'Toddar%' and PartyNumber='CDRM_448' and PartyId='100100001740800'

レスポンス本文の例

{
  "items": [
    {
      "PartyId": 100100001740800,
      "PartyNumber": "CDRM_448",
      "SourceSystem": "RNOW",
      "SourceSystemReferenceValue": "291",
      "OrganizationProfileId": 100100001740800,
      "OrganizationName": "146201273770710561",
      "UniqueNameSuffix": "(San Mateo, US)",
      "PartyUniqueName": "146201273770710561 (San Mateo, US)",
      "Type": "ZCA_CUSTOMER",
      "SalesProfileNumber": "TEMPORARY2293488",
      "OwnerPartyId": 100010037920358,
      "OwnerPartyNumber": "100010037920358",
      "OwnerEmailAddress": "sendmail-test-discard@oraclecloud.com",
      "OwnerName": "ToddAR BeelerAR",
      "PrimaryContactPartyId": null,
      "PrimaryContactPartyNumber": null,
      "PrimaryContactSourceSystem": null,
      "PrimaryContactSourceSystemReferenceValue": null,
      "PrimaryContactName": null,
      "PrimaryContactEmail": null,
      "PrimaryContactPhone": null,
	...	
	  }
	 ]
}

例: RESTフレームワーク・バージョン3

この例では、ネストされた子コレクション・リソースが親に沿って取得され、配列ではなくJSONオブジェクトとして表されていることがわかります。 InvoiceIdフィールドを使用すると、invoiceLines子リソースをリソース・コレクションとして取得できます。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:3' https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices?fields=InvoiceId;invoiceLines:Description,ShipToLocation,Requester&onlyData=true

レスポンス本文の例

{
    "items": [        
        {
            "InvoiceId": 353933,
            "invoiceLines": {
                "items": [
                    {
                        "Description": "Foreign currency Standard unmatched Invoice with lines, distributions and installments",
                        "ShipToLocation": M1-_SEATTLE_MFG_0_2450399171831,
                        "Requester": Adams,Joshua
                    }
                ],
                "count": 1,
                "hasMore": false,
                "limit": 25,
                "offset": 0,
                "links": [
                    {
                        "rel": "self",
                        "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices/353933/child/invoiceLines",
                        "name": "invoiceLines",
                        "kind": "collection"
                    }
                ]
            }
        },
        {
            "InvoiceId": 300100169282057,
            "invoiceLines": {
                "items": [
                    . . .
                ],
                "count": 3,
                "hasMore": false,
                "limit": 25,
                "offset": 0,
                "links": [
                    . . .
                ]
            }
        },
        . . .
    ],
    "count": 25,
    "hasMore": true,
    "limit": 25,
    "offset": 0,
    "links": [
        {
            "rel": "self",
            "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.5/invoices",
            "name": "invoices",
            "kind": "collection"
        },
        . . .
    ]
}

例: RESTフレームワーク・バージョン4

この例の請求書作成リクエストでは、InvoiceNumberフィールドによって検証エラーが発生します。レスポンス・ペイロードには、例外の詳細がJSONオブジェクトとして含まれます。

cURLコマンド

curl --user <username:password> -X POST -H 'REST-Framework-Version:4' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices

リクエスト本文の例

{
    "InvoiceNumber": "REST Unmatched Invoice",
    "InvoiceCurrency": "USD",
    "InvoiceAmount": 2212.75,
    "InvoiceDate": "2018-10-01",
    "BusinessUnit": "Vision Operations",
    "Supplier": "Advanced Network Devices",
    "SupplierSite": "FRESNO",
    "Requester": "Johnson,Mary",
    "InvoiceGroup": "01Oct2018-Group",
    "Description": "Office Supplies"
}

レスポンス本文の例

{
    "title": "Bad Request",
    "status": "400",
    "o:errorDetails": [
        {
            "detail": "This invoice number already exists. Provide a unique invoice number. (AP-810776)",
            "o:errorCode": "AP:::AP_RS_INV_NUM_DUPLICATE_VALUE",
            "o:errorPath": "/InvoiceNumber"
        }
    ]
}

例: RESTフレームワーク・バージョン5

このフレームワークが使用中の場合、依存値リスト(LOV)リソースは、ネストされたサブリソースではなくルート・レベルのリソースになる可能性があります。

違いを理解するには、businessPlansリソースに送信されるこのリクエストを確認します。このリソースには、PeriodTypeCodeフィールドに応じて有効な値を持つPeriodStartDisplayNameフィールドがあります。このリクエストではフレームワーク・バージョン4を使用します。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:4' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/businessPlans/describe

レスポンス本文の例

{

        "name" : "PeriodStartDisplayName", 
        "type" : "string", 
        ...... 
        "lov" : { 
          "childRef" : "SalesGLStartPeriodPickerTimeListViewAccessor", 
          "attributeMap" : [ { 
            "source" : "PeriodName", 
            "target" : "PeriodStartDisplayName" 
          }, { 
            "source" : "Periodtype", 
            "target" : "PeriodTypeCode", 
            "derived" : true 
          } ], 
          "displayAttributes" : [ "PeriodName" ], 
          "lovResourcePath" : [ { 
            "resource" : "salesGLPeriodTypes" 
          }, { 
            "resource" : "salesGLStartPeriodTimes" 
          } ] 
        }, 
        ...... 
        { 
            "rel" : "lov", 
            "href" : "https:// servername.fa.us2.oraclecloud.com /crmRestApi/resources/11.13.18.05/salesGLPeriodTypes", 
            "name" : "salesGLPeriodTypes", 
            "kind" : "collection" 
          } 
}

レスポンスは、PeriodStartDisplayNameがLOV属性であり、その有効な値はネストされた子LOVリソースsalesGLStartPeriodTimesから取得され、その親はsalesGLPeriodTypesであることを示しています。次のURLを使用して、PeriodStartDisplayNameの有効な値を取得できます : https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/salesGLPeriodTypes/{PeriodTypeCode}/child/salesGLStartPeriodTimes。PeriodTypeCodeトークンが、選択したPeriodTypeCode値に置き換えられます。

ただし、フレームワーク・バージョン5では、salesGLPeriodTypes LOVリソースはサブリソースではなくなりました。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:5' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/businessPlans/describe

レスポンス本文の例

{
        "name" : "PeriodStartDisplayName",
        "type" : "string",
        ......
        "lov" : {
          "childRef" : "SalesGLStartPeriodPickerTimeListViewAccessor",
          "childRefForCreate" : "SalesGLStartPeriodPickerTimeListViewAccessorForCreate",
          "attributeMap" : [ {
            "source" : "PeriodName",
            "target" : "PeriodStartDisplayName"
          }, {
            "source" : "Periodtype",
            "target" : "PeriodTypeCode",
            "derived" : true
          } ],
          "displayAttributes" : [ "PeriodName" ]
        },
        ......
        {
          "rel" : "lov",
          "href" : "https:// servername.fa.us2.oraclecloud.com /crmRestApi/resources/11.13.18.05/salesGLStartPeriodTimesLOV?finder=StartPeriodFinder%3BbindPeriodType%3D{PeriodTypeCode}",
          "name" : "SalesGLStartPeriodPickerTimeListViewAccessorForCreate",
          "kind" : "collection"
        }
}

かわりに、属性のlov記述内で、childRefForCreateプロパティはLOVリソースを識別します。そのLOVのhrefにルート・レベルのリソースURLが含まれていることがわかります:

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/salesGLStartPeriodTimesLOV?finder=StartPeriodFinder;bindPeriodType={PeriodTypeCode}

有効なPeriodStartDisplayName値を取得するには、指定されたURLでGETリクエストを使用し、PeriodTypeCodeトークンを選択したPeriodTypeCode値に置き換える必要があります。

ノート:

リソースにカスタム・カスケード固定選択リスト(FCL)を定義し、子FCL URLをリクエストした場合、レスポンスに余分なフィルタが表示されることがあります。これは、古いリリースでFCLが作成され、フレームワーク・バージョン5を使用している場合に観測されます。ただし、機能には影響はなく、フィルタを無視することもできます。

例: RESTフレームワーク・バージョン6

この例では、リンクやヘッダーなどのアイテム・コンテキスト情報が、新しく作成された@context要素内にどのように配置されるかを確認します。フレームワーク・バージョン5まで、リンクはリソース・フィールドと同じレベルに配置されました。

以前にセルフ・リンクのプロパティ要素の下に配置された変更インジケータが、ヘッダーの下の新しい要素Etagに移動されました。 ETagヘッダー値は、各アイテム・リソースの@contextセクションで使用できます。

@contextセクションには、RESTリクエストが失敗しないが、クライアントがさらにアクションを実行する価値があるという警告が含まれる場合もあります。

最初の例は、フレームワーク・バージョン5が使用されているときにlinksが表示される場所を示しています。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:5' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices

レスポンス本文の例

{
  "items": [
    {
      "InvoiceId": 180511,
      "InvoiceNumber": "IBY_Group2_I2470",
      "InvoiceCurrency": "SGD",
      "PaymentCurrency": "SGD",
      "InvoiceAmount": 63750,
      "InvoiceDate": "2013-08-16",
      "BusinessUnit": "Vision Operations",
      "Supplier": "IBY_Supplier2",
      "SupplierNumber": "1357714951",
      ...
  "links": [
        {
          "rel": "self",
          "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices/180511",
          "name": "invoices",
          "kind": "item",
          "properties": {
            "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000478"
          } 
		 }
	  ]
    }  
    ]
  }

フレームワーク・バージョン6を使用して同じリクエストが送信されると、新しく導入された@contextセクション内に表示されるlinksがレスポンスに表示されます。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:6' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices

レスポンス本文の例

{
  "items": [
    {
      "InvoiceId": 180511,
      "InvoiceNumber": "IBY_Group2_I2470",
      "InvoiceCurrency": "SGD",
      "PaymentCurrency": "SGD",
      "InvoiceAmount": 63750,
      "InvoiceDate": "2013-08-16",
      "BusinessUnit": "Vision Operations",
      "Supplier": "IBY_Supplier2",
      "SupplierNumber": "1357714951",
      ...
  "LastUpdateLogin": "E4127E5109082CC8E0435360F00AF4AD",
      "@context": {
        "key": "180511",
        "headers": {
          "ETag": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000478"
        },
        "links": [
          {
            "rel": "self",
            "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices/180511",
            "name": "invoices",
            "kind": "item"},
            ...
         } ]
      }
    ]
  }

例: RESTフレームワーク・バージョン7

フレームワーク・バージョン7以降では、リソース・メタデータもリソース・データも行レベルLOVを含んでいません。次の例は、フレームワークのバージョンが変更されたときにレスポンスがどのように変化するかを示しています。

最初のレスポンスは、行レベルのLOVを表示するフレームワーク・バージョン6からのものです。 2番目のレスポンスはフレームワーク・バージョン7で、行レベルのLOVは表示されなくなります。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:6' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/describe

レスポンス本文の例(以前のフレームワーク・バージョン)

{ 
        "name" : "BudgetedFlag", 
        "type" : "boolean", 
        ...... 
        "lov" : { 
          "childRef" : "YesNoLOV", 
          "childRefForCreate" : "YesNoLOVForCreate", 
          "attributeMap" : [ { 
            "source" : "LookupCode", 
            "target" : "BudgetedFlag" 
          } ], 
          "displayAttributes" : [ "Meaning" ] 
        } 
        ... 
        { 
      "item" : {
        "links" : [ {
          "rel" : "lov", 
          "href" : "https:// servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/{id}/lov/YesNoLOV", 
          "name" : "YesNoLOV", 
          "kind" : "collection" 
        }, { 
          "rel" : "lov", 
          "href" : "https:// servername.fa.us2.oraclecloud.com /crmRestApi/resources/11.13.18.05/fndStaticLookups?finder=LookupTypeFinder%3BBindLookupType%3DYES_NO", 
          "name" : "YesNoLOVForCreate", 
          "kind" : "collection" 
        }
		
	}

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/describe

レスポンス本文の例(バージョン7)

{ 
        "name" : "BudgetedFlag", 
        "type" : "boolean", 
        ...... 
        "lov" : { 
          "childRef" : "YesNoLOV", 
          "attributeMap" : [ { 
            "source" : "LookupCode", 
            "target" : "BudgetedFlag" 
          } ], 
          "displayAttributes" : [ "Meaning" ] 
        }, 
        ... 
        { 
          "rel" : "lov", 
          "href" : "https:// servername.fa.us2.oraclecloud.com /crmRestApi/resources/11.13.18.05/fndStaticLookups?finder=LookupTypeFinder%3BBindLookupType%3DYES_NO", 
          "name" : "YesNoLOV", 
          "kind" : "collection" 
        }
		
}

次の行レベルのLOVがレスポンス本文に表示されないことを確認します。

{ 
          "rel" : "lov", 
          "href" : "https:// servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/{id}/lov/YesNoLOV", 
          "name" : "YesNoLOV", 
          "kind" : "collection" 
        }

同様に、リソース・データに対するリクエストに対するレスポンスには、行レベルのLOVリンクは含まれません。次の例で確認できます。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:6' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/CDRM_113480/

レスポンス本文の例(以前のフレームワーク・バージョン)

{
...
 "Name": "TestOpportunity",
  "OptyId": 300100200556345,
  "OptyNumber": "CDRM_113480",
  "OwnerResourcePartyId": 100010025532672,
  "PrimaryCompetitorId": 100000012079032,
  ...
  "@context": {
    "key": "CDRM_113480",
    "headers": {
      "ETag": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000002770400000002737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B0200007870000000067372001B6F7261636C652E6A626F2E646F6D61696E2E4E756C6C56616C75655899C1C58DAABEEB02000149000A6D53514C54797065496478700000000C78"
    },
    "links": [
	 ....
     {
        "rel": "lov",
        "href": "https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/CDRM_113480/lov/RatedCurrenciesVO",
        "name": "RatedCurrenciesVO",
        "kind": "collection"
      },
	  }
    ]
  }

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/CDRM_113480/

レスポンス本文の例(バージョン7)

レスポンス本文にRatedCurrenciesVO LOVへの参照が含まれていません。

{
    ...
 "@context": {
    "key": "CDRM_113480",
    "headers": {
      "ETag": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000002770400000002737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B0200007870000000067372001B6F7261636C652E6A626F2E646F6D61696E2E4E756C6C56616C75655899C1C58DAABEEB02000149000A6D53514C54797065496478700000000C78"
    },
    "links": [
      {
        "rel": "self",
        "href": "https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/CDRM_113480",
        "name": "opportunities",
        "kind": "item"
      },

例: RESTフレームワーク・バージョン8

このフレームワーク・バージョンでは3つの変更が導入されるため、各変更は箇条書きとして表示され、それぞれに独自の例と説明のセットが含まれています。

ClobDomainデータ型のサポート

フレームワーク・バージョン7以前では、ClobDomainタイプのデータを含むリクエストを送信する場合は、base64エンコード形式で表示する必要があります。それ以外の場合、リクエストは失敗します。フレームワーク・バージョン8以降では、リクエスト本文でClobDomainデータ型の値にプレーン・テキストを使用し、レスポンスがプレーン・テキストでデータを返すことを期待できます。この例では、どのように動作するかを確認します。

productsリソースの場合、説明テキストのデータ型がClobDomainであるとします。フレームワーク7を使用すると、プレーン・テキスト("Description" : "Marker description")でClobDomainデータ型の値を指定して作成リクエストを送信すると、レスポンスは失敗します。

cURLコマンド

curl --user <username:password> -X POST -d '{"ProductId":201, "ProductCode":"MARKER", "Name": "Marker", "ProductType": 1, "Description": "Marker description"}' -H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products

レスポンス本文の例(以前のフレームワーク・バージョン)

{
  "title" : "Bad Request",
  "status" : "400",
  "o:errorDetails" : [ {
    "detail" : "Unable to parse the provided payload",
    "o:errorCode" : "27521"
  }

ただし、base64形式("Description" : "TWFya2VyIGRlc2NyaXB0aW9u")でエンコードされた値を使用してリクエストを送信すると、レコードが作成されます。

cURLコマンド

curl --user <username:password> -X POST -d '{"ProductId":201, "ProductCode":"MARKER", "Name": "Marker", "ProductType": 1, "Description": "TWFya2VyIGRlc2NyaXB0aW9u"}' -H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products

レスポンス本文の例(以前のフレームワーク・バージョン)

{
  "ProductId" : 201,
  "ProductCode" : "MARKER",
  "Name" : "Marker",
  "Description" : "TWFya2VyIGRlc2NyaXB0aW9u",
  "ProductType" : "1",
  "@context" : {
    "key" : "201",
    "links" : [ {
      "rel" : "self",
      "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/201",
      "name" : "products",
      "kind" : "item"
    }, {
      "rel" : "canonical",
      "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/201",
      "name" : "products",
      "kind" : "item"
    } ]
  }
}

フレームワーク・バージョン8を使用している場合は、値をエンコーディングするかわりにプレーン・テキスト("Description" : "Marker description")でリクエストを送信できます。レコードが正常に作成されると、レスポンスがプレーン・テキストで値を返すことがわかります。

cURLコマンド

curl --user <username:password> -X POST -d '{"ProductId":201, "ProductCode":"MARKER", "Name": "Marker", "ProductType": 1, "Description": "Marker description"}' -H 'REST-Framework-Version:8' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products

レスポンス本文の例(バージョン8)

{
  "ProductId" : 201,
  "ProductCode" : "MARKER",
  "Name" : "Marker",
  "Description" : "Marker description",
  "ProductType" : "1",
  "@context" : {
    "key" : "201",
    "links" : [ {
      "rel" : "self",
      "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/201",
      "name" : "products",
      "kind" : "item"
    }, {
      "rel" : "canonical",
      "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/201",
      "name" : "products",
      "kind" : "item"
    } ]
  }
}

複数選択リストが配列に表示される

フレームワーク・バージョン8以降では、リクエストに複数選択値リストが含まれている場合は、カンマ区切り値ではなく配列で表示する必要があります。それ以外の場合、リクエストは失敗します。

この例では、productsリソースのレコードを作成し、値1と2のリストを配列("ProductType": ["1", "2"])に示したリクエストを確認します。フレームワーク・バージョン7以前では、カンマ区切り値書式でのみ表示される値のリストの作成がサポートされています。したがって、配列として値を作成するリクエストは、フレームワークが値を配列として解析できないため失敗します。

cURLコマンド

curl --user <username:password> -X POST -d '{"ProductId":302, "ProductCode":"MARKER", "Name": "Marker", "ProductType": ["1", "2"]}'-H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products

レスポンス本文の例(以前のフレームワーク・バージョン)

{
  "title" : "Bad Request",
  "status" : "400",
  "o:errorDetails" : [ {
    "detail" : "Unable to parse the provided payload value for ProductType: Array value not expected.",
    "o:errorCode" : "27535"
  }

カンマ区切り値形式("ProductType": "1,2")で表示された値を使用して同じリクエストが送信されると、レコードが正常に作成されます。

cURLコマンド

curl --user <username:password> -X POST -d '{"ProductId":302, "ProductCode":"MARKER", "Name": "Marker", "ProductType": "1,2"}'-H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products

レスポンス本文の例(以前のフレームワーク・バージョン)

{
  "ProductId" : 302,
  "ProductCode" : "MARKER",
  "Name" : "Marker",
  "Description" : null,
  "ProductType" : "1,2",
  "Picture" : null,
  "@context" : {
    "key" : "302",
    "links" : [ {
      "rel" : "self",
      "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/302",
      "name" : "products",
      "kind" : "item"
    }, {
      "rel" : "canonical",
      "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/302",
      "name" : "products",
      "kind" : "item"
    } ]
  }
}

ただし、フレームワーク・バージョン8では、配列に値リストが表示されると、レコードが正常に作成されます。

cURLコマンド

curl --user <username:password> -X POST -d '{"ProductId":302, "ProductCode":"MARKER", "Name": "Marker", "ProductType": ["1", "2"]}'-H 'REST-Framework-Version:8' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products

レスポンス本文の例(バージョン8)

{
  "ProductId" : 302,
  "ProductCode" : "MARKER",
  "Name" : "Marker",
  "Description" : null,
  "ProductType" : [ 1, 2 ],
  "Picture" : null,
  "@context" : {
    "key" : "302",
    "links" : [ {
      "rel" : "self",
      "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/302",
      "name" : "products",
      "kind" : "item"
    }, {
      "rel" : "canonical",
      "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/302",
      "name" : "products",
      "kind" : "item"
    } ]
  }
}

ノート:

逆に、フレームワーク・バージョン8ではカンマ区切り値はサポートされていません。そのため、フレームワーク・バージョン8を使用している場合は、値のリストを作成するためのリクエストをカンマ区切り値形式で送信しないでください。その場合、リクエストは失敗し、次のレスポンスが返されます:

{
  "title" : "Bad Request",
  "status" : "400",
  "o:errorDetails" : [ {
    "detail" : "Unable to parse the provided payload value for ProductType: Array value expected.",
    "o:errorCode" : "27534"
  }

キー属性の特殊文字の処理

フレームワーク・バージョン7以前では、主キーまたは行ファインダ・キーに特殊文字(スラッシュ(/)をセパレータとして使用した日付値など)を持つデータが含まれている場合、レスポンスで返されるRESTリソース・リンクは正しくありません。フレームワーク・バージョン8以降、この問題は修正され、レスポンスで正しいリソースURLリンクが返されます。この例では、キー値にスラッシュが含まれるリソースを確認します。まず、レコード"CatId" : 2の詳細をcatsリソースから取得します。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats?q=CatId=2

レスポンス本文の例(以前のフレームワーク・バージョン)

{
  "items" : [ {
    "CatId" : 2,
    "CatCode" : "ELEC/COMPUTER",
    "@context" : {
      "key" : "ELEC/COMPUTER",
      "links" : [ {
        "rel" : "self",
        "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%2FCOMPUTER",
        "name" : "cats",
        "kind" : "item"
      }, {
        "rel" : "canonical",
        "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%2FCOMPUTER",
        "name" : "cats",
        "kind" : "item"
      } ]
    }
  } ],
  "count" : 1,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "http://servername.fa.us2.oraclecloud.com/resources/<version>/cats",
    "name" : "cats",
    "kind" : "collection"
  } ]
}

レスポンスでは、"key" : "ELEC/COMPUTER"にスラッシュが含まれていることがわかります。予約文字に適用されるパーセント・エンコーディング・ルールに従ってスラッシュ(/)は%2Fにエンコードされますが、URLでは使用できません。 URLエンコーディングの標準により、URLのパーセント記号が再度パーセント・エンコーディング(%が%25に変更)され、URLでの使用に適合する必要があります。その結果、キーのパス・パラメータがELEC%2FCOMPUTERからELEC%252FCOMPUTERに変わります。フレームワーク・バージョン7以前では、URLでこのパス・パラメータを使用して詳細を取得しようとすると機能しません。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER

リクエストはエラーで失敗します:

HTTP/1.1 404 Not Found

ただし、フレームワーク・バージョン8ではこのエンコーディングがサポートされています。したがって、詳細を取得するリクエストを送信すると、レスポンスで返されるURLはエンコーディング標準に従って設定されます。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:8' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats?q=CatId=2

レスポンス本文の例(バージョン8)

{
  "items" : [ {
    "CatId" : 2,
    "CatCode" : "ELEC/COMPUTER",
    "@context" : {
      "key" : "ELEC%2FCOMPUTER",
      "links" : [ {
        "rel" : "self",
        "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER",
        "name" : "cats",
        "kind" : "item"
      }, {
        "rel" : "canonical",
        "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER",
        "name" : "cats",
        "kind" : "item"
      } ]
    }
  } ],
  "count" : 1,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "http://servername.fa.us2.oraclecloud.com/resources/<version>/cats",
    "name" : "cats",
    "kind" : "collection"
  } ]
}

また、URLでエンコードされたパス・パラメータ値(ELEC%252FCOMPUTER)を使用すると、有効なレスポンスを期待できます。

cURLコマンド

curl --user <username:password> -H 'REST-Framework-Version:8' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER

レスポンス本文の例(バージョン8)


  {
    "CatId" : 2,
    "CatCode" : "ELEC/COMPUTER",
    "@context" : {
      "key" : "ELEC%2FCOMPUTER",
      "links" : [ {
        "rel" : "self",
        "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER",
        "name" : "cats",
        "kind" : "item"
      }, {
        "rel" : "canonical",
        "href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER",
        "name" : "cats",
        "kind" : "item"
      } ]
    }
  }

例: RESTフレームワーク・バージョン9

このフレームワーク・バージョンでは3つの変更が導入されるため、各変更が箇条書きとして表示され、それぞれに独自の例と説明のセットが含まれています。

高精度数値のサポート

15桁を超える値を取得する場合、精度要件のために値が切り捨てられるか切り捨てられる可能性があります。データの損失を防ぐため、高精度の数値はJSON文字列タイプに変換されます。 RESTクライアントは、記述ペイロードおよびレスポンス・ペイロードでそのような値を文字列として処理できます。

レスポンス本文の例(以前のフレームワーク・バージョン)

返される数値の書式は' int64 'です。

{
  "EmpId": {
    "type": "integer",
    "format": "int64",
    "nullable": false,
    "x-hints": {
      "precision": 18
    }
  }
}

レスポンス本文の例(バージョン9)

返される数値の書式は' BigInt 'です。

{
  "EmpId": {
    "type": "string",
    "format": "BigInt",                
    "maxLength" : 18,
    "nullable": false,
    "x-hints": {
      "operators": ["=", ">", ">=", "<", "<=", "<>"]
    }
  }
}

無効なアクセサで問合せパラメータを使用する場合のエラー

GETリクエストが成功するには、RESTサービスに対して有効になっているアクセサとともに、許可された問合せパラメータを使用する必要があります。フレームワーク・バージョン9より前では、有効化されていないアクセサで問合せパラメータを使用した場合、エラーは発生しません。フレームワーク・バージョン9を起動しています。有効化されていないアクセサで?fields, ?expand, ?partialDescription, ?polymorphicType, ?partialDescriptionForCatalogなどの問合せパラメータを使用している場合、RESTクライアントは400 Bad requestエラーを表示します。

q問合せでのワイルドカード文字のサポート

フレームワーク・バージョン9以降、LIKE演算子を含む?q問合せでは、% (パーセント)、* (アスタリスク)、_ (アンダースコア)、? (疑問符)および\ (バックスラッシュ)などのワイルドカード文字の問合せをサポートするために、エスケープ文字として\ (バックスラッシュ)文字を使用できます。たとえば:

?q=DeptName like '%\%%' - query for DeptName containing % 
?q=DeptName like '%\*%' - query for DeptName containing * 
?q=DeptName like '%\_%' - query for DeptName containing _ 
?q=DeptName like '%\?%' - query for DeptName containing ? 
?q=DeptName like '%\\%' - query for DeptName containing \