コレクションの管理
「コレクション・リソース」は、アカウント、お知らせ、商談などのアイテムのリストを表します。 収集リソースをソート、フィルタおよびページ付けして、大規模な結果セットの使用および消費を容易にします。 たとえば、データ・セット全体ではなく、顧客回収リソースから情報のサブセットのみを選択する場合があります。 次の処理を使用して、収集リソースから返されたデータを管理できます:
問合せ
RESTリソースの問合せは簡単: 必要なレスポンスを取り戻すために、webサーバーとの対話方法を知る必要があります。 q
パラメータを使用してコレクション・リソースを問い合せてフィルタしたり、リソースでサポートされているfinder
パラメータを使用してレコードを問い合せることができます。 SCIMリソースを操作している場合は、attributes
パラメータを使用して問い合せ、filter
パラメータを使用して結果をフィルタできます。 これらのパラメータの詳細は、この項で説明するとおります。
問合せ可能属性の識別方法
GET操作で使用できる属性をqパラメータとともに使用できるようにするには、リソース・メタデータから属性の問合せ可能なプロパティを使用します。 GETメソッドを使用して、RESTリソースに関するメタデータを/describe
エンドポイントから取得します。 リクエストでは次のURL構文を使用します:
https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/<version>/<resource>/describe
receivingReceiptRequests
リソースの問合せ可能な属性を識別するとします。 このcURLコマンドを使用して、describeリクエストを送信します。
curl -X GET -u <username:password> https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/receivingReceiptRequests/describe HTTP/1.1 -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json' | json_pp
describeレスポンスで、属性の問合せ可能なプロパティは、その属性が問合せ可能かどうかを示します。

たとえば、スクリーンショットでは、CurrencyCode
属性の問合せ可能なプロパティがtrue
に設定されています。 つまり、この属性をURLに含めて、GET操作で使用できます。 たとえば:
https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/receivingReceiptRequests?q=CurrencyCode=USD
一方、問合せ可能なプロパティがfalse
に設定されている場合、GET操作でその属性を使用することはできません。 InsertAndProcessFlag
属性に対して問合せを実行するとします。 GETリクエストを送信するためにURLに含めます:
https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/receivingReceiptRequests?q=InsertAndProcessFlag=Yes
リクエストは失敗し、レスポンスで400 Bad Requestステータス・コードが返されます。 これは、InsertAndProcessFlag
属性の問合せ可能なプロパティが(スクリーンショットに示すように)false
に設定されており、問合せ可能な属性ではないことを示すためです。
q
問合せパラメータ
「RESTフレームワーク」をバージョン2として定義した場合、q
問合せパラメータは、コレクション・リソースをフィルタ処理するためにRowMatch式をサポートする拡張式構文を使用します。 バージョン2以降では、バージョン1でサポートされる例による問合せ構文を使用するリクエストはエラーを返します。
たとえば、セミコロンq=deptno>=10;loc!=NY
で区切られた問合せ式は、バージョン2以降でエラーを返します。 RowMatch式q= deptno>=10 or loc!=NY
は、バージョン2以降でサポートされています。 次に、バージョン2以降でサポートされている拡張問合せ構文の例を示します:
- フィールドの値が使用可能なリストにあるかどうかをテストするには、
in
演算子を使用します:DecisionLevelCode in ('DIRECTOR','VP')
- リレーショナル比較には、
between
およびnot between:
を使用WinProb between 80 and 100
WinProb not between 80 and 100
- 複雑な問合せ式を作成するには、
and
およびor
を、一致するカッコのセットとともに使用します:(DescriptionText is not null) or ((Revenue <= 300000) and (WinProb between 80 and 100))
REST Frameworkバージョン1を使用している場合は、リクエストで例による問合せ構文を使用できます。 ただし、例による問合せ構文は、バージョン2以降では機能しないことに注意してください。 バージョンの詳細については、「RESTフレームワーク・バージョンの設定」を参照してください。
次の表に、RESTデータ型と、問合せパラメータ文字列で使用できる有効な演算子を示します。 演算子BETWEEN
, NOT BETWEEN
, IN
, NOT IN
およびワイルドカード文字%
は、RESTフレームワーク・バージョン2以降でのみ使用できます。
RESTデータ型 | q パラメータでサポートされる演算子 |
---|---|
string |
|
boolean |
|
number |
|
integer |
|
date |
|
datetime
ノート: UTCとローカルの日時書式の両方がサポートされています。 |
|
子リソース属性の問合せ
q
問合せパラメータを使用して、最上位リソースで副問合せを実行できます。 問合せは、問合せ基準を満たす子または孫リソース・レコードを含む最上位レベルのリソース・レコードを返します。 この機能には、REST Frameworkバージョン2以上が必要です。
子リソースworkRelationshipsIn
およびnames
を持つworkers
リソースと、assignments
という孫リソースに対する問合せの2つの異なる例を見てみましょう。 最初の例では、指定されたPositionId
値を持つworkRelationships
とその子assignments
を含むworkers
の問合せを実行できます。
GET https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?q=workRelationships.assignments.PositionId in (407, 67, 23)
2番目の例では、names
ですべてのworkers
を問い合せることができます。ここで、FirstName
値には文字「Ki」が含まれています。
GET https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?q=names.FirstName like '%Ki%'
finder
問合せパラメータ
指定した基準に基づいてレコードを検索する場合は、finder
パラメータを使用します。 finder
パラメータは、リソースに関連付けられた事前定義済問合せです。 ファインダ変数で指定された基準に基づいてレコードを返すには、サポートされているファインダ名を使用します。 たとえば、ファインダPrimaryKey
およびファインダ変数AnnouncementId
を使用して、特定の識別子のアナウンスメントを取得します。 cURLコマンドの例を次に示します:
curl -u username:password \
-X GET https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/announcements?finder=PrimaryKey;AnnouncementId=300100015957778\
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'
ノート:
リソースでサポートされているファインダ名およびファインダ変数の詳細は、このガイドの「タスク」の項にあるリソースの「すべて取得」メソッドのRequest
> Query Parameter
> finder
の項を参照してください。
クロス・ドメイン・アイデンティティ管理(SCIM)リソースのシステムを問い合せるためのattributes
パラメータの使用方法
attributes
パラメータを使用して、SCIMリソースを問い合せます:
?attributes=<scim-attribute-list>
属性リストのSCIM表記
<attribute-name>[.<sub-attribute-name>]
attributes
パラメータは、埋込みSCIMリソースを含むレスポンスを返す任意のリクエスト(GET
, PATCH
, POST
、PUT
など)に含めることができます。
次に例を示します。
?attributes=id, name
?attributes=username, name.familyName
?attributes=displayName, email.primary
SCIMリソースでのfilter
パラメータの使用方法
filter
パラメータを使用して、一致するSCIMリソースのサブセットを指定して戻します:
?filter=<scim-filter>
次の表に、SCIMリソースに使用できるフィルタリング式の有効な演算子を示します。
オペレータ | 摘要 |
---|---|
|
|
|
|
|
|
|
「次で始まる」と解釈されます。
|
|
「次で終わる」と解釈されます。
|
co |
「次を含む」と解釈されます。
|
|
「等しい」と解釈されます。
|
|
「次と等しくない」と解釈されます。
|
|
「次以上」と解釈されます。
|
|
「次より大きい」と解釈されます。
|
|
「次以下」と解釈されます。
|
|
「次より小さい」と解釈されます。
|
|
「表す」と解釈され、属性に値が含まれているか、複合属性に空でないノードが含まれていることを示します。
|
v1リソースの問合せ
v1リソースを問い合せるには、$filter
パラメータを使用する必要があります。 この項では、$filter
パラメータで使用できる演算子もリストします。
オペレータ | 摘要 | 例: | サンプルURL |
---|---|---|---|
!= | 次と等しくない | activeFlag != true | ?$filter=activeFlag!=true |
|
大/小文字の区別なしの比較 | ename ~= 'king' | ?$filter=ename~='king' |
ノート:
- 演算子では大文字と小文字は区別されませんが、識別子とリテラル(true、false、nullなど)では大文字と小文字が区別されます。 たとえば、"
ename LIKE 'A%'
"は"ename like 'A%'
"と同等ですが、"Ename LIKE 'A%
'"または"ename like 'a%'
"と同等ではありません。 - リテラル値
string
およびdate
は、一重引用符(')で囲まれています。たとえば、'Hello World' , '1969-12-31'
などです。 - 数値および
boolean
リテラル値は、exmpleの場合は42, false
のように記述されます。 - 文字列内の一重引用符をエスケープするには、その前に別の一重引用符を付けます。たとえば、title= 'Where''s Wally?'のようにします
11.13.18.05バージョン・リソースを使用する一部の演算子は、空白が含まれているため、v1リソースでは使用できません。 演算子に空白が含まれている場合は、エンコーディングを必要とする特殊文字とみなされます。 かわりに、そのような演算子と同等のものを使用して同じレスポンスを取得できます。 次の表に、同等の演算子および使用例を示します。 この要件を排除するために、v1リソースでは、スペースを含む一部の演算子はサポートされていません。 かわりに、この表に示す同等の演算子を使用できます。
11.13.18.05でサポートされる演算子 | v1で使用する同等の演算子 | 例: |
---|---|---|
相似でない | ! | !(ename LIKE 'KING') |
IS NULL | = null | DeptName = null |
NULLでない | != null | DeptName != null |
BETWEEN | >=低いAND <=高 | salary >= 2000 AND salary <= 3000 |
次の間以外 |
|
|
次に含まれない | ! (IN) | ! (給与IN (800、1500、valueN)) |
子リソースの問合せ
子リソースのエンドポイントは、問合せでそのプロパティ名<child_accessor_property_name>を使用して示されます。 子リソース・コレクションを問い合せる場合は、次のリクエストを使用できます:
GET /objects/<module_name>/v1/<resource_name>/<resource_key_value>/<child_accessor_property_name>
子リソースのインスタンスを問い合せる場合は、次のリクエストを使用できます:
GET /objects/<module_name>/v1/<resource_name>/<resource_key_value>/<child_accessor_property_name>/<child_resource_key_value>
ページ番号付け
ほとんどのリソース・コレクションには、なんらかのページ区切りが必要です。 これがないと、単純な検索で何百万ものレコードが返され、ネットワークがクロールになります。 そのため、コレクション・リソースのすべてのレコードを受信するかわりに、RESTクライアント・レスポンスでページに表示されるレコードの数を制限できます。 これを行うには、リクエスト・ペイロードで次のパラメータを設定します:
limit
- ページング・サイズを指定offset
- リソースが返される開始点を指定totalResults
- 問合せに一致する検索レコードの合計数を含めるにはtrueに設定
レスポンス・ペイロードで次のフィールドを設定します:
hasMore
- コレクションから返されるレコードの数が増えた場合はtrueに設定し、コレクションから最後のレコード・セットが取得された場合はfalseに設定totalResults
- 検索レコードの合計数に設定
たとえば、クライアントは、お知らせリソースに対してGET
コマンドを実行します。 サーバーは100のお知らせを格納し、現在のリクエストは25だけを返します。 取得するレコードがさらに存在することを示すために、サーバーは読取り専用hasMore
フィールドをtrueに設定します。
レスポンス本文の例
{
"items": [
.
.
.
],
"count": 25,
"hasMore": true,
"limit": 25,
"offset": 0,
"links": [
{
.
.
.
}
]
}
リクエストでtotalResults
パラメータをtrueに設定すると、レスポンスには、検索基準に一致するレコードの合計数を示すtotalResults
フィールドが含まれます。 totalResults
値で示されるすべてのレコードを取得した後、サーバーはhasMore
をfalseに設定します。
{
"items": [
.
.
.
],
"totalResults": 100,
"count": 25,
"hasMore": true,
"limit": 25,
"offset": 0,
"links": [
{
.
.
.
}
]
}
limit
およびoffset
パラメータを指定すると、ページ区切り結果は順序付けされません。 一貫した結果を得るには、orderBy
パラメータを使用して結果を順序付けます。 ページング・リクエスト間で収集リソースを更新すると、各ページに表示されるレコードは異なる場合があります。
リクエストの例 | 返されたレコード |
---|---|
GET /announcements?offset=10&limit=20 |
11 から 30 |
GET /announcements?q=Subject LIKE 'meeting%'&limit=10 |
1 から 10 |
GET /announcements?q=Subject LIKE 'meeting%'&offset=25 |
26 から 50 |
GET /announcements?totalResults=true&limit=20 |
1 から 20 レスポンスには、問合せに一致するレコード数が含まれます。 |
ノート:
ほとんどのリソースでは、レコードを取得するための事前定義された問合せ制限は、デフォルトで500行または同様の値に設定されます。 設定された制限を超えるレコードを取得する必要がある場合は、制限およびオフセット・パラメータを使用してバッチで取得できます。 たとえば、約1000のレコードがある場合、一連のGETリクエストを使用して、200行のバッチで取得できます:/crmRestApi/resources/latest/subscriptionProducts?offset=0&limit=200
/crmRestApi/resources/latest/subscriptionProducts?offset=200&limit=200
/crmRestApi/resources/latest/subscriptionProducts?offset=400&limit=200
/crmRestApi/resources/latest/subscriptionProducts?offset=600&limit=200
/crmRestApi/resources/latest/subscriptionProducts?offset=800&limit=200
SCIMリソース・リクエストのレスポンス・レコードをページ区切りするには、リクエスト・ペイロードで次のパラメータを設定します:
count
- ページング・サイズを指定します。 このパラメータの推奨値は100です。startIndex
- リソースが返される開始点を指定します。
リクエストの例 | 返されたレコード |
---|---|
?attributes=username&startIndex=11&count=20 |
11 から 30 |
?attributes=firstname pr&count=10 |
1 から 10 |
v1リソースのページ区切り
$limit
パラメータと$offset
パラメータの組合せを使用して、リソース・コレクションをスクロールできます。 $limit
パラメータは、レスポンスで返されるリソースの数を定義します。 $offset
パラメータは、最初のリソースの開始索引を定義します。
ノート:
オフセットは0ベースです。 そのため、?$offset=0
を設定すると、最初のリソースが返されます。
GET /orders?$orderBy=orderDate&$limit=10&$offset=10
この例では、レスポンスに11番目のアイテムから始まる10個のレコードのセットが含まれます。
ソート
ソートは、大量のデータを処理しやすくするもう1つの機能です。 orderBy
問合せパラメータを使用して、コレクション・リソースから返されたアイテムをソートできます。
ノート:
予測可能なページング結果を取得するには、OptyId
やPartyNumber
などの一意の属性のみを使用して結果をソートする必要があります。 たとえば、商談の最初のページに移動するには、次のコマンドを使用します:
GET /opportunities?orderBy=OptyId
レスポンスで返された最後の商談にOptyId=1000
があり、次のページに移動すると、GETリクエストは次のように構造化されます:
GET /opportunities?orderBy=OptyId&q=OptyId>1000
ソート順序を設定するには、昇順にはasc
を、降順にはdesc
を使用します。 デフォルトの順序付け順序はasc
です。 レスポンス・ペイロードで返されるアイテムは、大/小文字が区別される順序でソートされます。
たとえば、documentId
に従ってアイテムを降順にソートするには、次のコマンドを入力します:
?orderBy=documentId:desc
Deptno
に従ってアイテムを昇順にソートするには、次のコマンドを入力します:
?orderBy=Deptno:asc
またはのみ
?orderBy=Deptno
asc
はデフォルトのソート順序であるためです。
問合せパラメータに複数のフィールドを含める場合、フィールドを指定する順序によってソート順が決まります。 たとえば、アイテムをtitle
の昇順でソートし、dateAdded
に従って降順でソートするには、次のコマンドを入力します:
?orderBy=title,dateAdded:desc
SCIMリソースのレコードのソート方法
sortBy
パラメータを使用して、コレクション・リソースから返されたアイテムをソートできます:
?sortBy=<scim-attribute>
ここで、SCIM属性名は単純な属性の場合は<attribute>
、複雑な属性の場合は<attribute.subattribute>
である必要があります。
たとえば、documentId
に従ってアイテムを降順にソートするには、次のコマンドを入力します:
?sortBy=documentId&sortOrder=descending
複数のフィールドに基づいてソートする場合(たとえば、アイテムをtitle
の昇順でソートし、dateAdded
に従って降順でソートする場合)には、次のコマンドを入力します:
?sortBy=title,dateAdded&sortOrder=descending
v1リソースのソート
$sortBy
パラメータを使用して、コレクション・リソースをソートできます。 フィールド名のカンマ区切りのリストを使用します。各フィールド名にはオプションのソート順序を'.' (コロン)で区切って追加します。 たとえば、employeesresourceコレクションを最初にdeptnoで昇順でソートし、次にsalaryで降順でソートするには、次のリクエストを送信します:
GET /employees?$sortBy=deptno:asc,salary:desc
収集リソースの管理方法がわかりました。