コレクションの管理
「コレクション・リソース」は、アカウント、お知らせ、商談などのアイテムのリストを表します。 収集リソースをソート、フィルタおよびページ付けして、大規模な結果セットの使用および消費を容易にします。 たとえば、データ・セット全体ではなく、顧客回収リソースから情報のサブセットのみを選択する場合があります。 次の処理を使用して、収集リソースから返されたデータを管理できます:
問合せ
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_ppdescribeレスポンスで、属性の問合せ可能なプロパティは、その属性が問合せ可能かどうかを示します。
たとえば、スクリーンショットでは、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 100WinProb 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><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 |
containsと解釈されます。
|
|
|
「等しい」と解釈されます。
|
|
|
「等しくない」と解釈されます。
|
|
|
「次以上」と解釈されます。
|
|
|
「次より大きい」と解釈されます。
|
|
|
「次以下」と解釈されます。
|
|
|
「次より小さい」と解釈されます。
|
|
|
「表す」と解釈され、属性に値が含まれているか、複合属性に空でないノードが含まれていることを示します。
|
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リテラル値は、42, falseのように記述されます。 - 文字列内の一重引用符をエスケープするには、その前に別の一重引用符を付けます。たとえば、title= 'Where''s Wally?'のようにします
11.13.18.05バージョン・リソースを使用する一部の演算子は、空白が含まれているため、v1リソースでは使用できません。 演算子に空白が含まれている場合は、エンコーディングを必要とする特殊文字とみなされます。 かわりに、そのような演算子と同等のものを使用して同じレスポンスを取得できます。 次の表に、同等の演算子および使用例を示します。 この要件を排除するために、v1リソースでは、スペースを含む一部の演算子はサポートされていません。 かわりに、この表に示す同等の演算子を使用できます。
| 11.13.18.05でサポートされている演算子 | v1で使用する同等の演算子 | 例 |
|---|---|---|
| NOT LIKE | ! | !(ename LIKE 'KING') |
| IS NULL | = null | DeptName = null |
| IS NOT NULL | != null | DeptName != null |
| BETWEEN | >= low AND <= high | salary >= 2000 AND salary <= 3000 |
| NOT BETWEEN |
|
|
| 次に含まれない | ! (IN) | ! (給与IN (800、1500、valueN)) |
子リソースの問合せ
子リソースのエンドポイントは、問合せでプロパティ名<child_accessor_property_name>を使用して示されます。 子リソース・コレクションを問い合せる場合は、次のリクエストを使用できます:
GET /objects/<module_name>/v1/$openapi/<resource>/<resource_key_value>/<child_accessor_property_name>子リソースのインスタンスを問い合せる場合は、次のリクエストを使用できます:
GET /objects/<module_name>/v1/$openapi/<resource>/<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=200SCIMリソースのレコードのページ区切り
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:descDeptnoに従ってアイテムを昇順にソートするには、次のコマンドを入力します:
?orderBy=Deptno:ascまたはのみ
?orderBy=Deptnoascはデフォルトのソート順序であるためです。
問合せパラメータに複数のフィールドを含める場合、フィールドを指定する順序によってソート順が決まります。 たとえば、アイテムをtitleの昇順でソートし、dateAddedに従って降順でソートするには、次のコマンドを入力します:
?orderBy=title,dateAdded:descSCIMリソースのレコードのソート方法
sortByパラメータを使用して、コレクション・リソースから返されたアイテムをソートできます:
?sortBy=<scim-attribute><attribute>、複雑な属性の場合は<attribute.subattribute>である必要があります。
たとえば、documentIdに従ってアイテムを降順にソートするには、次のコマンドを入力します:
?sortBy=documentId&sortOrder=descending複数のフィールドに基づいてソートする場合、たとえば、アイテムをtitleの昇順でソートし、dateAddedに従って降順でソートするには、次のコマンドを入力します:
?sortBy=title,dateAdded&sortOrder=descendingv1リソースのソート
$sortByパラメータを使用してコレクション・リソースをソートできます。 フィールド名のカンマ区切りリストを使用します。各フィールド名にはオプションのソート順序を'.' (コロン)で区切って追加します。 たとえば、employeesresourceコレクションを最初にdeptnoで昇順でソートし、次にsalaryで降順でソートするには、次のリクエストを送信します:
GET /employees?$sortBy=deptno:asc,salary:desc収集リソースの管理方法がわかりました。