API Driver のAPI Profile を新規作成する

RESTful APIs は、外部データや社内データに直観的で安定したアクセスを実現します。2019年6月までにパブリックAPI の数は22,000 を超え、さらにその数は増加を続けています。増加し続けるAPI に対しCData api Driver は、シンプルかつ拡張性の高い標準アクセスを実現します。

API Driver をなぜ使うの？

CData API Driver は、CData Drivers と同様に、データ連携を標準化することで簡単にすることを目指して作られた製品です。API Driver と公開されているAPI Profile を使うことで、多くのAPI とBI、データ連携ツール、カスタムアプリケーションをノーコードで連携させることができます。エンタープライズおよび開発者は、API Profile をカスタマイズしたり、新しいAPI Profile を作成することが可能であり、あらゆるRESTful API （CData API Server で作成したAPI を含みます) への連携をおどろくほど簡単にできます。

この記事では、API Driver で新しいAPI に接続するためのAPI Profile の新規作成の方法をを説明します。

API Profile の作成

API Profiles は、ターゲットとなるAPI へのSQL アクセスを実現します。すでに多くのAPI に対応するAPI Profiles が用意されていますが、ユーザーがアクセスしたAPI がカバーされていない場合もあります。その場合、ユーザーは新しくAPI Profile を開発することが可能です。

Schema File (.rsd) の作成

API Profiles は、API に対応するスキーマファイル群でできています。この記事では、TripPin OData v4 API を例に、People エンドポイントへのスキーマファイルを作成します。

api:info: このキーワードは、スクリプトされたカラム定義を通じてAPI フィールドをテーブルカラムにマップします。
attr: この項目は、カラム定義を表します（詳細は下を参照）
api:set attr="...": この項目は、API 連携の各種のパラメータを設定しています。ページング機能やAPI レスポンスのパース方法などを含みます。
api:script method="...": この項目は、API エンドポイントに対するRead/Write 機能がどう実装されているかを示します。どの内部処理が呼ばれ、フィルタリングなどの特定の機能が管理されるかを含みます。

People.rsd というテキストファイルをつくります。ここからスキーマファイルのセクションごとに基となるAPI 定義に対応するスキーマをつくります。

カラム定義の作成

API Driver schema files enable SQL access to API endpoints, and this starts with creating column definitions for corresponding API fields for the given endpoint, using API Script keywords and other functionality. An api:script keyword contains the entire schema definition. An api:info keyword provides the table name & description and contains the column definitions, where each API field is mapped to a table with an attr (attribute) element.

The People endpoint of our API returns a series of people, where each entry is represent by a JSON object similar to the following:

{
"UserName" : "russellwhyte",
"FirstName" : "Russell",
"LastName" : "Whyte",
"MiddleName" : null,
"Gender" : "Male",
"Age" : null,
"Emails" : ["Russell@example.com","Russell@contoso.com"],
"FavoriteFeature" : "Feature1",
"Features" : ["Feature1","Feature2"],
"AddressInfo" : [
  { "Address" : "187 Suffolk Ln.",
  "City":{
    "Name" : "Boise",
    "CountryRegion" : "United States",
    "Region" : "ID"
  }
}],
"HomeAddress" : null}

We can using path definitions based on the JSON structure to drill down into each of the values in the response, effectively flattening the response into a SQL table model. Create the column definitions based on the API specification and inferred information based on the response. An explanation of the column definition follows.


<api:script xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:api="http://apiscript.com/ns?v1" >
  
  
    
    <attr name="UserName" key="true" xs:type="string" readonly="true" other:xPath="UserName" />
    <attr name="FirstName"           xs:type="string" readonly="true" other:xPath="FirstName" />
    <attr name="LastName"            xs:type="string" readonly="true" other:xPath="LastName" />
    <attr name="MiddleName"          xs:type="string" readonly="true" other:xPath="MiddleName" />
    <attr name="Gender"              xs:type="string" readonly="true" other:xPath="Gender" />
    <attr name="Age"                 xs:type="int"    readonly="true" other:xPath="Age" />
    <attr name="Emails"              xs:type="string" readonly="true" other:xPath="Emails" />
    <attr name="FavoriteFeature"     xs:type="string" readonly="true" other:xPath="FavoriteFeature" />
    <attr name="Feature1"            xs:type="string" readonly="true" other:xPath="Features[0]" />
    <attr name="Feature2"            xs:type="string" readonly="true" other:xPath="Features[1]" />
    <attr name="Address"             xs:type="string" readonly="true" other:xPath="AddressInfo/Address" />
    <attr name="City"                xs:type="string" readonly="true" other:xPath="AddressInfo/City/Name" />
    <attr name="CountryRegion"       xs:type="string" readonly="true" other:xPath="AddressInfo/City/CountryRegion"/>
    <attr name="Region"              xs:type="string" readonly="true" other:xPath="AddressInfo/City/Region" />
  
...

カラム定義アトリビュート

name: The name of the column in the SQL interface for the API endpoint
xs:type: The data type associated with the column (e.g.: string, datetime, int, etc.)
readonly: Whether the column allows writes (by default, this is always true)
key: Whether a column is intended to be a unique identifier for the elements in a table/view
other:xPath: The path (exact or relative to theRepeatElement) in the API response to the column value

特定のカラム

Here, we examine specific column definitions and explain how the different attributes create the SQL mapping for the API fields.

Column	Featured Attribute	Meaning
UserName	key	Signifies UserName as a unique identifier for the table
ALL	readonly	Determines whether a column can be modified or not
ALL	xs:type	Sets the SQL datatype (based on API specification or data model)
Feature1	other:xPath	The array index [0] indicates to pull the first entry in the Features JSON array
City	other:xPath	Drills into the AddressInfo JSON object to expose the city name

グローバルパラメータの追加

After creating the column definitions, we need to set the global parameters for integrating with the API, including the API endpoint to request data from, any required values for connecting, specific fields or headers for the API request, and the repeated element in the API response that represents individual entries for the API endpoint.

...
  
  <api:set attr="ContentType" value="application/json" />
  <api:set attr="EnablePaging" value="true" />
  <api:set attr="RepeatElement" value="/value" />
  <api:set attr="pagenumberparam" value="page_number" />
  <api:set attr="pagesize" value="300" />
  <api:set attr="pagesizeparam" value="page_size" />
  <api:set attr="uri" value="https://services.odata.org/TripPinRESTierService/People" />
...

Read/Write 機能の追加

With the columns and global parameters defined, we can complete the schema file by scripting the read and write functionality. SELECT functionality is implemented in the <api:script method="GET"> keyword, setting the HTTP method to GET and calling the apisadoExecuteJSONGet operation to retrieve and process the data.

  
    <api:set attr="method" value="GET" />
    
      <api:push/>

To implement INSERT / UPDATE / DELETE functionality, we need to add additional <api:script> elements with the POST, MERGE, and DELETE methods and implement the specific functionality with further scripting. For this article, we will only implement SELECT functionality and throw an error message if we try to write to the API endpoint.

Setting the method Attribute

With the API functionality implemented, we can use the profile with the API Driver in any tool or application that supports JDBC or ADO.NET connectivity, granting SQL access to the API.

DbVisualizer でProfile を使う

API Driver は、普通のデータベースドライバーと同じように、コネクションプロパティを使ってデータへの接続を行います。API Driver では、二つの重要なコネクションプロパティがあります：

Profile: 拡張子が.apip となっているファイルで接続するデータソース向けののもの
ProfileSettings: 選択したProfile で必要なname-value ペアでセミコロン区切りのもの

DbVisualizer では、JDBC を使うので、JDBC の接続文字列を使います:

jdbc:apis:Profile=/PATH/TO/TripPin/;

DbVisualizer で、新しい接続をAPI Driver に対して作成し、接続文字列をデータベースURL に入力します。このように新しいProfile に接続することができます。あとは、DB のようにSQL を発行するとAPI を呼び出すことができます。

TripPin People Data as a Database via API Driver

詳細情報および無償評価版

これでAPI Driver を使ってAPI にアクセスする方法がわかりましたね。製品詳細はAPI Driver 製品ページを参照するか、API Profile の編集や設定のKB 記事(API Driver Profiles を使ってみる and API Driver Profile をカスタマイズする)を見てください。API Driver は30日の無償版を利用可能です。是非、お試しください。

ソリューション

開催予定のイベント

サポート

ブログへ →