コレクションの管理
コレクション・リソースは、カテゴリ、言語、ロケールなどのアイテムのリストを表します。 収集リソースをソート、フィルタおよびページ付けして、大規模な結果セットの使用および消費を容易にします。 たとえば、データ・セット全体ではなく、コンテンツ・コレクション・リソースから情報のサブセットのみを選択する場合があります。 次の処理を使用して、収集リソースから返されたデータを管理できます:
フィルタ
フィルタリングは、RESTクライアントで返されるデータおよび表示されるデータの量を制限するために必要です。
次の表に、URIの例を使用してRESTリソースに対して実行できるフィルタ操作の一部を示します。
| 操作 | メソッド | URIの例 | 説明 |
|---|---|---|---|
| すべてのコンテンツを取得しています |
GET |
|
拡張モードでコンテンツ・オブジェクトのページ区切りリストを返します。 |
| レコードIDによるコンテンツ・オブジェクトの取得 |
GET |
|
FULLモードでコンテンツ・オブジェクトを返し、そのコンテンツの公開済バージョンをデフォルト・ロケールで表示します。 |
ページ付け
リソースのコレクションをページ区切りするには、limitやoffsetなどのパラメータを使用します。 リソースのコレクションを返すほとんどのリソースは、これらのパラメータをサポートしています。
次の表に、ページ区切りに使用される制限およびオフセット・パラメータを示します。
| パラメータ | 説明 |
|---|---|
| 制限 | サーバーから返されるアイテムの最大数を指定する正の整数値。 パフォーマンス上の理由により、サーバーが値を上書きする場合があります。 クライアントによって制限値が指定されていない場合、サーバーはデフォルトの制限値を使用します。 |
| offset | 返される最初のアイテムのインデックスを指定する負でない整数値。 オフセット索引は0から開始されます。 クライアントによってオフセット値が指定されていない場合、サーバーはデフォルト値の0を使用します。 |
単純なページングは、制限問合せパラメータとオフセット問合せパラメータの両方を指定することで実現できます。
たとえば、コンテンツ?offset=10&limit=20を使用してGETリクエストを発行すると、レスポンスには、すべてのコンテンツ・オブジェクトの11から30番目の位置までの最大20個のコンテンツ・オブジェクトが含まれます。
ノート:
limitおよびoffsetパラメータの使用中に、リソース・コレクション内のアイテムがページング・リクエスト間で更新されると、不整合が発生する可能性があります。ソート
orderByリクエスト・パラメータは、オブジェクトのコレクションをリクエストしたときに受信するオブジェクトのリストをソートするために使用されます。 ほとんどのメソッドは、orderByリクエスト・パラメータをサポートしています。
orderByパラメータで使用する様々な値は、スキーマおよびリソースのカタログ情報で確認できます。 スキーマおよびカタログ情報を取得するには、HTTPリクエストでmediaType値を" application/schema+json "としてGETメソッドを使用します。
ノート:
予測可能な結果を取得するには、OptyIdやPartyNumberなどの一意の属性のみを使用して結果をソートする必要があります。 たとえば、商談の最初のページに移動するには、次のコマンドを使用します:
GET /opportunities?orderBy=OptyIdレスポンスで返された最後の商談にOptyId = 1000があり、次のページに移動すると、GETリクエストは次のように構造化されます:
GET /opportunities?orderBy=OptyId>100リソースのスキーマおよびカタログ情報を取得するURIの例を次に示します:
https://<REST_API_HOST>/km/api/latest/metadata-catalog/{resourceName}
このリクエストに対するレスポンスで、sortableフラグがtrueに設定されているスキーマ・プロパティを探す必要があります。これらは、orderByリクエスト・パラメータで使用できるリソースの唯一のフィールドです。
ほとんどのリソースは、スキーマ・カタログ・リクエストをサポートしています。 リソースがスキーマ・カタログ・リクエストをサポートしていない場合は、特定のドキュメントを参照して、orderByパラメータとともに使用する追加の値を取得します。
ソート順
orderByパラメータ値の一部として昇順または降順を指定して、リソース・コレクションを昇順または降順にソートできます。 順序を指定しない場合、orderByパラメータはデフォルトでリソース・コレクションを昇順にソートします。
リクエストの例
リストを昇順または降順にソートするリクエストの例を次に示します:
GET /content?orderBy=documentIdリクエストは、documentIdパラメータ値で昇順にソートされたコンテンツ・オブジェクトを返します。
GET /content?orderBy=documentId:descリクエストは、documentIdパラメータ値で降順にソートされたコンテンツ・オブジェクトを返します。
大文字と小文字の区別
orderByパラメータ値の一部として大/小文字を区別するか、大/小文字を区別しないかを指定することで、リソース・コレクションを大/小文字の区別でソートできます。 大/小文字の区別を指定しない場合、デフォルト・パラメータは、orderByパラメータで使用されるフィールドの標準の大/小文字に従ってリストをソートします。
リクエストの例
大文字と小文字の区別に従ってリストをソートするリクエストの例を次に示します:
GET /content?orderBy=title:case-sensitiveこのリクエストは、タイトル・ケースで適切にソートされたコンテンツ・オブジェクトを返します。
{ "items": [ { "contentType": { "recordId": "33B9C302D8264371B6A12EDAF3FD974B", "referenceKey": "FAQ", "name": "FAQ", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/contentTypes/33B9C302D8264371B6A12EDAF3FD974B", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "priority": "PRIORITY_0", "createDate": "2016-09-27T12:23:49-0600", "dateAdded": "2016-09-27T12:23:49-0600", "displayStartDate": "2016-09-27T12:23:22-0600", "displayEndDate": "9999-12-31T00:00:00-0700", "owner": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "lastModifier": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "creator": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "published": true, "publishDate": "2016-09-27T12:23:49-0600", "checkedOut": false, "publishedVersion": "1.0", "recordId": "040036719791200157210710b5007f7a", "versionId": "040036719791200157210710b5007f7b", "documentId": "FAQ1", "title": "test - content", "version": "1.0", "answerId": 1000000, "locale": { "recordId": "en_US", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/locales/en_US", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "dateModified": "2016-10-20T12:37:09-0600", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content/040036719791200157210710b5007f7a", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "collection", "href": "https://<IM_REST_API_HOST>/km/api/latest/content", "mediaType": "application/json, application/xml", "method": "GET", "profile": "https://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/content" } ] }, { "contentType": { "recordId": "33B9C302D8264371B6A12EDAF3FD974B", "referenceKey": "FAQ", "name": "FAQ", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/contentTypes/33B9C302D8264371B6A12EDAF3FD974B", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "priority": "PRIORITY_0", "createDate": "2016-10-18T03:23:28-0600", "dateAdded": "2016-10-18T03:23:30-0600", "displayStartDate": "2016-10-18T03:22:00-0600", "displayEndDate": "9999-12-31T00:00:00-0700", "owner": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "lastModifier": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "creator": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "published": true, "publishDate": "2016-10-18T03:23:30-0600", "checkedOut": false, "publishedVersion": "1.0", "recordId": "040087068a90cb00157d5295740007fdf", "versionId": "040087068a90cb00157d5295740007fde", "documentId": "FAQ10", "title": "How To Maintain Summary Templates", "version": "1.0", "answerId": 1000018, "locale": { "recordId": "en_US", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/locales/en_US", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "dateModified": "2016-10-18T03:23:30-0600", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content/040087068a90cb00157d5295740007fdf", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "collection", "href": "https://<IM_REST_API_HOST>/km/api/latest/content", "mediaType": "application/json, application/xml", "method": "GET", "profile": "https://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/content" } ] }, { , ], "hasMore": true, "limit": 20, "offset": 0, "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content?limit=20&offset=0&orderBy=documentId:case-sensitive", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "next", "href": "https://<IM_REST_API_HOST>/km/api/latest/content?limit=20&offset=20&orderBy=documentId:case-sensitive", "mediaType": "application/json, application/xml", "method": "GET" } ], "count": 2 }GET /content?orderBy=title:case-insensitiveリクエストは、documentIdパラメータ値で大/小文字を区別せずにソートされたコンテンツ・オブジェクトを返します。
{ "items": [ { "contentType": { "recordId": "33B9C302D8264371B6A12EDAF3FD974B", "referenceKey": "FAQ", "name": "FAQ", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/contentTypes/33B9C302D8264371B6A12EDAF3FD974B", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "priority": "PRIORITY_0", "createDate": "2016-10-18T04:01:19-0600", "dateAdded": "2016-10-18T04:01:19-0600", "displayStartDate": "2016-10-18T04:00:00-0600", "displayEndDate": "9999-12-31T00:00:00-0700", "owner": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "lastModifier": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "creator": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "published": true, "publishDate": "2016-10-18T04:01:19-0600", "checkedOut": false, "publishedVersion": "1.0", "recordId": "040087068a90cb00157d5295740007f9a", "versionId": "040087068a90cb00157d5295740007f99", "documentId": "FAQ22", "title": ">How To Compile Invalid Packages", "version": "1.0", "answerId": 1000030, "locale": { "recordId": "en_US", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/locales/en_US", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "dateModified": "2016-10-18T04:01:19-0600", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content/040087068a90cb00157d5295740007f9a", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "collection", "href": "https://<IM_REST_API_HOST>/km/api/latest/content", "mediaType": "application/json, application/xml", "method": "GET", "profile": "https://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/content" } ] }, { "contentType": { "recordId": "BC015169991F49738196682D57E7C5E3", "referenceKey": "SOLUTION", "name": "Solution", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/contentTypes/BC015169991F49738196682D57E7C5E3", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "priority": "PRIORITY_0", "createDate": "2016-10-19T08:30:49-0600", "dateAdded": "2016-10-19T08:30:49-0600", "displayStartDate": "2016-10-19T08:28:39-0600", "displayEndDate": "9999-12-31T00:00:00-0700", "owner": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "lastModifier": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "creator": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "published": true, "publishDate": "2016-10-19T08:30:49-0600", "checkedOut": false, "publishedVersion": "1.0", "recordId": "04008665a7af600157d88f87fa007edc", "versionId": "04008665a7af600157d88f87fa007ed8", "documentId": "SOL79", "title": "1099 Forms Prints Only 33 Characters For Supplier Name", "version": "1.0", "answerId": 1000162, "locale": { "recordId": "en_US", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/locales/en_US", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "dateModified": "2016-10-19T08:30:49-0600", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content/04008665a7af600157d88f87fa007edc", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "collection", "href": "https://<IM_REST_API_HOST>/km/api/latest/content", "mediaType": "application/json, application/xml", "method": "GET", "profile": "https://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/content" } ] }, { "contentType": { "recordId": "BC015169991F49738196682D57E7C5E3", "referenceKey": "SOLUTION", "name": "Solution", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/contentTypes/BC015169991F49738196682D57E7C5E3", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "priority": "PRIORITY_0", "createDate": "2016-10-19T08:27:52-0600", "dateAdded": "2016-10-19T08:27:52-0600", "displayStartDate": "2016-10-19T08:26:43-0600", "displayEndDate": "9999-12-31T00:00:00-0700", "owner": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "lastModifier": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "creator": { "recordId": "040036719791200157210710b5007f80", "name": "NAME_VALUE", "externalType": "ACCOUNT", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/users/040036719791200157210710b5007f80", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "published": true, "publishDate": "2016-10-19T08:27:52-0600", "checkedOut": false, "publishedVersion": "1.0", "recordId": "04008665a7af600157d88f87fa007ee2", "versionId": "04008665a7af600157d88f87fa007ee1", "documentId": "SOL78", "title": "11i - Autoinvoice Fails Validation On A Credit Memo From Project Accounting", "version": "1.0", "answerId": 1000161, "locale": { "recordId": "en_US", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/locales/en_US", "mediaType": "application/json, application/xml", "method": "GET" } ] }, "dateModified": "2016-10-19T08:27:52-0600", "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content/04008665a7af600157d88f87fa007ee2", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "collection", "href": "https://<IM_REST_API_HOST>/km/api/latest/content", "mediaType": "application/json, application/xml", "method": "GET", "profile": "https://<IM_REST_API_HOST>/km/api/latest/metadata-catalog/content" } ] }, ], "hasMore": true, "limit": 20, "offset": 0, "links": [ { "rel": "canonical", "href": "https://<IM_REST_API_HOST>/km/api/latest/content?limit=20&offset=0&orderBy=title:case-insensitive", "mediaType": "application/json, application/xml", "method": "GET" }, { "rel": "next", "href": "https://<IM_REST_API_HOST>/km/api/latest/content?limit=20&offset=20&orderBy=title:case-insensitive", "mediaType": "application/json, application/xml", "method": "GET" } ], "count": 3 }
ソート構文
順序値および大/小文字の区別によるソートをリクエストする場合、常に、大/小文字の区別の前に順序値を指定します。 orderByパラメータに複数のフィールドを指定することで、リソースのコレクションをソートできます。 複数のフィールドが指定されている場合、リソース・コレクションは、フィールドが指定されている順序に従ってソートされます。
リクエストの例
複数のフィールドを含むリストを並べ替えるリクエストの例を次に示します:
GET /content?orderBy=title:desc:case-insensitiveこのリクエストは、タイトルでソートされたコンテンツ・オブジェクトを降順で返します。 タイトルは大文字と小文字を区別せずにソートされます。
GET /content?orderBy=title:case-sensitive,dateAdded:descリクエストは、タイトルでソートされたコンテンツ・オブジェクトを、大文字と小文字の区別が昇順で返します。 第2レベルのソートは、dateAddedパラメータ値の降順で実行されます。
問合せ中
B2B Service REST APIのナレッジは、設定されたリソース・コレクションをフィルタするための問合せサポートを提供します。 リクエストとともにqリクエスト・パラメータを使用して問合せを実行できます。 qリクエスト・パラメータの値には、リクエストでwhere句を実行するためのリソースの問合せパラメータに関連する1つ以上の式が含まれます。 問合せリクエストでは、リソース・コレクションで返されたアイテムのページ区切りおよびソートもサポートされます。 qリクエスト・パラメータのwhere句または値は、問合せと呼ばれます。 ほとんどのリソースはqリクエスト・パラメータをサポートしています。 詳細は、「サポートされている問合せパラメータ」を参照してください。
リクエストの例
次にqリクエストの例を示します。 この例では、問合せはURLエンコードされていません。
GET /content?q=dateAdded after '2015-01-01'&orderBy=dateAdded:desc&limit=10&offset=11リクエストは、2015年1月1日より後に作成された最大10個のコンテンツ・オブジェクトを、問合せに一致する11番目のコンテンツから、最近追加された順にソートして返します。
GET /content?q=title likeAny ('*Oracle Knowledge*') and dateAdded after '2015-01-01'&orderBy=documentIdこのリクエストは、2015年1月1日より後に作成されたOracle Knowledgeというタイトルのコンテンツ・オブジェクトを、文書化されたパラメータ値で昇順にソートして返します。
リクエストの例(URLエンコード)
GET /content?q=dateAdded+after+'2015-01-01'&orderBy=dateAdded:desc&limit=10&offset=11リクエストは、2015年1月1日より後に作成された最大10個のコンテンツ・オブジェクトを、問合せに一致する11番目のコンテンツから、最近追加された順にソートして返します。
GET /content?q=title+likeAny+('*Oracle+Knowledge*')+and+dateAdded+after+'2015-01-01'&orderBy=documentIdリクエストは、2015年1月1日より後に作成された「Oracle Knowledge」というタイトルのコンテンツ・オブジェクトを、documentIdで昇順でソートして返します。