OData Javascript Library
Lightweight OData Client for OData (v2) Service.
Installation
npm i -S c4codata
Alternative, in build-tool-less environment, just add unpkg umd link to your page, and OData
object will be available in window
.
Table of Contents
- Installation
- Table of Contents
- OData Version 2 concepts
- OData Client
- ODataParam
- ODataFilter
- Batch requests
- Generator usage
- Others
- CHANGELOG
- LICENSE
OData Version 2 concepts
From OData.org
If you are already familiar with OData, please skip this section
URI Format
A URI used by an OData service has up to three significant parts: the service root URI, resource path and query string options. Additional URI constructs (such as a fragment) MAY be present in a URI used by an OData service; however, this specification applies no further meaning to such additional constructs.
Pagination
A data service URI with a $skip System Query Option identifies a subset of the Entries in the Collection of Entries identified by the Resource Path section of the URI. That subset is defined by seeking N Entries into the Collection and selecting only the remaining Entries (starting with Entry N+1). N is an integer greater than or equal to zero specified by this query option. If a value less than zero is specified, the URI should be considered malformed.
https://services.odata.org/OData/OData.svc/Products?$skip=2&$top=2&$orderby=Rating
The third and fourth Product Entry from the collection of all products when the collection is sorted by Rating (ascending).
Filter
A URI with a
$filter
System Query Option identifies a subset of the Entries from the Collection of Entries identified by the Resource Path section of the URI. The subset is determined by selecting only the Entries that satisfy the predicate expression specified by the query option.
Operator | Description | Example |
---|---|---|
Eq | Equal | /Suppliers?$filter=Address/City eq 'Redmond' |
Ne | Not equal | /Suppliers?$filter=Address/City ne 'London' |
Gt | Greater than | /Products?$filter=Price gt 20 |
Ge | Greater than or equal | /Products?$filter=Price ge 10 |
Lt | Less than | /Products?$filter=Price lt 20 |
Le | Less than or equal | /Products?$filter=Price le 100 |
And | Logical and | /Products?$filter=Price le 200 and Price gt 3.5 |
Or | Logical or | /Products?$filter=Price le 3.5 or Price gt 200 |
OData Client
Start with a simple query, following code start a GET
http request, and asks the server to respond to all customers which phone number equals 030-0074321
// odata.org sample odata serviceconst TestServiceURL = "https://services.odata.org/V2/Northwind/Northwind.svc/$metadata"const odata = TestServiceURL // Query by filter//// GET /V2/Northwind/Northwind.svc/Customers?$format=json&$filter=Phone eq '030-0074321'const filter = OData; const result = await odata
ODataRequest interface
ODataResponse interface
ODataParam
use ODataParam
to control data size, involved fields and order
pagination
skip
first 30 records and top
10 records
// equal to $format=json&$skip=30&$top=10ODatatop10
filter
filter data by fields value
// $format=json&$filter=A eq 'test'OData
inline count
response with all records count, usefully.
also could set with filter
, and response with filtered records count.
// equal to $format=json&$inlinecount=allpagesODatatop1
orderby
sort response data
// result is $format=json&$orderby=CreationDateTime descOData // result is $format=json&$orderby=A desc,B ascOData
navigation property
expand association data
// $expand=CustomersOData// $expand=Customers,EmployeesOData
fields select
remove unused fields from response
// $format=json&$select=ObjectID,NameOData;
full text search (basic query)
search all supported fields with text
SAP systems feature
LOW PERFORMANCE
// fuzzy// $format=json&$search=%any word%OData;// not fuzzy// $format=json&$search=any wordOData;
ODataFilter
Use the ODataFilter
to filter data
Most SAP
systems only support AND
operator between different fields, and OR
operator in a same field. (it depends on SAP Netweaver implementation)
So you don't need to specify AND/OR
operator between fields, c4codata
will auto process it.
Though C4C only support AND operator in different fields, but for gt/lt/ge/le
, you can use AND for filtering period data.
just ref following examples
filter by single field value
// Name eq 'test string'OData // ID lt '1024'OData // also support eq/ne/le/lt/gt/ge ...
filter by multi fields
// Name eq 'test string1' and Name2 eq 'test string2'OData
filter by one field but multi values
// Name eq 'test string1' and (Name2 eq 'test string1' or Name2 eq 'test string2')OData
filter by date
Depends on field type, use betweenDateTime
or betweenDateTimeOffset
to filter date。
Please provide Date
object in this api.
// Name eq 'test string1' and (CreationDateTime gt datetime'2018-01-24T12:43:31.839Z' and CreationDateTime lt datetime'2018-05-24T12:43:31.839Z')OData // > include boundary value // (CreationDateTime ge datetime'2018-01-24T12:43:31.839Z' and CreationDateTime le datetime'2018-05-24T12:43:31.839Z')OData
Batch requests
use odata $batch
api for operating multi entities in single HTTP request, it will save a lot of time between client & server (In the case of processing a large number of requests).
const odata = ODataconst testDesc1 = ; // a generated uuidconst testDesc2 = ; // execute reqeusts and return mocked responsesconst result = await odata result // Created
Generator usage
This library provide a JS generator, provide ES6 static function declaration, but I dont want to write too much about this.
If you really need that, just contact me.
install it global firstly
npm i -g c4codata # type defination generator
c4codata includes a type defination generator to help developer invoke odata api.
Usage: odata-js-generator [OPTIONS] [ARGS] Options: -m, --uri STRING metadata uri -u, --user STRING c4c username -p, --pass STRING c4c password -o, --out [STRING] out file -d, --debug BOOLEAN debug mode -s, --separate STRING out with separate files in directory -r, --odatajs BOOLEAN seperate generator without odata.js -h, --help Display help and usage details
sample command (generate single js file)
use following command to generate declaration
odata-js-generator -m "https://host/sap/c4c/odata/v1/c4codata/$metadata?sap-label=true" -u c4c-username -p c4c-password
then, you could use the c4codata.js to operation OData
some SAP OData implementations have some different param in url, like sap-label
, it will response the label value in the UI interface.
Others
Use markdown-toc to generate table of contents, with following commands:
markdown-toc --replace --inline --header "## Table of Contents" --skip-headers=1 README.md
CHANGELOG
LICENSE
MIT License
Copyright (c) 2018 Theo Sun
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.