Ce contenu n'est pas disponible dans la langue sélectionnée.
8.2. OData Version 4.0 Support
Red Hat JBoss Data Virtualization strives to be compliant with the OData specification.
For example, if you have deployed a VDB named northwind that has a customers table in a NW model, then you can access that table with an HTTP GET via this URL: http://localhost:8080/odata4/northwind/NW/customers. This is akin to making a JDBC/ODBC connection and issuing this SQL:
SELECT * FROM NW.customers
Note
Use correct case (upper or lower) in the resource path. Unlike SQL, the names used in the URI as case-sensitive.
Note
The returned results from the OData query are output in either Atom/AtomPub XML or JSON format. JSON results are returned by default.
You can submit predicates with your query to filter the results: http://localhost:8080/odata4/northwind/NW/customers?$filter=name eq 'bob'
Note
The spaces around 'eq' are for readability of the example only; in real URLs they must be percent-encoded as %20. OData mandates percent encoding for all spaces in URLs. http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html
This is similar to making a JDBC/ODBC connection and issuing the SQL
SELECT * FROM NW.customers where name = 'bob'
To request the result to be formatted in a specific format, add the query option $format like this: http://localhost:8080/odata4/northwind/NW/customers?$format=JSON
Query options can be combined as needed. For example here is how you format with a filter:
http://localhost:8080/odata4/northwind/NW/customers?$filter=name eq 'bob'&$format=xml
OData allows for querying navigations from one entity to another. A navigation is similar to the foreign key relationships in relational databases.
For example, if the customers table has an exported key to the orders table on the customers primary key called the customer_fk, then an OData GET could be issued like this: http://localhost:8080/odata4/northwind/NW/customers(1234)/customer_fk?$filter=orderdate gt 2012-12-31T21:23:38Z
This would be akin to making a JDBC/ODBC connection and issuing this SQL:
SELECT o.* FROM NW.orders o join NW.customers c on o.customer_id = c.id where c.id=1234 and o.orderdate > {ts '2012-12-31 21:23:38'}
Note
For detailed protocol access you can read the specification at http://odata.org. You can also read this very useful web resource for an example of accessing an OData server.
Important
If you are not seeing all the rows, see the configuration section below for more details. Generally batching is being utilized, which tooling should understand automatically, and additional queries with a $skiptoken query option specified are needed: http://localhost:8080/odata4/northwind/NW/customers?$skiptoken=xxx
Important
Sometimes you may encounter an "EntitySet Not Found" error. This happens when you issue the above query and you see a message like this:
{"error":{"code":null,"message":"Cannot find EntitySet, Singleton, ActionImport or FunctionImport with name 'xxx'."}}
This message means that either you supplied an incorrect model-name/table-name combination. Check that the spelling and case are correct.
It is possible that the entity is not part of the metadata, such as when a table does not have any PRIMARY KEY or UNIQUE KEY(s).
It is possible to update your data. Using the OData protocol it is possible to perform CREATE/UPDATE/DELETE operations along with the READ operations shown above. These operations use different HTTP methods.
INSERT/CREATE is accomplished through the "POST" HTTP method. Here is an example:
POST /service.svc/Customers HTTP/1.1
Host: host
Content-Type: application/json
Accept: application/json
{
"CustomerID": "AS123X",
"CompanyName": "Contoso Widgets",
"Address" : {
"Street": "58 Contoso St",
"City": "Seattle"
}
}
An UPDATE is performed with an HTTP "PUT":
PUT /service.svc/Customers('ALFKI') HTTP/1.1
Host: host
Content-Type: application/josn
Accept: application/json
{
"CustomerID": "AS123X",
"CompanyName": "Updated Company Name",
"Address" : {
"Street": "Updated Street"
}
}
The DELETE operation uses the HTTP "DELETE" method.
DELETE /service.svc/Customers('ALFKI') HTTP/1.1
Host: host
Content-Type: application/json
Accept: application/json
8.2.1. Security
By default OData access is secured using HTTPBasic authentication. The user will be authenticated against Red Hat JBoss Data Virtualization’s default security domain "teiid-security".
Important
Users are expected to have the odata role. Be sure to create user with this role when you are using
add-user.sh script to create a new user.
However, if you wish to change the security domain use a deployment-overlay to override the
web.xml file in the odata4 file in the EAP_HOME/modules/org/jboss/teiid/main/deployments directory.
The OData WAR can also support Kerberos, SAML and OAuth2 authentications. To learn about these, please see the Security Guide.
8.2.2. Configuration
The OData WAR file can be configured by configuring the following properties in the web.xml file:
| Property Name | Description | Default Value |
|---|---|---|
| batch-size | Number of rows to send back each time, -1 returns all rows | 256 |
| skiptoken-cache-time | Time interval between the results being recycled/expired between $skiptoken requests | 300000 |
| local-transport-name | Data Virtualization Local transport name for connection | odata |
| invalid-xml10-character-replacement | Replacement string if an invalid XML 1.0 character appears in the data - note that this replacement will occur even if JSON is requested. No value (the default) means that an exception will be thrown with XML results if such a character is encountered. | NA |
| proxy-base-uri | Defines the proxy server’s URI to be used in OData responses. | NA |
| connection.XXX | Sets XXX as an execution property on the local connection. Can be used for example to enable result set cache mode. | NA |
Note
If the Data Virtualization server is configured behind a proxy server or deployed in cloud environment, or using a load-balancer then the URI of the server which is handling the OData request is different from URI of proxy. To generate valid links in the OData responses, configure "proxy-base-uri" property in the web.xml. If this value is available as system property then define the property value as per the below.
<init-param>
<param-name>proxy-base-uri</param-name>
<param-value>${system-property-name}</param-value>
</init-param>
To modify the web.xml file, create a deployment-overlay using the CLI with the modified contents:
deployment-overlay add --name=myOverlay --content=/WEB-INF/web.xml=/modified/web.xml --deployments=teiid-odata-odata4.war --redeploy-affected
The Red Hat JBoss Data Virtualization OData server implements cursoring logic when the result rows exceed the configured batch size. On every request, only batch-size number of rows are returned. Each such request is considered an active cursor, with a specified amount of idle time specified by skip-token-cache-time. After the cursor is timed out, the cursor will be closed and remaining results will be cleaned up, and will no longer be available for further queries. Since there is no session based tracking of these cursors, if the request for skiptoken comes after the expired time, the original query will be executed again and tries to re-position the cursor to relative absolute potion, however the results are not guaranteed to be same as the underlying sources may have been updated with new information meanwhile.
Important
The following feature limitations apply:
- Delta processing is not supported.
- The data-aggregation extension to the specification is not supported.
8.2.3. Client Tools for Access
There are different tools you can use. Depending upon your programming model and needs there are various ways you write your access layer into OData. Here are some suggestions:
- Your Browser: The OData Explorer is an online tool for browsing an OData data service.
- Olingo: Is a Java framework that supports OData V4, has both consumer and producer framework.
- Microsoft has various .Net based libraries. See http://odata.github.io/
- Windows Desktop: LINQPad is a wonderful tool for building OData queries interactively. See https://www.linqpad.net/
- Shell Scripts: use the CURL tool
8.2.4. OData Metadata
OData defines its schema using Conceptual Schema Definition Language (CSDL). Every VDB,that is deployed in an ACTIVE state on the Data Virtualzation server exposes its metadata in CSDL format. For example if you want retrieve metadata for your vdb northwind, you need to issue a query like this: http://localhost:8080/odata4/northwind/NW/$metadata
Since OData schema model is not a relational schema model, Red Hat JBoss Data Virtualization uses the following semantics to map its relational schema model to OData schema model.
| Relational Entity | Mapped OData Entity |
|---|---|
| Table/View | EntityType, EntitySet |
| Table Columns | EntityType’s Properties |
| Primary Key | EntityType’s Key Properties |
| Foreign Key | Navigation Property on EntityType |
| Procedure | FunctionImport, Action Import |
| Procedure's Table Return | ComplexType |
By design, Red Hat JBoss Data Virtualization does not define any "embedded" ComplexType in the EntityType.
Since OData access is more key based, it is mandatory that every table Red Hat JBoss Data Virtualization exposes through OData has a primary key or at least one unique key. A table which does not have either of these will be dropped out of the $metadata.
