CData Software Blog

クラウド連携のCData Software の技術ブログです。

Zoho Marketing Hub を各種ツールから連携可能なコネクタ・ドライバー化:CData API Driver

f:id:sugimomoto:20210311162501p:plain

こんにちは。CData Software Japanリードエンジニアの杉本です。

本記事では、各種 Web APIODBC / JDBC / ADO.NET といった標準のDB接続規格でアクセスできるようにするCData API Driverを用いて、Zoho Marketing Hub の API を各種ツールから接続する方法を紹介します。

ExcelAccess・Power BIなどのUIベースのツールやAsteriaなどのETLツールはもちろん、Visual StduioやEclipseといった開発ツールからも接続することが可能です。

Zoho Marketing Hub とは?

Zoho Marketing HubはCRMSaaSで有名なZohoが提供しているMarketing Automation SaaSです。

www.zoho.com

f:id:sugimomoto:20210311161654p:plain

見込み客の詳細な管理から、マルチチャネルマーケティングまで、様々な機能を備えたMAツールとなっています。

Zoho Marketing Hub では外部連携用のAPIも提供しており、リードの生成や取得、マーケティングリストの管理までAPIで行うことができるようになっています。

www.zoho.com

f:id:sugimomoto:20210311161702p:plain

今回はこのAPIを使って、様々なツールとの連携を実現しています。

実現イメージ

この記事では Zoho Marketing Hub APIに対してExcelやPower BIといった各種ツールやIDEからの接続方法を紹介します。しかしながら、各APIは単純にツールと接続・連携することはできません。

各ツールがどのようにWeb API側へリクエストを投げるべきかの判断材料や各種認証方法の処理、メタデータの情報等が無いためです。そのためには基本的にカスタムコネクタを作るか、プログラムを組まなければいけません。

f:id:sugimomoto:20210311161711p:plain

そこで、CData API Driver を用いて、このボトルネックを解決します。

まず、各ツールからはODBCJDBCインタフェースでSQL(Select文)をCData API Driverに向けて発行してもらいます。そのリクエストを受け取った CData API Driverは、Zoho Marketing Hub の API のエンドポイントに対して、SQL文を解釈し、HTTPリクエスト発行します。

リクエスト後、JSONフォーマットで返ってきたデータをCData API Driverが各種インタフェースフォーマットにデータを変換してツールに返します。

f:id:sugimomoto:20210311161718p:plain

これにより、各種ツールからアドホックSQLによるリクエストがあったタイミングで最新のデータをZoho Marketing Hub API から取得することが可能となります。

各種接続シナリオと必要なツール

CData API Driver は様々なツールとの接続に利用できますが、今回は以下のツールを用いて接続する方法を解説していきます。

上記以外のツールからの接続に関しては、以下のページで各種接続方法記事を公開しています。

www.cdata.com

f:id:sugimomoto:20201124135144p:plain

テーブル(ビュー)一覧

Zoho Marketing Hub API Profileでは、以下のテーブル(ビュー)を提供しています。用途に合わせて、接続してみてください。

テーブル名 対応API 備考
CampaignDetails getcampaigndetails データを取得する場合、Where句でCamapignKeyを指定する必要があります。
CampaignReports campaignreports データを取得する場合、Where句でCamapignKeyを指定する必要があります。
Campaigns recentcampaigns  
CampaignRecipients getcampaignrecipientsdata データを取得する場合、Where句でCamapignKeyを指定する必要があります。
MailingLists getmailinglists  
Segments getmailinglists  
MailingListLeads getlistleads データを取得する場合、Where句でListKeyを指定する必要があります。
LeadFields getallleadfields  
SegmentLeads getsegmentleads データを取得する場合、Where句でCVIDを指定する必要があります。
Journeys getopenjourneys  

Zoho Marketing Hub API 利用準備

まず、Zoho Marketing Hub APIに接続するために、認証・認可を行う OAuthアプリケーションを準備しましょう。

www.zoho.com

以下のURLにアクセスし、「ADD CLIENT」をクリックしてください。

api-console.zoho.com

f:id:sugimomoto:20210311161726p:plain

Client Typeの一覧から「Server-based Applications」を選びます。

f:id:sugimomoto:20210311161732p:plain

任意の「Client Name」と「Homepage URL」を指定し、リダイレクト先として使用するアプリケーションに応じたURLを指定します。

Excel Add-inやODBCJDBC Driver等でローカル接続を行う場合は「http://localhost:33333」を指定します。 CDataSyncの場合は「http://localhost:8019/src/oauthCallback.rst」を指定します。

クラウドホスティング等で接続する場合は、ドメイン:ポート番号をそれぞれ適切な値に設定してください。

f:id:sugimomoto:20210311161738p:plain

アプリケーションの作成が完了すると、接続に必要な「ClientId」「Client Secret」を取得できます。

f:id:sugimomoto:20210311161743p:plain

API データ処理用 設定ファイルを作成

続いて、Zoho Marketing Hub の API を CData API Deiver が解釈できるように設定ファイル(API Profile)を作成します。

すでに私が作成したものがあるので、以下のURLからダウンロードしてください。

https://cdatajbuilds.s3-ap-northeast-1.amazonaws.com/APIProfiles/ZohoMarketingHub.apip

保存先フォルダは後ほど使用するので「C:\API Profiles」といった書き込み可能な任意のフォルダに配置してください。

f:id:sugimomoto:20210311161748p:plain

CDataSyncの場合は手順を後述します。

CData API Driver のインストール

各種ツールと Zoho Marketing Hub API を繋ぐために必要となる CData API Driverをインストールします。

基本的なインストール・設定方法は各種Driver共通ですので、ここではODBC Driverを例に説明します。

まず、CData API ODBC Driverの30日間の評価版をダウンロードします。ダウンロードの際には、Emailの登録が必要となります。

https://www.cdata.com/jp/apidriver/download/

f:id:sugimomoto:20201027111336p:plain

ダウンロードしたsetup.exeファイルをBIツールがインストールされているマシンにインストールします。インストールウィザードに従い、EULAを確認した上でインストールを完了します。

f:id:sugimomoto:20201027111341p:plain

※途中、ライセンスサーバーへのオンラインアクティベーションが行われるためネットワーク環境に接続されている必要があります。

インストールが完了すると、ODBCのDSN設定のウィンドウが立ち上がります。

以下の項目をセットし、保存します。

プロパティ名 備考
Profile C:\API Profiles\ZohoMarketingHub.apip 予めダウンロードしたZoho Marketing Hub.apipのパスを指定します。
AuthScheme OAuth
CallbackURL http://localhost:33333 OAuthのアプリで指定したRedirectURLを指定します。
Initiate OAuth GETANDREFRESH
OAuthClientId 例)1000.1WTGS9FJ66MZA5CNB364W5X39KTRSO 予め取得したClientIdを指定します。
OAuthClientSecret 例)186a570c2af1f63641ea06ce3fb90aacabc6109a9e 予め取得したClientSecretを指定します。

f:id:sugimomoto:20210311161754p:plain

「接続テスト」をクリックすると、ブラウザが立ち上がり、Zoho Marketing Hubへのログインとアクセス許可を求める画面が表示されます。内容を確認して「受諾する」をクリックしてください。

f:id:sugimomoto:20210311161800p:plain

最後に以下のようなメッセージが表示されればOKです。

f:id:sugimomoto:20210311161848p:plain

以上で、CData API Driverの準備は完了です。

Excel から Zoho Marketing Hub API に接続(Excel Add-in for API

CData Excel Add-in for API をインストール後、Excelを立ち上げるとCDataタブが追加されていることがわかります。このタブから各種操作を実施します。

接続を開始するには、CDataタブから[取得元 API]をクリックします。

f:id:sugimomoto:20201116171024p:plain

最初に接続するためのウィザードが表示されるので、「CData API Driverのインストール」の内容と同様に各種パラメータを入力します。

f:id:sugimomoto:20210311161909p:plain

接続後、対象テーブルを選択し、「OK」をクリックします。また、ここの画面で細かなフィルターやJOINの指定を行うことも可能です。

f:id:sugimomoto:20210311161914p:plain

f:id:sugimomoto:20210311161919p:plain

クリック後、対象のデータが一括で取得できます。

f:id:sugimomoto:20210311161924p:plain

Access リンクテーブル から Zoho Marketing Hub API に接続(CData REST ODBC Driver)

次はCData ODBC Driverを利用して、Access リンクテーブルから接続してみたいと思います。

あらかじめ新規にAccessを立ち上げて、空のデータベースを作成しておきましょう。

続いて「外部データ」タブから「新しいデータ ソース」→「他のソースから」→「ODBC データベース」を選択します。

image.png

ウィザードが表示されるので「リンクテーブルを作成」を選択し、「OK」をクリックします。

image.png

データソースの選択では「コンピューターデータソース」から事前に作成したCData API Driver用DSNを選択し「OK」をクリック

f:id:sugimomoto:20210311161930p:plain

テーブルの一覧が表示されるので、任意のテーブルを選択し「OK」をクリックします。

f:id:sugimomoto:20210311161935p:plain

設定後、リンクテーブルが追加され、以下のようにZoho Marketing Hubのデータを閲覧することができるようになります。もちろん、通常通りクエリデザイナーでも使用可能です。

f:id:sugimomoto:20210311161940p:plain

なお、Accessでうまくデータが取得できない場合は接続プロパティの「Other」の項目に「SupportAccessLinkedMode = False;」を設定してみてください。

f:id:sugimomoto:20201124134536p:plain

PowerBI から Zoho Marketing Hub API に接続(CData API Driver for Power BI)

続いて CData Power BI Connector を用いて、Power BIからZoho Marketing Hubのデータを取得します。

PowerBI Desktopを起動して、「データを取得」をクリックします。

f:id:sugimomoto:20201027111449p:plain

データ接続先一覧の中から「CData API」を選択し、「接続」をクリックします。

f:id:sugimomoto:20201027111519p:plain

データソース名は先程登録したZoho Marketing HubのDSNを入力し「OK」をクリックします。

f:id:sugimomoto:20210311161946p:plain

テーブルの一覧から対象となるテーブルを選択し「読み込み」をクリックします。

f:id:sugimomoto:20210311161951p:plain

以下のようにZoho Marketing Hubのデータを読み込みことができます。

f:id:sugimomoto:20210311161956p:plain

あとはPoewr BIの機能を用いて、ビジュアライズに利用することができます。

ASTERIA Warp から Zoho Marketing Hub API に接続(CData JDBC API Driver)

ASTERIA Warpでは、フローデザイナーを使って、データ処理のプロセスを作成します。

フローデザイナーの基本的な利用方法についてはWarpフローデザイナー操作ガイドをご覧ください。

CData JDBC API Driver はインストール後、「cdata.jdbc.api.jar」と「cdata.jdbc.api.lic」のファイルをAsteriaのドライバーフォルダ(asteriahome5\system\lib\drivers)に登録します。

f:id:sugimomoto:20210218152238p:plain

その後、ASTERIA Warpを立ち上げて、フローデザイナーにアクセスし、CData JDBC Driverを使用するために接続を追加します。

画面左のコネクションペイン上にある電源ボタンをクリックをクリックすると、「コネクションの作成」ダイアログが表示されます。

f:id:sugimomoto:20210216154030p:plain

「接続種別」として「RDB」を選択、「名前」に分かりやすい名前を設定し「OK」をクリックします。

作成したコネクションをダブルクリックすると、画面右のインスペクタに接続プロパティが表示されます。 「基本」タブでドライバーのパスとURLをそれぞれ設定します。

プロパティ名 備考
ドライバーのパス 例)C:\asteriahome5\system\lib\drivers\cdata.jdbc.api.jar 前節でインストールした API JDBC Driverファイルへの参照を指定します。
URL jdbc:api:Profile=C:\API Profiles\ZohoMarketingHub.apip;
ProfileSettings=";Authscheme=OAuth;
InitiateOAuth=GETANDREFRESH;
OAuthClientId=XXXX;
OAuthClientSecret=XXXX;
CallbackUrl=http://localhost:33333;";
Zoho Marketing Hubに接続するための接続文字列を指定します。

これでコネクションの作成は完了です。あとは、フロー上でデータベースタブにある「RDBGet」のコンポーネントを使って、データの取得が行なえます。

「RDBGet」フローに配置し、ダブルクリックします。

f:id:sugimomoto:20210216180653p:plain

コネクションの選択ウインドウが表示されるので、先程作成したZoho Marketing Hubのコネクションを選択しましょう。

f:id:sugimomoto:20210311162005p:plain

その後、SQLビルダーが表示されるので、取得したいデータが格納されている、任意のテーブルとカラムを選択します。

f:id:sugimomoto:20210311162017p:plain

あとは、「モデルにSQLを適用する」をクリックし「SELECTテスト」でデータが正常に取得できているかを確認します。

以下のようにデータが参照できれいればOKです。設定を保存してSQLビルダーを閉じます。

f:id:sugimomoto:20210311162023p:plain

CDataSync から Zoho Marketing Hub に接続

www.cdata.com

CDataSyncではデータソースとして、Zoho Marketing Hubに接続することができます。

なお、CDataSync Windows版の場合は「ZohoMarketingHub.apip」のプロファイルをSyncの本体が存在するフォルダの「www\app_data\profiles」に配置してください。profilesフォルダが存在しない場合は手動で作成してください。

C:\Program Files\CData\CData Sync\www\app_data\profiles

f:id:sugimomoto:20210311162029p:plain

Cross-Platform版の組み込みJettyで構成している場合は、以下のフォルダにapipファイルを配置します。

/opt/sync/profiles

また、Zoho の OAuthアプリにて予め、CDataSync用のRedirectURLを登録しておきましょう。

f:id:sugimomoto:20210311162040p:plain

配置後、CDataSyncを起動すると以下のようにデータソースとして Zoho Marketing Hubが利用できるようになります。

f:id:sugimomoto:20210311162047p:plain

接続プロパティは以下の通り設定します。

プロパティ名 備考
ProfileSettings CallbackURL=http://localhost:8019/src/oauthCallback.rst OAuthのアプリで指定したRedirectURLを指定します。
OAuthClientId 例)1000.1WTGS9FJ66MZA5CNB364W5X39KTRSO 予め取得したClientIdを指定します。
OAuthClientSecret 例)186a570c2af1f63641ea06ce3fb90aacabc6109a9e 予め取得したClientSecretを指定します。

入力後、「接続」ボタンをクリックし、Zoho Marketing Hubへのログインが完了すればOKです。

f:id:sugimomoto:20210311162059p:plain

併せて、任意の同期先の接続情報も構成しておきましょう。

f:id:sugimomoto:20210311162106p:plain

接続完了後、新しくジョブを作成します。

f:id:sugimomoto:20210311162114p:plain

先程作成したZoho Marketing Hubのコネクションを選択します。

f:id:sugimomoto:20210311162131p:plain

ジョブを作成した後は、Zoho Marketing Hub の同期対象となる任意のテーブルを選択しましょう。

f:id:sugimomoto:20210311162136p:plain

f:id:sugimomoto:20210311162140p:plain

データのプレビュー画面で、実際に取得が成功しているかどうかを確認できました。

f:id:sugimomoto:20210311162144p:plain

あとは、任意のスケジュールを指定してデータのレプリケーションを実行できます。

f:id:sugimomoto:20210311162149p:plain

Tips

MailingListLeadsやCampaignDetailsのデータを取得する場合は、特定の項目を取得条件に指定する必要があります。

以下のようなSQLもしくはフィルター条件を指定してください。

SELECT * FROM [MailingListLeads] WHERE [ListKey] = '3z26523521e34cf3463ff22569982475d8b05679ce564bcfdfab639caabbee9351'

f:id:sugimomoto:20210311162155p:plain

これでデータを取得できます。

f:id:sugimomoto:20210311162202p:plain

また、以下のようにサブクエリを用いて、メーリングリスト横断でLead情報を取得することも可能です。

SELECT * FROM MailingListLeads WHERE ListKey In (SELECT ListKey FROM MailingLists);

サンプルとなるSQLは以下のとおりです。

SELECT * FROM LeadFields;

SELECT * FROM MailingListLeads WHERE ListKey = '3z26523521e34cf3463ff22569982475d8b05679ce564bcfdfab639caabbee9351';

SELECT * FROM MailingListLeads WHERE ListKey In (SELECT ListKey FROM MailingLists);

SELECT * FROM Campaigns;

SELECT * FROM MailingLists;

SELECT * FROM SegmentLeads WHERE CVID = '782097000000060831';

SELECT * FROM SegmentLeads WHERE CVID IN (SELECT CVID FROM Segments);

SELECT * FROM Segments;

SELECT * FROM Journeys;

SELECT * FROM CampaignReports WHERE CampaignKey = 'XXXXXXX';

SELECT * FROM CampaignRecipients WHERE CampaignKey = 'XXXXX';

SELECT * FROM CampaignDetails WHERE CampaignKey = 'XXXX';

終わりに

これら以外にもCData API Driverは各種ETLツールや帳票ツールなどからも接続することが可能です。

以下のCData オンラインナレッジベースには、各種ツールからの接続方法を紹介した記事が多数掲載されているので、是非見てみてください。

www.cdata.com

また、こういったツールとはどう連携すればいいの? といった問い合わせはテクニカルサポートフォームまでお気軽にどうぞ!

https://www.cdata.com/jp/support/submit.aspx