Aspera on Cloud APIのusage_reportsから取得できるデータ特性を解説
投稿者：平間 博
こんにちは。
私たちIntegrationチームはシステム/アプリケーションを統合するソリューションエンジニアであり、API、メッセージ・データ、ファイルを使った様々なデータソースやアプリケーションの統合において、製品の選定から設計・構築、そして導入後のサポートを行っております。
このBlogでは、Aspera on Cloud APIを使ってファイル転送量に関する統計データを取得する方法とデータの取り扱い方について解説します。
Aspera on Cloudは転送量ベースサブスクリプションライセンスであるため、利用推移をトレースすることは契約者に取って重要なアクティビティとなります。
しかし、トレースするためにはAspera on Cloudへログインして利用率のダッシュボードを目視確認する必要があり、アナログ的な対応が求められます。
そこで、Aspera on Cloud API※が提供する「usage_reports」を使って監視などの運用スキームに消費動向をトラックする方法が有効であるため、APIの使い方とAPIを通して取得されるデータの特性をお伝えします。
APIの使い方は、以下のコードサンプルを御確認ください。トークンの取得方法は「Aspera APIを使った独自レポート生成方法のご紹介」を参考にしてください。
●APIコールのサンプル(Node.js)
async function listReports( token ) {
const options = {
hostname: 'api.ibmaspera.com',
path: '/api/v1/usage_reports',
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer ' + token
}
}
return new Promise( ( (resolve, reject) => {
let req = https.request( options, ( res ) => {
if ( !res.statusCode.toString( '10' ).match( /2\d\d/ ) ) {
writeErrorlogs("レポートデータを取得できません。資格情報、通信経路の状態を確認してください。")
return
}
let body = ''
res.on( 'data', ( chunk ) => {
body += chunk
})
res.on( 'end', () => {
resolve( body )
})
}).on( 'error', (e) => {
reject( e.message )
writeErrorlogs("レポートデータを取得できません。資格情報、通信経路の状態を確認してください。")
})
req.end()
}))
}
サンプルが示すAPIのURLは、「https://hostname/path」からなりますが、これはAPIリファレンスと異なっています。これはAPIリファレンスで示されるURLは恐らくURLリライトがかかることが前提のようですが、現状ではコールできません。APIの利用を検討される場合、APIのエンドポイントについてはIBM Supportへ確認するか、当Blogのように実績を調査することを推奨します。
Aspera on Cloud APIの「usage_reports」から取得されるデータ形態は、以下のデータフォーマットになっています。
●データフォーマット
{
"node_id": "1",
"reporting_period_bytes": 1024,
"reporting_period_bytes_in": 512,
"reporting_period_bytes_out": 512,
"total_bytes": 2048,
"total_bytes_in": 1024,
"total_bytes_out": 1024,
"updated_at": "2019-06-18T21:46:36.000Z",
"workspace_id": "2"
}
実際に取得する場合、月毎に分割されたデータ群(配列)が返されます。
ただし、Standard+エディション以上ではノードとワークスペースが複数存在することもあるため、更にデータはノード別、そしてワークスペース別に分割されます。このため、月当たりの消費動向を求める場合は、以下のように集計していきます。
ノードの転送量 = 当該ノードが管理するワークスペースで生じた転送量の集計
月間の転送量 = 当該月の全ノードの転送量の集計
この時に注意が必要なのは、契約者によるノードやワークスペースが削除可能である点です。
ノードやワークスペースが削除されても「usage_reports」より提供されるデータ群から実績が消失することはありませんが、ノードリストやワークスペースリストをAPIから取得して突合している場合、リストに登場しないノードIDやワークスペースIDが「usage_reports」より提供されるデータ群に出現するため、転送量の集計から漏れることがあり得ます。
そうした例外対応に配慮したコードサンプルを以下に示します。
●集計処理のサンプル(Node.js)
async function main() {
let token = JSON.parse(await generateToken(req_options, req_data)).access_token
let org_info = JSON.parse( await getMyOrganization(token) )
let org_id = org_info.url_id
let org_name = org_info.name
let org_plan = org_info.tier
let lst_nodes = JSON.parse( await listNodes(token) )
let lst_workspaces = JSON.parse( await listWorkspaces(token) )
let lst_reports = JSON.parse( await listReports(token) )
var nodes = {}
var workspaces = {}
var transmit_info_bynode = {}
let all_node_transmit = 0
let all_node_transmit_in = 0
let all_node_transmit_out = 0
var total_transmit_info = {}
lst_nodes.forEach( function( value ) {
nodes[value.id] = value.name
});
lst_workspaces.forEach( function( value ) {
workspaces[value.id] = value.name
});
lst_reports.forEach( async function( value, i ) {
let n_idx = value.node_id
let w_idx = value.workspace_id
let node_name = ''
let workspace_name = ''
if( nodes[n_idx] ) {
node_name = nodes[n_idx]
} else {
node_name = '削除済みノード'
}
if( workspaces[w_idx] ) {
workspace_name = workspaces[w_idx]
} else {
workspace_name = '削除済みワークスペース'
}
let using_flag = await isNewRecord( lst_reports, n_idx, w_idx, i, value.updated_at )
if ( using_flag ) {
let key = node_name + ' used by ' + workspace_name
if ( key in transmit_info_bynode ) {
transmit_info_bynode[key]['volume'] += value.total_bytes
transmit_info_bynode[key]['volume_in'] += value.total_bytes_in
transmit_info_bynode[key]['volume_out'] += value.total_bytes_out
} else {
transmit_info_bynode[key] = {}
transmit_info_bynode[key]['volume'] = value.total_bytes
transmit_info_bynode[key]['volume_in'] = value.total_bytes_in
transmit_info_bynode[key]['volume_out'] = value.total_bytes_out
transmit_info_bynode[key]['node'] = node_name
transmit_info_bynode[key]['workspace'] = workspace_name
}
all_node_transmit += value.total_bytes
all_node_transmit_in += value.total_bytes_in
all_node_transmit_out += value.total_bytes_out
}
});
let conditions = await checkConstract( all_node_transmit, all_node_transmit_out )
total_transmit_info['volume'] = all_node_transmit
total_transmit_info['volume_in'] = all_node_transmit_in
total_transmit_info['volume_out'] = all_node_transmit_out
sendHTMLEmail( org_name, org_plan, total_transmit_info, conditions, transmit_info_bynode )
}
以上、Aspera on Cloud APIが提供する「usage_reports」を使った転送データの取得と集計方法について説明しました。
今後もAsperaに関する情報発信を企画し、お届けしていきます。
※ Aspera on Cloud APIリファレンス
https://developer.ibm.com/apis/catalog/aspera–aspera-on-cloud-api/Introduction
