AdobeAnalytics: Adobe I/OのAPIを使ってSAINT分類データを取得する

ホーム
Adobe Analytics, Adobe I/O
AdobeAnalytics: Adobe I/OのAPIを使ってSAINT分類データを取得する

2020.12.3

AdobeAnalytics: Adobe I/OのAPIを使ってSAINT分類データを取得する

こんにちは、エクスチュアの權泳東(権泳東/コン・ヨンドン)です。

今回はSAINT分類データをAdobe I/OのAPIを使って取得する方法についてです。

AAのUIからもSAINT分類データをTSV形式でダウンロードする事が可能です。
しかし、ファイルサイズが1MBを超えてしまう場合、FTPというレガシーなプロトコルを使ってAdobe指定のFTPサーバーからファイルをダウンロードするという残念なエクスペリエンスを強いられます。

というわけで、もっとモダンなエクスペリンスを求めるためにAdobe I/OのAPIを使ってSAINT分類データを取得する処理を実装しました。

Adobe I/Oプロジェクトを作成する

Adobe I/Oコンソールを開いて、「Create new project」からプロジェクトを作成します。

https://console.adobe.io/home

作成したら、「Add API」で「Adobe Analytics」を選んで追加します。
必要な権限を追加してから、キーペアをzipファイルでダウンロードします。

認証の作成では「JWT」を選択してください。

JWT認証を実装する

ここからが本題。

JWT認証をしてAPI実行に必要なトークンを生成する処理をNode.jsで実装します。
まずは簡単なプログラムを書きました。
これ↓です。

/* token.js */
const jwt = require('jsonwebtoken');
const fs = require('fs');
const request = require('request');

const expire = Math.round((Date.now() + 86400000) / 1000);

const payload = {
    "exp":expire,
    "iss":process.env.ADB_ORG_ID,
    "sub":process.env.ADB_TECH_ACC_ID,
    "https://ims-na1.adobelogin.com/s/ent_analytics_bulk_ingest_sdk":true,
    "aud":"https://ims-na1.adobelogin.com/c/"+process.env.ADB_CLIENT_ID
};

const client_id = process.env.ADB_CLIENT_ID;
const client_secret = process.env.ADB_CLIENT_SECRET;

const secret = fs.readFileSync('private.key');

const options = {
    algorithm: 'RS256'
};

const token = jwt.sign(payload, secret, options);

const  headers = {
    'Content-Type' : 'application/x-www-form-urlencoded'
};

let params = {
    url : 'https://ims-na1.adobelogin.com/ims/exchange/jwt',
    method : 'POST',
    headers : headers,
    form : {
        'client_id' : client_id,
        'client_secret' : client_secret,
        'jwt_token' : token
    },
    json : true
};
 
request(params, function (error, response, body) {
    let res = body.access_token;
    console.log(res);
});

JWTペイロードを生成して認証サーバーにPOST送信して24時間有効なトークンを取得する、という処理を実装しました。
このNode.jsプログラムの実行方法は後述します。

ClassificationsAPIを実装する

続いて、ClassificationsAPIを実装します。
これまたNode.jsでプログラムを作成しました。
これ↓です。

/* exec_saint_api.js */
const method = process.argv[2];
const token = process.env.TOKEN;

const Client = require('node-rest-client').Client;
const client = new Client();
const endpoint = 'https://api.omniture.com/admin/1.4/rest/';

const fs = require('fs');

let args = { 
    headers: {
        'Authorization' : 'Bearer ' + token,
        'Content-Type' : 'application/json'
    },
    parameters: {
        'method' : 'Classifications.' + method
    }
};

if (method == 'CreateExport') {
    args.data = {
        'rsid_list' : [process.env.RSID],
        'encoding' : 'UTF-8',
        'all_rows' : true,
        'element': process.env.VAR,
        'email_address' : process.env.EMAIL,
        'date_filter_start_date' : process.env.DATE_START,
        'date_filter_end_date' : process.env.DATE_END
    };
    client.post(endpoint, args, (data, response) => {
        console.log(data.job_id);
    });
} else if (method == 'GetStatus') {
    args.data = {
        'job_id' : process.env.JOB_ID
    };
    client.post(endpoint, args, (data, response) => {
        let timer = setInterval(() => {
            let job = data.find((x) => x.type == 'job_id');
            if (job.status == 'Completed') {
                let file = data.find((y) => y.type == 'file_id');
                let file_id = file.id;
                let page_num = file.viewable_pages;
                console.log(file_id + ',' + page_num);
                clearInterval(timer);
            }
        }, 60000);
    });
} else if (method == 'GetExport') {
    let file_id = process.env.FILE.split(',')[0];
    let page_num = parseInt(process.env.FILE.split(',')[1]);
    let saint_json = process.env.SAINT_JSON;
    for (let i=0; i<page_num; i++) {
        args.data = {
            'file_id' : file_id,
            'page' : i+1
        };
        client.post(endpoint, args, (data, response) => {
            fs.appendFileSync(saint_json, JSON.stringify(data));
        });
    }
}

SAINT分類データのエクスポートジョブを生成してからデータを取得するために、CreateExport, GetStatus, GetExportというメソッドを実行するための処理を実装しています。
このNode.jsプログラムの実行方法は以下で説明します。

プログラム実行のためのbashスクリプト

さて、ここまでに作成したtoken.jsとget_saint_api.jsを実行するためのbashスクリプトを書きます。

#!/bin/bash

set -eu
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin

##設定ここから##
# API認証情報
export ADB_ORG_ID="123456789@AdobeOrg" #OrgID
export ADB_TECH_ACC_ID="abcdefg@techacct.adobe.com" #Tech Account ID
export ADB_CLIENT_ID="0987654321" #client ID
export ADB_CLIENT_SECRET="1234-5678-abcd-efgh" #client secret

# エクスポート設定
export RSID="exturexturecom"
export VAR="trackingcode"
export EMAIL="exture@example.com"
export DATE_START="2010-01-01"
export DATE_END="2020-12-31"

# ファイル名定義
export SAINT_JSON="saint.json"
export SAINT_TXT="saint.txt"
export LOAD_TXT="load.txt"
##設定ここまで##

# 空ファイル作成
: > ${SAINT_JSON}
: > ${SAINT_TXT}
: > ${LOAD_TXT}

export TOKEN=$(node token.js)

# job作成
export JOB_ID=$(node exec_saint_api.js "CreateExport")
echo "JOB_ID: ${JOB_ID}"

# status確認
sleep 60
export FILE=$(node exec_saint_api.js "GetStatus")
echo "FILE_ID: ${FILE%,*}"
echo "PAGE_NUM: ${FILE#*,}"

# download
node exec_saint_api.js "GetExport"

#jqでJSONをCSV変換
cat ${SAINT_JSON} |jq -r '.[]|.data[]|.row|@csv' > ${SAINT_TXT}

何をやってるかと言うと、まずAdobeI/Oのコンソールで作成したAPI実行に必要なJWT認証情報を環境変数として定義してます。
これらは全てAdobeI/Oコンソールから作成・取得出来ます。

続いて、SAINT分類データの取得に必要なAdobeAnalyticsのレポートスイートIDや変数名、通知先メアドなどを環境変数に持たせます。

出力するファイル名も環境変数で定義してあります。

そしてこのbashスクリプトを実行すると、まずはtoken.jsを使ってJWT認証を行ってトークンを取得します。

このトークンを使って、SAINT分類データのエクスポートジョブの作成から分類データの取得までをget_saint_api.jsが実行してます。

JSONファイルをCSV変換する

APIで取得した分類データはJSON形式になってます。
そのままではExcelやエディタで編集出来ないので、jqコマンドを使ってCSVに変換してます。

jqコマンドは以前↓の記事でも使いましたが、JSONを操作するためのLinuxコマンドです。

Linux Tips: コマンドラインでJSONをCSVに変換する

とても便利なので使い方を覚えると役に立ちます。

CSVに変換したSAINT分類データはExcelで編集したり、またはAdobeAnalyticsのDatafeedと一緒にBigQueryにロードしてBIツールで分析に使うのも良いでしょう。
もちろんBigQuery以外のデータウェアハウスに入れてもよいですし。

TL;DR

AdobeAnalyticsのSAINT分類データを取得するために、AdobeI/OのAPIを実装する方法について紹介しました。
AdobeI/OのAPIではJWT認証を使います。
また、APIで取得したJSONデータはCSVに変換すると扱いやすくなります。

あと、どうでも良いんですけど今はもう「SAINT」って言わずにただの「分類」って言うみたいですね。
どうでも良いです。

弊社では、Adobe Analytics認定エキスパート資格・Google Cloud認定プロフェショナルデータエンジニア資格・Linux Professional Institute認定資格を持ったエンジニア達が各種マーテックツールの導入実装コンサルティングサービスや、GCP/AWS/Azureなどのパブリッククラウドを使ったデータ分析基盤構築コンサルティングサービスを提供しております。

お問い合わせはこちらからどうぞ。