Open Data Protocol (OData)は、HTTPのようなコアプロトコルと、RESTのような一般的に受け入れられているWebの方法論に基づいて構築されたデータアクセスプロトコルです。例えば、JDBC/ODBC接続を作成してSQLコマンドを発行する代わりに、URL経由でHTTP GETでそのテーブルにアクセスすることができます：

SQL statement

OData query

SELECT * FROM SYSADMIN.Roles;;

GET http://localhost:8080/odata4/datavirtuality/SYSADMIN/Roles

ODataを使用する際には、いくつかの重要な注意点があります：

  • SQLとは異なり、URIで使用される名前は大文字と小文字を区別しますので、リソースパスでは正しい大文字（大文字または小文字）を使用してください；
  • OData クエリから返される結果は、Atom/AtomPub XML または JSON 形式です。デフォルトではJSONが使用されます；
  • ビューやテーブルを表示するには、主キーが必要です；
  • ユーザーがOData にアクセスするには、odata-roleを持っている必要があります。

Examples

1.  adminユーザーが表示できる View を作成します：

-- Create a view with primary key
CREATE VIEW views.view1 (a integer, b integer, PRIMARY KEY(a)) AS SELECT 1 a, 2 b;;

ユーザーにはデフォルトでodata-role が割り当てられているため、admin ユーザーの資格情報を使用してhttp://localhost:8080/odata4/datavirtuality/views/view2 リクエストを実行すると、OData 経由でadmin ユーザーがビューviews.view1 を表示できます。

2.  ビューを他のユーザーからも見えるようにします：

-- 1. Create a view with primary key
CREATE VIEW views.view2 (a integer, b integer, PRIMARY KEY(a)) AS SELECT 1 a, 2 b;;
 
-- 2. Create a 'test' user
CALL SYSADMIN.addUser(name => 'test', pwd => 'test', role_name => 'connect-dv-role') ;;
 
-- 3. Assign the odata-role to the user
CALL SYSADMIN.addUserRole(user_name => 'test', role_name => 'odata-role');;
 
-- 4. Create an additional role
CALL SYSADMIN.addRole(name => 'test-role', allowCreateTempTables => true) ;;
 
-- 5. Assign this role to the user
CALL SYSADMIN.addUserRole(user_name => 'test', role_name => 'test-role');;
 
-- 6. Set permission for the view to the user
CALL SYSADMIN.setPermissions(role_name => 'test-role', resourceName => 'views.view2', permissions => 'CRUDEAL') ;;

現在test ユーザーの資格情報を使用してhttp://localhost:8080/odata4/datavirtuality/views/view2 リクエストを実行すると、test ユーザーがOData 経由でviews.view2 を参照できるようになります。

Security and Access

デフォルトでは、OData アクセスはHTTP 基本認証を使用して保護されます。特別なodata-role ロールを持つユーザーだけがアクセスできます。

Query Options

SQLクエリと同様に、ODataクエリもいくつかの方法で拡張することができます。

Filtering Results

OData クエリは、WHERE句がSQL で行うように、クエリ結果をフィルタリングするための特別なクエリオプション$filter をサポートしています：

SQL statement

OData query

SELECT * FROM SYSADMIN.Roles WHERE id = 1 ;;

GET  http://localhost:8080/odata4/datavirtuality/SYSADMIN/Roles?$filter=id  eq 1


Spaces around 'eq' are for readability of the example only; in actual URLs, they must be percent-encoded as %20. OData mandates percent encoding for all spaces in URLs. Please see the URL Conventions section in the OData documentation for more information.

Formatting Results

結果の書式を指定するには、クエリオプション$formatを追加します：

GET http://localhost:8080/odata4/datavirtuality/SYSADMIN/Roles?$format=JSON

システム・クエリ・オプション$formatは ' json ', ' xml ', ' atom ' のいずれかでなければなりません。

Getting More Results

ODataはバッチ処理を利用しているため、一度に256行のデータを取得できます。結果の一番上の行に、次の256行を取得するために使用できる特別な$skiptokenオプションを持つ準備ができたクエリがあります：

GET  http://localhost:8080/odata4/datavirtuality/DV/customers?$skiptoken=xxx

Combining Query Options

クエリオプションは、この例のように一緒に使用することができます：

GET http://localhost:8080/odata4/datavirtuality/SYSADMIN/Roles?$filter=id eq 1&$format=XML

Querying Navigations

ODataは、あるエンティティから別のエンティティへのナビゲーションのクエリもサポートしています。ナビゲーションは、リレーショナルデータベースの外部キー関係に似ています：

SQL statement

OData query

SELECT CountryRegion.* FROM mysql_adventureworks.Address
   JOIN mysql_adventureworks.CountryRegion
   ON Address.CountryRegionCode = CountryRegion.CountryRegionCode
   WHERE Address.AddressID = 1 ;;

GET  http://localhost:8080/odata4/datavirtuality/mysql_adventureworks/address(1)/FK_CountryRegion_Address

Please note that at the moment, query navigation is not supported for virtual views - only for data source tables with foreign keys assigned directly in the source. Such keys should be imported by enabling the importer.importKeys model property on data source creation.

OData Metadata

ODataは、概念スキーマ定義言語（CSDL）を使用してスキーマを定義します：

http://localhost:8080/odata4/datavirtuality/DV/$metadata

OData スキーマモデルはリレーショナルスキーマモデルではないため、CData Virtuality Server は以下のセマンティクスを使用してリレーショナルスキーマモデルを OData スキーマモデルにマッピングします：

Relational entity

Mapped OData entity

Model name

Schema namespace, EntityContainer name

Table/View

EntityType, EntitySet

Table columns

EntityType's properties

Primary key

EntityType's key properties

Foreign key

Navigation property on EntityType

Procedure

FunctionImport, ActionImport

Procedure's table return

ComplexType

設計上、CData Virtuality Server はEntityTypeに「埋め込まれた」ComplexTypeを定義しません。

Datatype Mapping

Data type

OData type

STRING

Edm.String

BOOLEAN

Edm.Boolean

BYTE

Edm.SByte

SHORT

Edm.Int16

INTEGER

Edm.Int32

LONG

Edm.Int64

FLOAT

Edm.Single

DOUBLE

Edm.Double

BIG_INTEGER

Edm.Decimal

BIG_DECIMAL

Edm.Decimal

DATE

Edm.Date

TIME

Edm.TimeOfDay

TIMESTAMP

Edm.DateTimeOffset

BLOB

Edm.Stream

CLOB

Edm.Stream

XML

Edm.Stream

VARBINARY

Edm.Binary

Errors and Solutions

"Cannot find EntitySet"

{"error":{"code":null,"message":"Cannot find EntitySet, Singleton, ActionImport or FunctionImport with name 'xxx'."}}

以下のいずれかの原因が考えられます：

  • モデル名 / テーブル名の組み合わせが間違っています - スペルと大文字・小文字を確認してください；
  • テーブルがPRIMARY KEYまたはUNIQUE KEY (s) を持っていない場合など、実体はメタデータの一部ではありません。

"Illegal character in path at index XXX"

{"error":{"code":null,"message": "java.net.URISyntaxException: Illegal character in path at index XXX: URL/odata_error_ ('error code')/Property Reference"}}

OData ク エ リ を発行 し て こ のエ ラ ーが発生 し た場合は、 プ ロ パテ ィ 名を再確認 し て く だ さ い ：OData specificationに従えば、 プ ロ パテ ィ 名に空白を含む こ と はで き ません。

Executing Stored Procedures

Functions and Actions

エンティティとそのプロパティのマッピングは比較的簡単です。CData Virtuality Server プロシージャとOData 関数およびアクションのマッピングはより複雑です。OData には out パラメータの概念がないため、OUTパラメータは無視され、INOUTパラメータはINとしてのみ扱われます。結果セットは、複合型のコレクション結果にマッピングされます。

OData関数は、以下の場合に使用されます：

  • プロシージャ / 関数には戻り値があり、スカラーか結果セットのどちらかです；

  • 現在、Clob、Blob、XML がLOB 型とみなされています；

  • プロシージャ / 関数は副作用がありません。これは、更新カウントの明示的な値0によって決定されます。例えばCREATE VIRTUAL PROCEDURE …​ OPTIONS (UPDATECOUNT 0) AS BEGIN …​

これらの条件のいずれかが満たされない場合、プロシージャ / 関数は、代わりにOData アクションによって表されます。しかし、結果セットにLOB 値がある場合、複数のストリーミング値を返すことができないため、プロシージャはマッピングされません。

OData の関数とアクションは、異なる方法で呼び出されることに注意してください：

  • 関数は、GET リクエストによって呼び出され、パラメータ値がURI に含まれます；
  • アクションは、POSTリクエストによって呼び出され、コンテンツがパラメータ値を提供します。

現在のところ、未束縛の関数とアクションのみがサポートされています。

プロシージャ / 関数がどのようにマッピングされているかを確認するために、関数とアクションの$metadataを常にチェックすることをお勧めします。

Executing Functions

SQL statement

OData query

SELECT * FROM (EXEC "SYSADMIN.getTypeOfResource"("name" => 'SYSADMIN.Roles')) AS alias ;;

GET http://localhost:8080/odata4/datavirtuality/SYSADMIN/getTypeOfResource(name='SYSADMIN.Roles')

Executing Actions

SQL statement

OData query

CALL "SYSADMIN.setCurrentDWH"(nameInDv => 'mysql_adventueworks', nameInSource => 'adventueworks') ;;

POST http://localhost:8080/odata4/datavirtuality/SYSADMIN/setCurrentDWH
Host: host
Content-Type: application/json
Accept: application/json
{
    "nameInDv" : "mysql_adventueworks",
    "nameInSource" : "adventueworks"

}

Updating Data

OData プロトコルは、CREATE / UPDATE / DELETEオペレーショ ンに加え、READオペレーショ ンをサポー トしています。これらの操作は、異なるHTTPメソッドを使用します。

INSERT は、HTTPメソッドPOSTで実現されます：

POST /service.svc/Customers HTTP/1.1
Host: host
Content-Type: application/json
Accept: application/json
{
"CustomerID": "AS123X",
"CompanyName": "Contoso Widgets",
"Address" : "Seattle, 58 Contoso St"
}


UPDATEは、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" : "Seattle, Updated street"
}

DELETE操作は、HTTPメソッドDELETEを使用します：

DELETE /service.svc/Customers('ALFKI') HTTP/1.1
Host: host
Content-Type: application/json
Accept: application/json

OData as a Data Source

ODataをデータソースとして接続することができます。詳細については、Reference Guideのdedicated pageを参照してください。

Limitations

現時点では、ODataの実装は以下をサポートしていません：

  • 検索

  • デルタ処理

  • SPECのデータ集約拡張

  • SQL の類語CREATE (テーブル、ビュー、プロシージャ)、ALTER (ビュー、プロシージャ)、DROP / DROP IF EXISTS (テーブル、ビュー、プロシージャ)、 SELECT INTO クエリ
  • 複数の仮想データベース ( datavirtuality"システム VDB のみ使用可能)
  • itの使用は、プリミティブ・コレクション・プロパティのみに限定されます。