API Driver の事前定義API Profiles をカスタマイズする

企業で利用されるAPI の数は増加の一途をたどっています。ロングテールに増加するAPI に対してデータ連携を容易にする製品がCData API Driver です。

API Drver とは

CData API Driver CData Drivers と同様にAPI に対して標準SQL クエリでのアクセスを提供します。API Driver は汎用API に対して利用可能で、スキーマ定義ファイルであるAPI Profile を差し替えることで複数のAPI に対して標準SQL でのクエリを実現します。また、CData API Server で作成したAPI にも使うことができます。API Driver は、Bi、ETL、カスタムアプリケーションから利用することで、API とツール・アプリとのラスト1マイルをつなぎます。

この記事では、API Profile をカスタマイズして機能を追加する方法を説明します。

API Profile をカスタマイズする

提供されているAPI Profile は、デフォルトでターゲットAPI へのRead 機能が実装されています。ユーザーはAPI Profile をカスタマイズすることで、例えばWrite 機能を追加することが（基となるAPI で許容されている前提で）可能です。

既存のProfile をUnzip する

API Profiles (拡張子が.apip のファイル) は、ターゲットとなるAPI へのスキーマファイル群を圧縮したファイルです。このファイルを解凍してファイルをカスタマイズすることで、ドライバーの機能を拡張することが可能です。

スキーマファイルを開く

Profile を解凍したら、カスタマイズを行うAPI エンドポイントのスキーマファイルをテキストエディタで開きます。それぞれのスキーマファイルはAPI エンドポイントへのSQL アクセスを可能にする定義が記載されています。

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

以下は、Zoom API Profile のMeetings スキーマの内容です。

Meetings.rsd


  
    <attr name="Id"         xs:type="string"   readonly="true" key="true"   other:xPath="id"         />
    <attr name="CreatedAt"  xs:type="datetime" readonly="true"              other:xPath="created_at" />
    <attr name="Duration"   xs:type="int"      readonly="true"              other:xPath="duration"   />
    <attr name="HostId"     xs:type="string"   readonly="true"              other:xPath="host_id"    />
    <attr name="JoinUrl"    xs:type="string"   readonly="true"              other:xPath="join_url"   />
    <attr name="StartTime"  xs:type="datetime" readonly="true"              other:xPath="start_time" />
    <attr name="Timezone"   xs:type="string"   readonly="true"              other:xPath="timezone"   />
    <attr name="Topic"      xs:type="string"   readonly="true"              other:xPath="topic"      />
    <attr name="Type"       xs:type="int"      readonly="true"              other:xPath="type" desc="1 - Instant. 2 - Scheduled. 3 - Recurring with no fixed time. 8 - Recurring with fixed time"      />
    <attr name="Uuid"       xs:type="string"   readonly="true"              other:xPath="uuid"       />
    <attr name="UserId"     xs:type="string"   desc="Required. Must be set to a user's Id or email address. All meetings retrieved will be for that user." other:pseudocolumn="true" />
    
    <input  name="MeetingType"     xs:type="string"   desc="Filters on meetings with the given type. Allowed values are scheduled, live, and upcoming. Default is live." values="live,scheduled,upcoming" default="active" other:filter="type" />
    <input  name="rows@next" desc="Identifier for the next page of results. Do not set this value manually." />
  
  
  
  <api:set attr="ContentType" value="application/json" />
  <api:set attr="RepeatElement" value="/" />
  <api:set attr="EnablePaging" value="true" />
  <api:set attr="RepeatElement" value="/meetings" />
  <api:set attr="pagenumberparam" value="page_number" />
  <api:set attr="pagesize" value="300" />
  <api:set attr="pagesizeparam" value="page_size" />
  <api:validate attr="_input.UserId" desc="You must specify a user Id when using the Meetings table." />
  <api:set attr="uri" value="https://api.zoom.us/v2/users/[_input.UserId | urlencode()]/meetings" />
  
  
    <api:set attr="method" value="GET" />
    
      <api:push/>
    
  
  
  
  
    <api:throw code="500" desc="Inserts are not supported." />
  
  
    <api:throw code="500" desc="Updates are not supported." />
  
  
    <api:throw code="500" desc="Deletes are not supported." />

カラム定義のカスタマイズ

例えば、ユーザーがWrite 機能を実装したい場合には、スキーマを変更して対応するカラムへのWrite 処理の許可を与えます。Profile のカラム定義を編集する前に、ある一つのカラム定義をよくみて、異なるアトリビュートについて考えてみましょう。

Id Column Definition

    <attr name="Id"         xs:type="string"   readonly="true" key="true"   other:xPath="id"         />

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

name: API エンドポイントに対するSQL インターフェースでのカラム名
xs:type: カラムのデータ型（string、datetime、int など）
readonly: カラムがReadonly か書き込みを許容するか（デフォルトではTRUE）
key: テーブル/ビューにおいてそのカラムが一意の識別子とされているか
other:xPath: カラム値に対するAPI レスポンスでRepeatElement と同じもしくは関連するpath

見てわかるように、多くのカラム（それぞれAPI フィールドに相当する）は、Readonly に設定されています。API Driver がWrite 処理を行うことを許容するには、まずはReadonly フラグを外すことが必要です：

...
    <attr name="Id"         xs:type="string"   readonly="true" key="true"   other:xPath="id"         />
    <attr name="CreatedAt"  xs:type="datetime" readonly="true"              other:xPath="created_at" />
    <attr name="Duration"   xs:type="int"                                   other:xPath="duration"   />
    <attr name="HostId"     xs:type="string"   readonly="true"              other:xPath="host_id"    />
    <attr name="JoinUrl"    xs:type="string"   readonly="true"              other:xPath="join_url"   />
    <attr name="StartTime"  xs:type="datetime"                              other:xPath="start_time" />
    <attr name="Timezone"   xs:type="string"                                other:xPath="timezone"   />
    <attr name="Topic"      xs:type="string"                                other:xPath="topic"      />
    <attr name="Type"       xs:type="int"                                   other:xPath="type" desc="1 - Instant. 2 - Scheduled. 3 - Recurring with no fixed time. 8 - Recurring with fixed time"      />
    <attr name="Uuid"       xs:type="string"   readonly="true"              other:xPath="uuid"       />
...

INSERT 機能を追加

つぎに、INSERT 構文をサポートするための編集を行います：

INSERT INTO Meetings 
  (Topic,Type,StartTime,Duration,TimeZone,UserId) 
VALUES 
  ('Test Meeting',2,'2019-12-31T00:00:00',60,'EST','user@domain.com')

注意 : Topic、Type、StartTime、Duration、TimeZone は、このスキーマのカラムですUserId attr は、擬似カラムで、テーブルのカラムのように動作しますが、実際にはテーブルには保持されていません。この場合、UserId は特定のユーザーアカウントに新しいミーティングをPOST するために使われます。

このスキーマファイルでは、 <api:script method="POST">エレメントにおいて、SELECT 機能がすでに実装されています。

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

INSERT 機能の実装には、<api:script method="POST"> エレメントを編集して、"POST" にmethod attribute value を設定し、インプット値にdata アトリビュートを設定し、適切なオペレーション(この場合、apisadoExecuteJSONGet)を呼び出します。

method アトリビュートの設定

  
    <api:set attr="method" value="POST" />

data アトリビュートの設定

Zoom Meetings API エンドポイントは、ミーティングに関するフィールドを含むJSON オブジェクトを投げることで、新しいミーティングを作成できます。INSERT 構文の値は、_input オブジェクトのフィールドにマッピングされ、data アトリビュートが作成され、Zoom API にPOST されます。


{
  "topic": "[_input.Topic]",
  "type": [_input.Type],
  "start_time": "[_input.StartTime]",
  "duration": "[_input.Duration]",
  "timezone": "[_input.TimeZone]"
}

Calling the apisadoExecuteJSONGet Operation

Once the data attribute is set, call the apisadoExecuteJSONGet operation using an api:call keyword and push the operation to the API Driver with an api:push keyword.

...

カスタマイズされたProfile を使う

スキーマファイルへの編集を行ったら、Zoom アカウントへのミーティングのINSERT を実行してみましょう。スキーマファイルを保存して、圧縮（zip）します。圧縮されたファイルの拡張子を.apip に変更します。標準でSQL のINSERT を行うことができるツールや環境からドライバーを使ってみます。

INSERT 文を発行

INSERT INTO Meetings 
  (Topic,Type,StartTime,Duration,TimeZone,UserId) 
VALUES 
  ('Test Meeting (Edited Profile)',2,'2019-12-31T00:00:00',60,'EST','user@domain.com')

Meeting in Zoom

A new Zoom Meeting added through the API Driver

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

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

ソリューション

開催予定のイベント

サポート

ブログへ →