サポートされているHTTPメソッド
最も一般的に使用されるHTTPメソッド(または動詞)は、GET
, POST
, PATCH
およびDELETE.
です REST APIの構成要素であるこれらのメソッドは、URLを使用してRESTリソースに適用されるアクションを定義します。 詳細は、「カスタム・アクション」を参照してください。
ノート:
- REST APIのレスポンス時間は、いくつかのファクタによって異なります。 Oracleでは、RESTリクエスト要件が変更されたかどうかを定期的に確認することをお薦めします。 また、サービス構成で容量調整やその他の変更が必要かどうかもサービス管理者に確認してください。
- 通常、子リソースは親リソースからセキュリティ権限を継承します。 したがって、子リソースでメソッドを使用するには、親リソースでそのメソッドを使用するためのアクセス権が必要になる場合があります。 ただし、それらのリソースにアクセスするための権限要件が異なる子リソースが存在する場合があります。
次の表に、単一のリソースおよび収集リソースのメソッドとそのスコープを示します。
メソッド | 単一リソースで機能しますか。 | コレクション・リソースで機能しますか。 |
---|---|---|
はい。 単一のリソースを取得します。 |
はい。 コレクション内のサブセットまたはすべてのリソースを取得します。 |
|
いいえ。 |
はい。 コレクションに新しいリソースを作成します。 |
|
はい。 リソースを更新します。 |
いいえ。 |
|
はい。 リソースを削除します。 |
いいえ。 |
SCIMリソースでサポートされるHTTPメソッド
次の表に、SCIMリソースのメソッドとそのスコープを示します。
SCIMリソース | GET |
POST |
PUT |
PATCH |
DELETE |
Filtering |
---|---|---|---|---|---|---|
ユーザー | Yes | Yes | Yes | Yes | Yes | Yes |
ロール | Yes | No | No | Yes | No | Yes |
一括 | No | Yes | Yes | Yes | Yes | Yes |
スキーマ | Yes | No | No | No | No | No |
ResourceTypes | Yes | No | No | No | No | No |
BPMリソースでサポートされるHTTPメソッド
GET
, POST
, PUT
およびDELETE
メソッドを使用して、BPMリソースに対する基本的な作成、読取り、更新および削除操作を実行できます。
GETメソッド
このメソッドは、リソースから情報を取得するために使用します。 単一のリソースとコレクション・リソースの両方を問い合せるには、expand
、fields
およびonlyData
問合せパラメータを使用します。 問合せ結果にフィルタを適用するには、単一のリソースとコレクション・リソースに異なるパラメータを使用します。
単数形および収集リソースを問い合せるためのパラメータのリストは次のとおりです:
expand
階層リソースの問合せ時に、子リソースと親リソースを取得します。 デフォルトでは、サーバーは子リソースを返しません。 有効な値は次のとおりです:
- 単一の子リソースの名前。
- 複数の値を指定する子リソース名のカンマ区切りリスト。
- すべての子リソースを展開するためのキーワード
all
。
「RESTフレームワーク・バージョン3」から、expand
パラメータは、コレクションのページ区切りをサポートするために子リソース・アイテムをコレクション・リソースとして返します。 このパラメータは、単数リソースとコレクション・リソースの両方に適用されます。
URLの例
/fscmRestApi/resources/<version>/invoices/359240?expand=invoiceLines
レスポンス本文の例
{
"InvoiceId": 359240,
"InvoiceNumber": "Withholding tax - 300100170737078-2",
"InvoiceCurrency": "THB",
"PaymentCurrency": "THB",
"InvoiceAmount": 5,
. . .
"invoiceLines": {
"items": [
{
"LineNumber": 1,
"LineAmount": 5,
"AccountingDate": "2018-12-06",
. . .
"links": [
{
"rel": "self",
. . .
}
}
fields
指定されたフィールドの情報を取得します。 有効な値は次のとおりです:
- 単一プロパティの名前。
- 複数の値を指定するプロパティ名のカンマ区切りリスト。
「RESTフレームワーク・バージョン3」から、fields
パラメータは、コレクションのページ区切りをサポートするために子リソース・アイテムをコレクション・リソースとして返します。 このパラメータは、単数リソースとコレクション・リソースの両方に適用されます。
onlyData
取得されたデータに、リンクのないリソース・フィールド値のみが含まれているかどうかを示します。 デフォルト値は「偽」で、取得されたデータにデフォルトでリンクが含まれていることを示します。 このパラメータは、単数リソースとコレクション・リソースの両方に適用されます。
URLの例
/fscmRestApi/resources/<version>/announcements/300100090149733?onlyData=true
レスポンス本文の例
{
"AnnouncementId": "300100090149733",
"CategoryCode": "OF",
"CreatedBy": "SEED_DATA_FROM_VERTICAL",
"CreationDate": "2017-05-18T08:51:04.001+00:00",
"ExpireDate": "2017-05-19T00:00:00+00:00",
"ExpiryDaysFlag": null,
"LastUpdateDate": "2017-05-18T08:51:07.609+00:00",
"LastUpdateLogin": "4FC58160B86257BCE0539D06F10A598C",
"LastUpdatedBy": "SEED_DATA_FROM_VERTICAL",
"ObjectVersionNumber": 1,
"StartDate": "2017-05-18T00:00:00+00:00",
"Subject": "meeting at 4pm ",
"Description": "meeting at 4pm",
...
}
limit
サーバーが返すアイテムの最大数を指定する正の整数値。 アプリケーションのパフォーマンスを向上させるために、サーバーがこの値をオーバーライドする場合があります。 クライアント・リクエストで制限値が指定されていない場合、サーバーはデフォルトの制限値25を使用します。 このパラメータは、収集リソースにのみ適用されます。
offset
offset=0
の場合、レスポンスには、コレクションの最初のアイテムから始まるすべてのリソースが含まれます。offset=10
の場合、レスポンスには11「番目」アイテムから始まるリソースが含まれます。
q
コレクションから返されるアイテムのフィルタを指定します。 このパラメータは、収集リソースにのみ適用されます。
RESTフレームワーク・バージョン1では、問合せパラメータはwhere句で使用され、セミコロンで区切られた1つ以上の式が含まれています。 次に例を示します: q=deptno>=10 and <= 30;loc!=NY
.
RESTフレームワーク・バージョン1でサポートされる演算子:
=
(等しい)>
(より大きい)<
(より小さい)>=
(以上)<=
(以下)!=
(等しくない)AND
(And)OR
(Or)NOT
(Not)LIKE
(Like)
RESTフレームワーク・バージョン1で許可される特殊文字:
- エスケープ文字を定義する
\
(バックスラッシュ)。 - ワイルドカード文字を定義する
*
(アスタリスク)。 - リテラルを定義する
"
(二重引用符)および'
(一重引用符)。 サポートされている演算子を含むパラメータ値が正しく解釈されるように、引用符で囲まれた文字列の前後に空白を追加する必要があります。 次に例を示します。Keyword=<SPACE>':204 WITHIN EGP_ITEM_ORG_SECTION AND :US WITHIN EGP_ITEM_LANG_SECTION AND AS54888'<SPACE> ;ItemDefinitionOrgId=204;OrganizationId=204;
RESTフレームワーク・バージョン2以降では、問合せパラメータは、リソースから取得する特定の行を識別する行一致式の書式を受け入れます。
<>
(等しくない)BETWEEN
(between)NOT BETWEEN
(間にない)IN
(in)NOT IN
(次に含まれない)IS NULL
IS NOT NULL
- エスケープ文字を定義する
\
(バックスラッシュ)。 - ワイルドカード文字を定義する
%
(パーセント)。 - リテラルを定義する
"
(二重引用符)および' (一重引用符)。
totalResults
レスポンスの問合せに一致する検索レコードの合計数を含めるかどうかを示すブール値。 デフォルト値はfalseです。 このパラメータは、収集リソースにのみ適用されます。
URLの例
/fscmRestApi/resources/version/announcements?totalResults=true&limit=5
レスポンス本文の例
{
"items": [],
"totalResults": 55,
"count": 5,
"hasMore": true,
"limit": 5,
"offset": 0,
"links": []
}
orderBy
レスポンス・ペイロードのアイテムの順序を指定します。 このパラメータは、収集リソースにのみ適用されます。 詳細は、「ソート」を参照してください。
finder
特定のバインド・パラメータを含む事前定義済のwhere
句を使用して、コレクションを検索します。 このパラメータは、収集リソースにのみ適用されます。
たとえば、お知らせリソースは、AnnouncementId
という名前のバインド・パラメータの1つを使用して、PrimaryKey
というファインダを定義します。 クライアントはこのファインダを使用して、特定の識別子のアナウンスメントをフェッチできます。
たとえば:
finder=PrimaryKey;AnnouncementId=300100015957778
このコマンドでは、問合せパラメータ値の形式は次のとおりです:
<finder>;<attr1>=<val1>,<attr2>=<val2>
.
dependency
Country
およびState
フィールドが含まれます:
{
"Country" : "US",
"State" : "CA"
}
locationリソースは、StateリソースからStateフィールドの値を取得します。この値には、Countryリソースに依存する値リストが含まれています。 クライアントで国をBRに変更するとします。 新しい有効な州のリストを表示するには、クライアントは国フィールドのBRを使用するサーバーにリクエストを送信し、関連する州リストを取得します。
States?dependency=Country=BR
links
links
問合せパラメータを使用してリソース・アイテムまたはリソース・コレクションをリクエストすると、レスポンスには、パラメータ値に一致するリレーション・タイプ(rel
)を持つリンクのみが表示されます。 パラメータ値の書式は、リンクの関連タイプを表すカンマ区切りリスト(<rel_name>
、<rel_name>
)です。 リストでは、サポートされている属性値(self
、canonical
など)を使用できます。 このパラメータは、単数リソースとコレクション・リソースの両方に適用されます。
ノート:
onlyData
がtrue
に設定されている場合、linkパラメータをonlyData
と組み合せることはできません。 これは、ペイロードにlinks
セクションが表示されないためです。
include
アプリケーションで宣言されている特定の可視性のリソースの説明を取得するために使用されます。 表示は、unlisted
(プライベート・リソースの場合)またはpublic
(パブリック・リソースの場合)のいずれかに設定されます。 all
を使用して、両方のタイプのリソースを取得することもできます。 パラメータ値の書式は、リソースの可視性タイプを表すカンマ区切りリスト(<visibility_type>
、<visibility_type>
)です。 このパラメータは、describeリクエストにのみ適用されます。
?include=all
または?include=unlisted
を追加する必要があります。 このパラメータと、describeで使用できるその他のパラメータを組み合わせることができます。 たとえば、
/<resource>/describe?metadataMode=minimal&include=all
includeChildren
includeChildren
パラメータに使用されるブール値によって異なります:
- すべての子リソースを含めるには、describeリクエストに
?includeChildren=true
を追加します。 - すべての子リソースを除外するには、describeリクエストに
?includeChildren=false
を追加します。
/describe?metadataMode=list
を除き、このパラメータと、describeで使用できるその他のパラメータを組み合わせることができます。 このパラメータは、説明および単数形のリソースに適用されます。
showAnnotations
このパラメータを使用して、リソースに関連付けられた別のXMLファイルに格納されている注釈を追加または除外できます。 レスポンスは、showAnnotations
パラメータに使用されるブール値によって異なります:
- 注釈を含めるには、describeリクエストに
?showAnnotations=true
を追加します。 - すべての子リソースを除外または非表示にするには、describeリクエストに
?showAnnotations=false
を追加します。
/describe?metadataMode=list
を除き、このパラメータと、describeで使用できるその他のパラメータを組み合わせることができます。 注釈(定義されている場合)は、metadataMode=minimal
以外は、デフォルトでレスポンスに表示されます。 ただし、metadataMode=minimal
を使用していて、子リソースを表示する場合は、describeリクエストに?showAnnotations=true
を追加する必要があります。 たとえば、
/<resource>/describe?metadataMode=minimal&?showAnnotations=true
metadataMode
このパラメータを使用して、説明リクエストから取得する詳細のレベルを決定できます。 デフォルトでは、完全なdescribeによって、すべてのリソースの情報(各リソースのメタデータを含む)がすべて返されます。 取得される情報を制御するには、次のパラメータ値を使用します:
minimal
: 親リソースのタイトルとリンクのみを取得する場合は、describeリクエストに?metadataMode=minimal
を追加します。list
: メタデータなしで自己リンクのみが必要な場合は、describeリクエストに?metadataMode=list
を追加します。
オプションで、metadataMode
パラメータに追加のパラメータを追加できます。 子リソースを含めるには、includeChildren
を追加し、リソース注釈を含めるには、showAnnotations
を追加します。 たとえば、?metadataMode=minimal&includeChildren=true
を追加して、それに含まれるすべての子リソースを含む最小限のカタログ記述を取得できます。
resources
describeレスポンスで返されるリソースをフィルタ処理および制限するために使用します。 パラメータ値の書式は、リソースの名前を含むカンマ区切りリスト(<resource_name1>
、<resource_name2>
)です。 このパラメータと、describeで使用できるその他のパラメータを組み合わせることができます。
たとえば、カタログに4つのリソースが含まれているとします: organizations
, departments
, employees
, jobs
(リクエストに?resources=employees,jobs
を追加)は、employees
およびjobs
の情報のみを返します。
partialDescription
このパラメータを使用して、リソース・コレクション内の親子ネストされた階層内のリソースに対して取得できるメタデータ情報を制御できます。 そのため、子リソースでメタデータをリクエストすると、レスポンス・ペイロードにその子リソースの完全なメタデータが含まれることが予想されます。 ただし、階層の下位の子については、メタデータへのリンクは取得できますが、メタデータ自体は取得できません。
たとえば、departments
リソースにはemployees
リソースが含まれ、employees
子リソースにはbonus
という別の子が含まれます。 リクエストがemployees
子リソースを対象としている場合は、employees
のメタデータを取得しますが、bonus
子リソースの場合は、そのメタデータへのリンクのみを取得します。 前述の例に基づくサンプル・リクエストを次に示します。 リクエストでpartialDescription
パラメータを使用します:
/departments/describe?partialDescription=Employees
レスポンス本文で、子要素を確認して、階層内の子リソースの部分的な説明リンクを取得します。
{
"Resources" : {
"Employees" : {
...
},
"attributes" : [ {
...
}]
...
"children" : {
"Bonus" : {
"$ref" : "http://servername/restapi/resources/version/departments/describe?partialDescription=Employees.Bonus"
},
...
"links" :
...
}
}
}
そのリンクを使用して、bonus
リソースのメタデータを表示できます。
ノート:
このパラメータを他のパラメータと組み合せることはできません。
polymorphicType
このパラメータを使用して、ポリモーフィックで他のアイテムへの参照を持つルート・リソースのサブタイプ情報を取得できます。 これらのアイテムには、個々のリンクからアクセスできます。 リソースが多相かどうかを知るには、まずリソース・レベルで記述リクエストを送信する必要があります。 リソースが多相である場合、レスポンスには、子またはその子に対する多相サブタイプ情報が含まれます。 たとえば、contacts
リソースに対してdescribeリクエストを送信するとします:
https://server.oraclecorp.com:7501/hcmRestApi/resources/11.13.18.05/contacts/describe
レスポンスには、多相サブタイプの詳細を表示するために使用できるリンクが含まれている場合があります。 このサンプル・レスポンスでは、リンクは多相サブタイプcontacts.addresses.addressesDFF
を指します。
},
"subtypes" : {
"discriminator" : "__FLEX_Context",
"mapping" : {
"$ref" : "https://server.oraclecorp.com:7501/hcmRestApi/resources/11.13.18.05/contacts/describe?polymorphicType=contacts.addresses.addressesDFF"
}
レスポンス内のリンクをクリックし、さらにナビゲートします。 リソース階層に応じて、レスポンス本文に表示される複数のリンクに従う必要があります。 そのサブタイプの実際のスキーマとその属性およびリソースの詳細メタデータが表示されるまで、ナビゲートを続行します。
ノート:
このパラメータを他のパラメータと組み合せることはできません。
v1リソースのGETメソッド
v1リソースの場合、コレクション・リソースの詳細を取得するには、次の形式でリクエストURLを使用できます:
GET /objects/<module_name>/v1/<resource_name>
リソース・キーによるオブジェクト詳細の取得
リソース・キーを使用して、リソースの問合せをさらに絞り込むことができます。 リソース・キーは、ビジネス・オブジェクトのURLエンコード・キー値の連結文字列です。 リソース・キーは、主キー、代替キーまたは複数の識別子フィールドで構成されるコンポジット・キーです。 これらのすべての値がまとめて、レスポンス・ペイロードで返されるリソース識別子を形成します。
キー別にビジネス・オブジェクトの詳細を取得するには、次の形式でリクエストURLを使用できます:
GET /objects/<module_name>/v1/<resource_name>/<resource_key_value>
リソース識別子の値は、レスポンス・ペイロードの$idフィールドに表示されます。
子リソースv1リソースでは、子収集リソースの詳細を取得するために、次の形式でリクエストURLを使用できます:
GET /objects/<module_name>/v1/<resource_name>/<resource_key_value>/<child_accessor_property_name>
子リソース・コレクションのエンドポイントは次のとおりです:
/<resource_name>/<resource_key_value>/<child_accesor_property_name>
子リソースのURIは次のとおりです:
/<resource_name>/<resource_key_value>/<child_accessor_property_name>/<child_resource_key_value>
- 孫のURL
/<resource_name>/<resource_key_value>/<child_accessor_property_name>/<child_resource_key_value>/<grandchild_accessor_property_name>
- ひ孫のURL
/<resource_name>/<resource_key_value>/<child_accessor_property_name>/<child_resource_key_value>/<grandchild_accessor_property_name>/<grandchild_resource_key_value>/<greatgrandchild_accessor_property_name>
整形
$fieldsパラメータを使用して、リソース内のフィールドを選択できます。 フィールドの絶対リストを指定するには、 ?$fields=<field>,...,<field>
を使用します。
ここでは、同じリソースのフィールド名は、で区切られます。 "."を使用して、子および関連リソースを指定できます。 たとえば:
?$fields=<accessor>.<field>".
リクエストに不明なフィールドを含めると、400 Bad Request
が返されます。
デフォルト・シェイプ
v1リソースの場合、URLに値が指定されていないかぎり、パラメータはデフォルト値を使用します。 たとえば、GET /<resource_name>は次のようになります:
GET /<resource_name>?$offset=0&$limit={defaultPageSize}
ビジネス・ビュー
ビジネス・ビューは、ビジネス・オブジェクト階層全体での問合せを、収集問合せパラメータと組み合せて簡略化する、ビジネス・オブジェクトに関する事前定義済のビューです。 ビジネス・ビューにパラメータがある場合は、URLパラメータを使用してそれらのパラメータの値を指定して、問合せを実行できます。 デフォルト値を持つパラメータの場合、値を渡す必要はありません。
次に例を示します: /orders/$views/exceptionOrders?paramDate=2020-12-01
この例では、" exceptionOrders
"ビューは、フィルタ条件" status = 'EXCEPTION' AND date > :paramDate
"を定義します(指定された日付より後に作成されたEXCEPTION
状態のすべてのオーダーを検索します)。
POSTを介した問合せ
v1リソースの場合、親および子リソースのページ区切り、検索またはソート基準の詳細を取得するには、POSTメソッドを使用してリソースを問い合せることができます:
拡張問合せ拡張問合せは、単一のリソース・コースの問合せに使用されます。
POST /.../orders/1/$query
リクエスト本文の例を次に示します:
{
name: "getTimezoneList",
description: "Gets multiple timezones",
request: {
path: "/objects/{$config.apiVersion}/timezones",
method: "GET"
} }
拡張問合せすべて
拡張問合せallは、リソース・コレクションの問合せに使用されます。
POST /.../orders/$query
リクエスト本文の例を次に示します:
Content-Type: application/json
{
"collection": {
"filter": "date > '2020-12-01'"
},
"fields": ["orderMode"],
"accessors": {
"customer": {
"fields": ["name"]
},
"lines": {
"collection": {
"filter": "status = 'EXCEPTION'"
},
"accessors": {
"shipments": {
"collection": {
"sortBy": [{"shippedDate":"desc"}],
"limit": 1
}
}
}
}
}
}
POSTメソッド
リソースに新しいアイテムを作成するために使用します。 リクエスト・メディア・タイプは、次のとおりです。
application/vnd.oracle.adf.resourceitem+json
ノート:
Upsert-Mode
ヘッダーを使用して、既存のレコードを更新したり、単一のPOSTリクエストで新しいレコードを作成できます。 リクエストでUpsert-Mode
ヘッダーをtrueに設定し、アイテムがリクエストで指定された値と一致すると、レコードが更新されます。 それ以外の場合、RESTフレームワークは新しいレコードを作成します。 アップサート機能を機能させるには、リソースの作成に必要なリソースの必須属性がリクエストに含まれていることを確認します。
v1リソースのPOSTメソッド
v1リソースを作成するには、次の形式でリクエストURLを使用できます:
POST /invoices/v1/invoices
適切なjsonペイロードを含むコレクションURLでPOSTを使用してリソースを作成します。
URLの例
POST https//<servername>/api/boss/data/objects/invoices/v1/invoices/
{
"invoiceId": "99",
"invoiceNumber": "000099",
"documentSequence": null,
"total": {
"currency": "USD",
"amount": "2212.76"
}
}
Response
Status : 201
Cache-Control : no-cache, no-store, must-revalidate
リクエストURLを持つ子リソースは、次の形式で作成できます:
POST /invoices/v1/invoices/000006/invoiceLines
PATCHメソッド
リソースのデータを更新するために使用します。 PATCH
メソッドは、リクエスト本文で指定されたフィールドのみを更新します。 リクエスト・メディア・タイプは、次のとおりです。
application/vnd.oracle.adf.resourceitem+json
v1リソースのUPDATEメソッド
v1リソースを更新するには、次の形式でリクエストURLを使用できます:
PATCH /invoices/v1/invoices/000002
アイテムURLのPATCHを使用して、適切なjsonペイロードでリソースを更新します。
URLの例
PATCH https://<servername>/api/boss/data/objects/invoices/v1/invoices/000099
{
"total": {
"amount": "2212.77"
}
}
レスポンス本文の例
Response
Status : 204
Cache-Control : no-cache, no-store, must-revalidate
DELETEメソッド
リソースを削除するために使用します。 メソッドにはリクエスト本文は必要ありません。
v1リソースのDELETEメソッド
v1リソースを削除するには、次の形式でリクエストURLを使用できます:
DELETE /invoices/v1/invoices/000006
アイテムURLでDELETE
を使用してリソースを削除します。
URLの例
DELETE https://<servername>/api/boss/data/objects/<module segments>/v1/<service name>
レスポンス本文の例
Response
Status : 204
Cache-Control : no-cache, no-store, must-revalidate
リクエストURLを持つ子リソースを次の形式で削除できます:
DELETE /invoices/v1/invoices/000006/invoiceLines/000006,1
カスタム・アクション
リソースは、標準の作成、読取り、更新および削除(CRUD)アクションではないカスタム・アクションを公開する場合があります。 たとえば、アプリケーション・コンポーザを使用して標準オブジェクトで作成されたカスタム・オブジェクト関数は、カスタム処理として使用できます。 カスタム・アクションは、常にPOSTメソッドを使用して開始されます。
関連するリクエスト・メディア・タイプは次のとおりです:
application/vnd.oracle.adf.action+json
レスポンス・メディア・タイプは、次のとおりです。
application/vnd.oracle.adf.actionresult+json
次のリクエストには常にカスタム・アクションが含まれ、オプションでカスタム・アクションの入力パラメータの配列が含まれます:
application/vnd.oracle.adf.action+json
メディア・タイプのJSONスキーマは次のとおりです:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "Action execution representation.",
"description": "Represents the action execution and its parameters.",
"properties": {
"name": {
"type": "string",
"description": "Action name."
},
"parameters": {
"type": "array",
"description": "Parameter name/value pair.",
}
},
"required": [
"name"
]
}