こんにちは。CData Software Japan リードエンジニアの杉本です。
今回はCData Connect Cloud が備えているAPIの一つであるOData APIの使い方を解説したいと思います。
CData Connect とは？
CData Connect はGoogle スプレッドシートやExcel 365 などのクラウド上のスプレッドシート、Tableau Online、Google データポータル、Amazon QuickSight などのクラウドBI、Power Apps、AppSheet、OutSystems などのローコード / ノーコードツールから100種類以上のSaaS にAPI コーディングなしで接続することが可能になるData Connectivity as a Service です。
データソースはSalesforce、Dynamics 365、NetSuite、Adobe Marketo Engage、Salesforce Marketing Cloud Account Engagement（旧Pardot）、kintone、SharePoint などあらゆる業務SaaS に対応しています。
CData Connect が持つインターフェースの種類
CData Connect は前述の各ツールとのSaaS・NoSQL・DBの橋渡しを行うインターフェースとしてODataやVirtual SQL Serverをサポートしており、この機能によりシームレスな連携を実現しています。
インターフェースの種類は以下の3種類存在します。
https://cloud.cdata.com/docs/jp/Connecting-Data.html
・API（CData Connect API）
・OData
・Virtual SQL Server
今回はこの中でも「OData」に絞って解説を行います。
ちなみに「API（CData Connect API）」はCData Connect へのSQLのクエリがWeb APIのインターフェースを通じて行えるものです。
以下のようにPOSTリクエストでSQLを渡して、データの取得や処理を行います。
POST https://cloud.cdata.com/api/query
{
"query": "SELECT Id, AccountName, AccountNumber FROM Salesforce1.Account LIMIT 5",
"timeout": 60,
"parameters": {}
}
OData とは？
ODataは、データモデルの記述、およびそれらのモデルに従ったデータの編集および照会をサポートするプロトコル。 ざっくり言ってしまうと、表形式データの“編集”および“照会”を強みとしたREST ful なプロトコルです。
https://www.odata.org/
特徴としては、以下のような点があげられます。
・ メタデータ：特定のデータプロバイダによって公開されるデータモデルの機械可読の記述。
・ データ：データエンティティのセットとそれらの間の関係。
・ クエリー：サービスがフィルタリングとデータへの変換を実行するよう要求し、結果を返す。
・ 編集：データの作成、更新、および削除。
・ 操作：カスタムロジックの呼び出し
・ボキャブラリ：カスタムセマンティクスの付加
引用元：OData Web Services
http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html
個人的に特にとりあげるべきと考えるポイントは、REST API における URIに のフォーマットを統一したことにあるでしょう。
$top、$select、$filterといった、ある種SQLライクにWeb APIのデータリクエストを定型化することで、表形式データの取得アプローチを最適化しています。
また、EDMと呼ばれるMetadataエンドポイントを備えているので、各種フィールドや型を確認できるのも強みですね。これがあることで動的にクライアントからリクエストを組み立てることが可能です。
Postman・Power BI のインストール
今回の記事ではOData API の利用を APIクライアント・テストツールであるPostman から実施します。
利用しているプラットフォームに応じて、以下のリンクからツールをダウンロードしておいてください。
https://www.postman.com/
また、OData活用の一例として Power BI を例として取り上げています。こちらは以下のリンクからツールをダウンロードしておいてください。
https://powerbi.microsoft.com/ja-jp/desktop/
CData Connect のトライアルの取得
それでは実際にCData Connect を試していきましょう。まず以下のリンクからCData Connect のトライアルを取得します。
https://www.cdata.com/jp/cloud/
詳しいトライアルの取得方法は以下のリンクを参照ください。
https://www.cdata.com/jp/blog/connect-trial
Connection の追加
CData Connect の環境を取得したら、まず連携先のクラウドサービスに対するConnection を構成します。
「Connections」から「＋ Add Connection」をクリックし
今回は「Salesforce」を選択します。
Salesforce はOAuth やセキュリティトークンを用いた接続が可能です。
セキュリティトークンで接続するため、認証形式を変更します。[Advanced Settings]タブを開き、Auth Scheme でBasicを選択します。
その上で User・Password・Security Tokenを入力して「Create & Test」をクリックします。
以下のように接続成功のメッセージが表示されればConnection の作成は完了です。
また、合わせて対象のConnection に実行できる書き込みや更新操作の権限も調整しておきましょう。
Data Explorer で取得できる内容を確認
Connection の作成が完了したら、まずどのようなデータが取得できるのか、Data Explorer を使ってデータをクエリしてみましょう。
「Data Explorer 」を選択し「Schemas」から先程作成したSalesforce のConnection を選択します。するとSalesforce のオブジェクト一覧がテーブルとして表示されるので、Account（取引先）をドラッグ・アンド・ドロップでエディターに移動させます。
すると以下のようにSalesforce のデータがCData Connect 上で扱えることが確認できます。
OData へ Table の登録
CData Connect で OData APIを利用するには予めOData として公開するテーブルを選択しておく必要があります。
「OData」から「＋Add」をクリックし
先程作成したSalesforce のConnection を選択の上、「Next」をクリックします。
テーブル一覧が表示されるので、今回はAccount（取引先）とContact（取引先担当者）を選択しました。
これで以下のようにOData APIでそれぞれのテーブルを利用できるようになります。
なお、テーブルをクリックすると利用するカラムやエイリアス、データ型の変更が可能です。
API Tokenの生成
CData Connect の各インターフェースの接続にはAPI Tokenというログインパスワードとは別の認証キーが必要となります。
右上のユーザー名から「Settings」に移動し
「Access Tokens」のタブで「＋Create PAT」をクリックします。
任意の名前をつけて、「Create」をクリックすると
以下のようにPATが採取できます。これは一度しか表示されないので注意しましょう。
OData の活用例：Power BI からの利用
CData Connect 側でOData の準備が整ったので、早速使ってみましょう。
まず、ODataがどんなツールからどのように活用できるのかイメージを持ってもらうために、Power BI Desktopを例として接続を試してみたいと思います。
Power BI Desktop ではOData の読み取りを標準サポートしており、以下のように「データを取得」→「OData フィード」でCData Connect OData APIへの接続を追加できます。
OData フィードでは接続のOData エンドポイントURLが必要になります。「 https://cloud.cdata.com/api/odata/service」を入力します。
なお、この値はCData Connect の管理画面でも確認できます。
認証方法では「基本」を選択し、「ユーザー名」とパスワードを入力します。なお、パスワードの欄には事前に生成しておいたPATを指定してください。
すると以下のようにCData Connect で登録しておいたSalesforce の各テーブルが表示され、シームレスにPower BI のデータとして取り込むことができます。通常のAPIでは提供していない、テーブルやカラム、型に関する情報も識別してくれるのが便利です。
あとはPower BI の機能を活用して、各種データをビジュアライズできます。
Postmanからの実行方法：OData APIの認証
Power BI での例を御覧頂いたように、OData を活用することで、このようなCData Connect と連携するクライアントツールのアドオンを開発することができます。
それではここからはOData APIの使い方を通じて、アドオン開発のイメージを持ってもらおうと思います。
まず認証方法です。CData Connect ではBasic認証をサポートしています。
https://cloud.cdata.com/docs/jp/OData-Dashboard.html#postman
HTTPリクエストとしては以下のようにAuthorizationヘッダーに「user」と「password」をコロンで繋いで、Base64エンコードしたものを指定します。
Authorization: user:passwordをBase64エンコードしたもの
Postmanでは以下のように新しいリクエストを立ち上げて「Authorization」タブから「Basic Auth」を選択して、CData Connectのユーザー名とPATを指定します。
Metadata のクエリ
OData API は前述の通り、API自身が持つデータモデル、つまりMetadata を取得できることが大きな特徴の一つです。
世の中に数多く存在するREST APIなるものは、それがどんなリソースを持ち、どんなカラムを持っていて、どんなデータが取得できるのか、仕様書を使わなければ判別ができません。
しかしながら、ODataを使うことでAPIが持つテーブル、カラムを予め識別し、例えばユーザーへそれらの情報を提供し、選択させるようなインターフェースを作ることも可能です。
Metadata の取得はOData APIの仕様ではエンドポイントに「$metadata」を付与してリクエストするものと定められています。
https://cloud.cdata.com/docs/jp/OData-Metadata.html
以下のようにリクエストを送ってみましょう。
GET https://cloud.cdata.com/api/odata/service/$metadata
すると以下のようなXMLベースのデータが取得できます。（一部省略）
「EntityContainer」でテーブルの一覧を識別し、そのEntityTypeによって、それぞれのテーブルが持つカラムやKeyの情報、型の情報が識別できるようになっています。
ちなみに、OData仕様上Metadata はXMLと決まっていますが、CData Connect ではより扱いやすいようにJSONのフォーマットでも取得できるようになっています。ただ、OData 準拠での提供では無いため注意しましょう。
GET https://cloud.cdata.com/api/odata/service
{
"@odata.context": "https://cloud.cdata.com/api/odata/service/$metadata",
"value": [
{
"name": "Account",
"kind": "EntitySet",
"url": "Account"
},
{
"name": "Contact",
"kind": "EntitySet",
"url": "Contact"
}
]
}
レコードの取得
それでは実際に各テーブルのデータを取得してみましょう。
先程のMetadata でこのODataが持つリソースが特定できました。この取得したリソース名を用いてURLを組み立てることにより、対象のデータが取得できます。
OData はREST Ful なAPI なのでGET リクエストでデータが取得できます。
GET https://cloud.cdata.com/api/odata/service/Account
{
"@odata.context": " https://cloud.cdata.com/api/odata/service/$metadata#Account",
"value": [
{
"Id": "0017F000043zARYQA2",
"IsDeleted": false,
"MasterRecordId": null,
"Name": "Company Sample",
"Type": null,
"ParentId": null,
"BillingStreet": null,
"BillingCity": null,
"BillingState": null,
/* 一部省略 */
},
{
"Id": "0017F00000iPW5fQAG",
"IsDeleted": false,
"MasterRecordId": null,
"Name": "Company Sample 2",
"Type": "Customer - Channel",
"ParentId": null,
"BillingStreet": "345 Shoreline Park\nMountain View, CA 94043\nUSA",
"BillingCity": "Mountain View",
"BillingState": "CA",
/* 一部省略 */
}
]
}
各種クエリオプションの利用方法
OData の特徴の一つにURLクエリパラメータで指定できるデータの取得オプションが統一されていることが挙げられます。これを用いることで取得したいカラムを絞り込んだり、ページネーションの実施やフィルター条件の処理を柔軟に指定できます。
https://cloud.cdata.com/docs/jp/OData-Query-Options.html
現在CData Connect でサポートされているOData のクエリパラメータは以下のとおりです。
・$filter：データを取得する条件を指定します。
・$select：取得する項目を指定します。
・$orderby：取得結果の並び替えを指定します。
・$count：取得対象レコードの件数を指定します。
・$top and $skip：データの取得範囲を指定します。
例えば取得するカラムをId、Name、NumberOfEmployeesに絞り込み、上位3件をNumberOfEmployees：従業員数の少ない順（昇順）で取得したい場合、以下のようなクエリとなります。
GET https://cloud.cdata.com/api/odata/service/Account?$select=Id,Name,Type&$top=3&$orderby=Name
{
"@odata.context": " https://cloud.cdata.com/api/odata/service/$metadata#Account",
"value": [
{
"Id": "0017F000033NddxQAC",
"Name": "Sample",
"NumberOfEmployees": 111
},
{
"Id": "0017F00000iPW5YQAW",
"Name": "Dickenson plcaa",
"NumberOfEmployees": 120
},
{
"Id": "0017F00000iPW5fQAG",
"Name": "Update",
"NumberOfEmployees": 265
}
]
}
Filter 条件は以下のように組み立てることができ、様々な条件式を利用できます。
例えば従業員数100以上の取引先に絞り込みたい場合は以下のように指定します。
GET https://cloud.cdata.com/api/odata/service/Account?$select=Id,Name,NumberOfEmployees&$filter=NumberOfEmployees gt 100&$top=10&$orderby=NumberOfEmployees
条件式は以下のようなものがそれぞれ利用できるので、柔軟にデータの取得が実施できます。
https://cloud.cdata.com/docs/jp/OData-Query-Options.html#filter
データの追加・削除・更新の実行方法
OData は REST ful なAPI なのでデータの追加、更新、削除も決まったルールで実施できます。
https://cloud.cdata.com/docs/jp/OData-Operations.html#post
データを作成するときはPOST リクエストでリクエストBody にJSON データを指定して行います。
POST https://cloud.cdata.com/api/odata/service/Account
{
"Name": "Postman Sample",
"NumberOfEmployees": 1000
}
Postman では以下のように「Body」タブから「raw：JSON」を選択して入力します。
データの更新ではURL に更新対象のID を指定して行います。予め更新用のカラムのデータを取得しておきましょう。メソッドはPATCH を用いるので、リソースの部分的な更新が可能です。
PATCH https://cloud.cdata.com/api/odata/service/Account('0017F000043zARYQA2')
{
"Name": "Postman Sample Update"
}
DELETE は更新と同様にURL にID を指定し、DELETE メソッドで実施します。
DELETE https://cloud.cdata.com/api/odata/service/Account('0017F000043zARYQA2')
おわりに
このようにCData Connect は OData を用いることでそれぞれのAPI仕様の複雑さを意識せずに、共通処理としてデータ処理を実施できます。
試していく中でご不明な点があれば、どうぞお気軽にサポートフォームまでお問い合わせください。
https://www.cdata.com/jp/support/submit.aspx
関連コンテンツ
