コレクションの管理
「コレクション・リソース」は、アカウント、顧客、商談など、品目のリストを表します。 収集リソースをソート、フィルタおよびページ付けして、大規模な結果セットの使用および消費を容易にします。 たとえば、データ・セット全体ではなく、顧客回収リソースから情報のサブセットのみを選択する場合があります。 次の処理を使用して、収集リソースから返されたデータを管理できます:
問合せ
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とローカルの日時書式の両方がサポートされています。 |
|
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パラメータは、GET, PATCH, POSTやPUTなど、埋込みSCIMリソースを含むレスポンスを返す任意のリクエストに含めることができます。
次に例を示します。
?attributes=id, name?attributes=username, name.familyName?attributes=displayName, email.primary
SCIMリソースでのfilterパラメータの使用方法
filterパラメータを使用して、一致するSCIMリソースのサブセットを指定して戻します:
?filter=<scim-filter>次の表に、SCIMリソースに使用できるフィルタリング式の有効な演算子を示します。
| オペレータ | 説明 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
「次で始まる」と解釈されます。
|
|
|
「次で終わる」と解釈されます。
|
| コア |
「次を含む」と解釈されます。
|
|
|
「等しい」と解釈されます。
|
|
|
「次と等しくない」と解釈されます。
|
|
|
「次以上」と解釈されます。
|
|
|
「次より大きい」と解釈されます。
|
|
|
「次以下」と解釈されます。
|
|
|
「次より小さい」と解釈されます。
|
|
|
「表す」と解釈され、属性に値が含まれているか、複合属性に空でないノードが含まれていることを示します。
|
ページ番号付け
ほとんどのリソース・コレクションには、なんらかのページ区切りが必要です。 これがないと、単純な検索で数百万件のレコードが返され、ネットワークがクロールになる可能性があります。 そのため、コレクション・リソースのすべてのレコードを受信するかわりに、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 |
ソート
ソートは、大量のデータを処理しやすくするもう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=descending収集リソースの管理方法がわかりました。