チュートリアル：CData Adobe Analytics BizTalk Adapter を使ったアップデートグラムの実行

こんにちは！ウェブ担当の加藤です。マーケ関連のデータ分析や整備もやっています。

CData BizTalk Adapter for AdobeAnalytics は、BizTalk のAdobe Analytics でSQL コマンド、アップデートグラム、ストアドプロシージャを実行することを可能にします。ここでは、アップデートグラムを使用して、Adobe Analytics を挿入するアプリケーションのウォークスルーについて説明します。

1. 一方向のファイル受信場所はアップデートグラムを含むXML ドキュメントをピックアップします。
2. ドキュメントは、アダプタ用に構成された要請応答送信ポートにルーティングされます。
3. アダプタはコマンドを実行します。挿入の結果には、新しいレコードのId と、影響を受ける行が含まれています。
4. Adobe Analytics からの応答は、一方向のファイル送信ポートにルーティングされ、BizTalk メッセージをファイルに書き込みます。

サンプルアプリケーションを作成する

以下のセクションでは、サンプルアプリケーションの作成について説明します。

1. スキーマとアップデートグラムインスタンスを生成する
2. 受信ポートを構成する
3. ファイルの受信場所を構成する
4. 要請応答送信ポートにアダプタを構成する
5. ファイルの送信ポートを構成する
6. アプリケーションを介してBizTalk メッセージをルーティングするフィルタを作成する
7. ロケーションとポートを登録し、有効にする
8. アプリケーションログを表示する

スキーマとアップデートグラムインスタンスを生成する

Visual Studio のウィザードを使用することで、スキーマとアップデートグラムインスタンスを生成することができます。

1. プロジェクトにアダプタを追加する
2. 挿入スキーマを生成する
3. アップデートグラムインスタンスを生成する

プロジェクトにアダプタを追加する

［Add Adapter］ウィザードを使用して、プロジェクトにアダプタを追加します。アダプタを使用して、挿入したいテーブルに関する［AdsReport］などのAdobe Analytics メタデータをクエリします。

1. ［Solution Explorer］の［project］で右クリックし、［Add］->［Add Generated Items］と進みます。
2. ［resulting dialog box］の［Add Adapter Metadata］を選択します。
3. 表示される［Add Adapter］ウィザードで、リストからCData BizTalk Adapter for AdobeAnalytics を選択します。
4. ［Port menu］では、選択を空白のままにします。構成済みアダプタの接続文字列を使用したい場合には、BizTalkアプリケーションから送信ポート、または受信場所を選択します。

挿入スキーマを生成する

Adobe Analytics データを挿入するアップデートグラムを作成するためのテンプレートとしてスキーマを使用します。スキーマは、XMLリクエストと応答を定義する.xsd ファイルです。例として、挿入アップデートグラムを生成する方法を説明します。以下の手順に従って、update とdelete のアップデートグラムを生成できます。

1. ［Schema］ウィザードの［Connection String］ページで、認証資格情報とその他の接続プロパティを入力します。
2. 次のステップでは、［Send Port］オプションを選択します。
3. ［One-Way］オプションをオフにします。［One-Way］オプションは、返されたAffectedRows値など、アップデートグラムのアダプタからのすべての応答を無視します。新しく作成されたId の行も返されます。［One-Way］オプションを無効にすることで、Id の取得をサポートするアップデートグラムスキーマを取得できます。
4. ［Command Type］ メニューで、アップデートグラムを選択します。

5. ［Insert］オプションを選択し、挿入したいテーブルとカラムを選択します。このチュートリアルは、Page とPageViews を使用しています。

   Noteアップデートグラムを作成する際、挿入はスキーマに含ませたカラムに限定されます。

6. 概要ページで、定義した設定を確認し、［Finish］をクリックしてウィザードを閉じます。

アップデートグラムを生成する

このステップでは、後のステップでアダプタに送られるXML メッセージを作成します。［Solution Explorer］にある.xsd ファイルを右クリックし、［Generate Instance］をクリックしてアップデートグラムを作成します。アップデートグラムが保存される場所は、［Output］タブに表示されます。

アップデートグラムは、Adobe Analytics から求められる応答を定義するよう構成されています。アップデートグラムの例や詳細については、アダプタのヘルプドキュメントをご覧ください。

受信ポートを構成する

アプリケーションに受信場所を追加するには、まず受信ポートを追加する必要があります。受信ポートは複数の受信場所からのデータを受け取ることができます。

1. ［BizTalk Server Administration Console］でアプリケーションを開きます。
2. ［Receive Ports］を右クリックし、［New］->［One-Way Receive Port］と進みます。受信ポートプロパティのダイアログが表示されます。
3. 受信ポートの名前を入力します。

ファイル受信場所を構成する

静的な一方向のファイル受信場所は、アップデートグラムを含むBizTalk メッセージを作成します。

1. ［Receive Locations］を右クリックし、［New］->［One-Way Receive Location］と進みます。
2. 新しい受信場所がメンバとなる受信ポートを選択します。［Receive Location Properties］ダイアログが表示されます。
3. 受信場所の名前を入力します。
4. ［Transport Type］メニューで、［FILE］を選択します。
5. ［Configure］をクリックします。［File Transport Properties］ダイアログが表示されます。
6. ［Receive Folder］ボックスに、［DemoOutbound］のようなフォルダへのパスを入力します。受信場所はこのフォルダをスキャンし、［File mask］ボックスの条件に一致するファイルを探します。
7. ［Receive Location Properties］ダイアログの［Receive Pipeline］メニューで、デフォルトオプションの［PassThruReceive］を選択します。

要請応答送信ポートで、Adobe Analytics アダプタを構成する

コンフィギュレーションは、以下のステップで構成されています。

1. 要請応答送信ポートを作成、構成する
2. アダプタを構成する
3. Adobe Analytics への接続を構成する

要請応答送信ポートを作成、構成する

要請応答送信ポートを使用して、 アップデートグラムコマンドの結果を取得します。このチュートリアルでは、新しく挿入されたレコードのId がBizTalkで返されます。

1. ［BizTalk Administration Console］でアプリケーションを開きます。
2. ［Send Ports］を右クリックし、［New］->［Static Solicit-Response Send Port］を選択すると、送信ポートプロパティのダイアログが表示されます。
3. 送信ポートの名前を入力します。
4. ［Transport Type］メニューで、CData.AdobeAnalytics を選択します。

CData Adobe Analytics アダプタを構成する

［Adapter Transport Properties］ダイアログで、アダプタが実行するコマンドを定義します。

1. 送信ポートのプロパティで、［Configure］ボタンをクリックします。［Adapter Transport Properties］ダイアログが表示されます。
2. ［CommandType］プロパティで、アップデートグラムを選択します。

プロパティとその機能についての説明は、ヘルプドキュメントの［Adapter Configuration］を参照してください。

Adobe Analytics への接続を構成する

Adobe Analytics への接続に必要な資格情報とその他のプロパティを設定します。

1. ［Adapter Transport］プロパティダイアログで、［Connection String］プロパティのボタンをクリックします。［Connection String Options］ダイアログが表示されます。

2. 接続プロパティを入力してください。

   下は一般的な接続文字列です。

   GlobalCompanyId=myGlobalCompanyId; RSID=myRSID; OAuthClientId=myOauthClientId; OauthClientSecret=myOAuthClientSecret; CallbackURL=myCallbackURL;

   Adobe Analytics はOAuth 認証標準を利用しています。 OAuth 統合またはサービスアカウント統合で認証できます。OAuth を使って認証するには、アプリケーションを作成してOAuthClientId、OAuthClientSecret、およびCallbackURL 接続プロパティを取得しなければなりません。認証方法については、ヘルプドキュメントの「OAuth 認証の使用」を参照してください。

   GlobalCompanyIdの取得

   GlobalCompanyId は必須の接続プロパティです。Global Company ID がわからない場合は、Swagger UI のusers/me エンドポイントのリクエストURL で見つけることができます。Swagger UI にログインした後、ユーザーエンドポイントを展開し、「GET users/me」ボタンをクリックします。「Try it out」ボタンと「Execute」ボタンをクリックします。リクエストURL のusers/me エンドポイントの直前に表示されるGlobal Company ID をメモします。

   Report Suite Id の取得

   Report Suite ID （RSID）は必須の接続プロパティです。Adobe Analytics UI で、「管理者」->「レポートスイート」に進むと、名前の横にある識別子とともにレポートスイートのリストが表示されます。

   GlobalCompanyId、RSID、およびOAuth 接続プロパティを設定して、Adobe Analytics に接続してください。

3. ［Test Connection］をクリックして値を確認します。

接続プロパティとその機能の説明については、ヘルプドキュメントの［Connection String Options］チャプターを参照してください。

ファイル送信ポートを構成する

ファイル送信ポートは、インサートから返されるId をファイルに書き込みます。以下のステップに従って一方向送信ポートを構成し、受信メッセージをファイルに書きこみます。

1. ［Send Ports］を右クリックし、［Static One-Way Send Port］をクリックします。
2. ［Type］メニューで、［FILE］を選択します。
3. ［Configure］をクリックします。
4. ［DemoInbound］のような、メッセージが書き込まれるフォルダへのパスを［Destination Folder］ボックスに入力します。

アプリケーションを介してBizTalk メッセージをルーティングするフィルタを作成する

以下のステップに従って、アプリケーションで次の関連を定義するフィルタルールを作成します。

• 要請応答送信ポートを、アップデートグラムを含むBizTalk メッセージと関連付けます。
• ファイル送信ポートを、アップデートグラムの実行結果によって作成されたBizTalk メッセージと関連付けます。

1. 要請応答送信ポートのプロパティで、［Filters］をクリックし、以下の値を設定します。

   • プロパティ…メニューから、［BTS.InboundTransportLocation］を選択します。
   • 値…一方向の受信場所のURLを入力します。（この例では、［"C:\DemoOutbound\*.xml］を使用しています。）

2. 一方向送信ポートのプロパティで、［Filters］をクリックし、以下の値を設定します。

   • プロパティ…メニューから、［BTS.SPName］を選択します。
   • 値…要請応答送信ポートの（URL ではなく）名前を入力します。

ロケーションとポートをエンリストして有効にする

BizTalk アプリケーションを起動するときに以下の手順に従い、アップデートグラムが受信場所によって確実に取得されるようにします。

1. 要請応答送信ポートを右クリックし、［Start］をクリックします。これにより、送信ポートも登録されます。
2. 一方向送信ポートを右クリックし、［Start］をクリックします。これにより、送信ポートも登録されます。
3. 受信場所を右クリックし、［Enable］をクリックします。

受信場所用に構成したフォルダに、アップデートグラムを複製することができます。

一方向送信ポート用に構成したフォルダを開きます。このフォルダは、XML file の新しいId を含みます。メッセージは次の例のようになります。

<table xmlns="http://www.cdata.com/AdobeAnalyticsProvider" AffectedRows="1"> <row> <Id>0014000001XERBUAA5</Id> </row> </table>

アプリケーションログを表示する

アプリケーションログでエラーメッセージを表示することで、アプリケーションが正常に初期化されたことを素早く確認できます。ログを開くには、［Administration Console］のナビゲーションツリーで［Event Viewer (Local)］ノードを展開します。Windows ログを展開し、［Applications］を選択します。

発生したエラーのリストはここから入手可能です。ここには、システム上のすべてのアプリケーションのエラ-メッセージが含まれるため、エラーメッセージのソースを確認することが必要です。受信場所では、ソースが［CData BizTalk AdobeAnalytics Receive Adapter］である必要があります。エラーメッセージの詳細から、エラーの理由を知ることができます。

エラー解消のガイダンスについては、[email protected]/jp にお問い合わせください。