はじめに

Yellowfin の REST API 経由でユーザーをまとめて登録する場合や、グループメンバーをまとめて追加する場合などに、ID を指定して処理を実行する場面があります。具体的には、ユーザー ID、グループ ID、ロール IDなどの情報が必要となります。
本記事の中では、PHP のプログラムから REST API を呼び出して、これら情報を取得する方法を紹介します。

REST API 開発者用ドキュメントと動作検証

Yellowfin の REST API に関する詳細な情報は、開発者用ドキュメントに記述があります。ただ、必ずしも分かりやすい記述内容ではないので、ドキュメントの内容を理解できるようになるになるためには少々慣れが必要です。そのため、まずは本記事などを参考にしながら、REST API の使い方の概要をご理解いただければと思います。

本来であれば、いきなりプログラムを記述し始めるよりも、まずはブラウザのディベロッパーツールなどで、リクエストする情報と、レスポンスの情報が正しいか否かを確認するのが良いと思います。Chrome の場合だと、API Tester が該当します。本記事に登場するプログラムに関しても、全て API Tester で動作を確認してから、プログラムの作成を行いました。

アクセストークンの取得

Yellowfin のリソースにアクセスするために、2 種類のトークンを使用します。
1 つ目はリフレッシュトークンです。有効期限の無いトークンで、アクセストークンを取得するために必ず必要です。refresh-tokens API に対してリフレッシュトークンをPOSTで要求し取得します。
2 つ目はアクセストークンです。access-tokens API に対して入手済みのリフレッシュトークンを使って、POSTで要求し取得します。
アクセストークンの有効期限は 20 分間です。この間に、リソースにアクセスし、必要な処理を実施します。有効期限が切れたら、リフレッシュトークンを使ってアクセストークンを再入手します。

サンプルプログラムの中では、プログラムの処理が分かりやすいように、Admin の ID やパスワードはべた書きしています。その他 HEADER や BODY に必要な情報は、開発者ドキュメントの Creates a new refresh token と Gets an access token that can be used to access a resource の個所で詳細を確認してください。
下記プログラムの前半でリフレッシュトークンを取得し、後半でアクセストークンを取得しています。作成した HEADER や BODY 情報を使ってトークンを要求する処理には、curl を使っています。要求に対して返ってくるレスポンスの中から、アクセストークンを $accessToken 変数に取り込んでいます。

アクセストークン

//変数の宣言
$adminId = 'admin@yellowfin.com.au';
$adminPassword = 'test';
$time = ceil(microtime(true)*1000);
$url = 'http://localhost:8080/api/refresh-tokens';
$url2 = 'http://localhost:8080/api/access-tokens';
$refreshToken = "";
$accessToken = "";

//リフレッシュトークン：HEADERデータ作成
$header = array(
    'Authorization:YELLOWFIN ts='.$time.', nonce=123',
    'Accept:application/vnd.yellowfin.api-v2+json',
    'Content-Type:application/json;charset=UTF-8'
);

//リフレッシュトークン：BODYデータ作成
$body = array(
    'userName'=>$adminId,
    'password'=>$adminPassword
);
$body_json = json_encode($body, JSON_PRETTY_PRINT);

//リフレッシュトークン：Yellowfinにトークンを要求
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $body_json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, $url);
$result = curl_exec($ch);
$json_result = json_decode($result);
$refreshToken = $json_result->securityToken;
curl_close($ch);

//アクセストークン：HEADERデータ作成
$header2 = array(
    'Authorization:YELLOWFIN ts='.$time.', nonce=123, token='.$refreshToken,
    'Accept:application/vnd.yellowfin.api-v2+json',
    'Content-Type:application/json'
);

//アクセストークン：Yellowfinにトークンを要求
$ch2 = curl_init();
curl_setopt($ch2, CURLOPT_HTTPHEADER, $header2);
curl_setopt($ch2, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch2, CURLOPT_POSTFIELDS, '');
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_URL, $url2);
curl_close($ch);
$result2 = curl_exec($ch2);
$json_result2 = json_decode($result2);
$accessToken=$json_result2->securityToken;

ロール情報の取得

先の手順で取得したトークンを用いて、ロールに関する情報を GET で取得します。HEADER に必要な情報に関しては、開発者用ドキュメントの Get a list of all roles の個所で詳細を確認してください。
作成した HEADER 情報を使ってロールに関する情報をリクエストする処理には、curl を使っています。また、リクエストに対して返ってくるレスポンスの中に、ロールの数分だけ items 要素が含まれます。items 数ループを回して、その中からロール名 (roleName) とロール ID (roleId) と抜き出して、両者をタブで接続しています。

ロール情報取得

$url3 = 'http://localhost:8080/api/roles/';

//ロール参照：HEADERデータ作成
$header3 = array(
    'Authorization:YELLOWFIN ts='.$time.', nonce=123, token='.$accessToken,
    'Accept:application/vnd.yellowfin.api-v2+json'
);

//ロール参照：Yellowfinからロール情報取得
$ch3 = curl_init();
curl_setopt($ch3, CURLOPT_URL, $url3);
curl_setopt($ch3, CURLOPT_HTTPHEADER, $header3);
curl_setopt($ch3, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch3, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch3, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch3, CURLOPT_RETURNTRANSFER, true); 
$result3 = curl_exec($ch3);
$result3_json = json_decode($result3, true);
curl_close($ch3);

//取得した情報の確認
$i=0;
foreach($result3_json["items"] as $value) {
    $userInfo=$result3_json["items"][$i]["roleName"].'|'.$result3_json["items"][$i]["roleCode"]."\n";
    echo($userInfo);
    $i++;
}

ロール情報取得プログラム全容

ロール情報取得プログラムの全容は以下の通りです。

rolesInfo.php

//変数の宣言
$adminId = 'admin@yellowfin.com.au';
$adminPassword = 'test';
$time = ceil(microtime(true)*1000);
$url = 'http://localhost:8080/api/refresh-tokens';
$url2 = 'http://localhost:8080/api/access-tokens';
$refreshToken = "";
$accessToken = "";

//リフレッシュトークン：HEADERデータ作成
$header = array(
    'Authorization:YELLOWFIN ts='.$time.', nonce=123',
    'Accept:application/vnd.yellowfin.api-v2+json',
    'Content-Type:application/json;charset=UTF-8'
);

//リフレッシュトークン：BODYデータ作成
$body = array(
    'userName'=>$adminId,
    'password'=>$adminPassword
);
$body_json = json_encode($body, JSON_PRETTY_PRINT);

//リフレッシュトークン：Yellowfinにトークンを要求
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $body_json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, $url);
$result = curl_exec($ch);
$json_result = json_decode($result);
$refreshToken = $json_result->securityToken;
curl_close($ch);

//アクセストークン：HEADERデータ作成
$header2 = array(
    'Authorization:YELLOWFIN ts='.$time.', nonce=123, token='.$refreshToken,
    'Accept:application/vnd.yellowfin.api-v2+json',
    'Content-Type:application/json'
);

//アクセストークン：Yellowfinにトークンを要求
$ch2 = curl_init();
curl_setopt($ch2, CURLOPT_HTTPHEADER, $header2);
curl_setopt($ch2, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch2, CURLOPT_POSTFIELDS, '');
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_URL, $url2);
curl_close($ch);
$result2 = curl_exec($ch2);
$json_result2 = json_decode($result2);
$accessToken=$json_result2->securityToken;

//変数の宣言
$url3 = 'http://localhost:8080/api/roles/';

//ロール参照：HEADERデータ作成
$header3 = array(
    'Authorization:YELLOWFIN ts='.$time.', nonce=123, token='.$accessToken,
    'Accept:application/vnd.yellowfin.api-v2+json'
);

//ロール参照：Yellowfinからロール情報取得
$ch3 = curl_init();
curl_setopt($ch3, CURLOPT_URL, $url3);
curl_setopt($ch3, CURLOPT_HTTPHEADER, $header3);
curl_setopt($ch3, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch3, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch3, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch3, CURLOPT_RETURNTRANSFER, true); 
$result3 = curl_exec($ch3);
$result3_json = json_decode($result3, true);
curl_close($ch3);

//取得した情報の確認
$i=0;
foreach($result3_json["items"] as $value) {
    $userInfo=$result3_json["items"][$i]["roleName"].'|'.$result3_json["items"][$i]["roleCode"]."\n";
    echo($userInfo);
    $i++;
}

プログラムを実行すると、以下のような情報がコンソール上に表示されます。
各行の一番右側にアルファベット大文字で表示されているのが、ロール ID です。

php 実行

PS > php rolesInfo.php
Consumer & Collaborator YFREPORTCONSUMER
Personal Content Writer & Collaborator  YFREPORTWRITER
Public Content Writer & Collaborator    YFCORPWRITER
Public Content Writer & Collaborator - Advanced PUBLICCONTENTWRITERCOLLABORATORADVANCED
System Administrator    YFADMIN

ユーザー情報やグループ情報の取得

同様の流れで、ユーザー情報やグループ情報などを取得することも可能です。
それぞれの詳細は、開発者用ドキュメントの以下の個所で詳細をご確認ください。
・ Gets a list of available users
・ Get a list of available user groups

ユーザー情報取得プログラム全容

//変数の宣言
$adminId = 'admin@yellowfin.com.au';
$adminPassword = 'test';
$time = ceil(microtime(true)*1000);
$url = 'http://localhost:8080/api/refresh-tokens';
$url2 = 'http://localhost:8080/api/access-tokens';
$refreshToken = "";
$accessToken = "";

//リフレッシュトークン：HEADERデータ作成
$header = array(
	'Authorization:YELLOWFIN ts='.$time.', nonce=123',
	'Accept:application/vnd.yellowfin.api-v2+json',
	'Content-Type:application/json;charset=UTF-8'
);

//リフレッシュトークン：BODYデータ作成
$body = array(
	'userName'=>$adminId,
	'password'=>$adminPassword
);
$body_json = json_encode($body, JSON_PRETTY_PRINT);

//リフレッシュトークン：Yellowfinにトークンを要求
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $body_json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, $url);
$result = curl_exec($ch);
$json_result = json_decode($result);
$refreshToken = $json_result->securityToken;
curl_close($ch);

//アクセストークン：HEADERデータ作成
$header2 = array(
	'Authorization:YELLOWFIN ts='.$time.', nonce=123, token='.$refreshToken,
	'Accept:application/vnd.yellowfin.api-v2+json',
	'Content-Type:application/json'
);

//アクセストークン：Yellowfinにトークンを要求
$ch2 = curl_init();
curl_setopt($ch2, CURLOPT_HTTPHEADER, $header2);
curl_setopt($ch2, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch2, CURLOPT_POSTFIELDS, '');
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_URL, $url2);
curl_close($ch);
$result2 = curl_exec($ch2);
$json_result2 = json_decode($result2);
$accessToken=$json_result2->securityToken;

//変数の宣言
$url3='http://localhost:8080/api/admin/users';

//ユーザー参照：HEADERデータ作成
$header3 = array(
	'Authorization:YELLOWFIN ts='.$time.', nonce=123, token='.$accessToken,
	'Accept:application/vnd.yellowfin.api-v2+json'
);

//ユーザー参照：Yellowfinからユーザー情報取得
$ch3 = curl_init();
curl_setopt($ch3, CURLOPT_URL, $url3);
curl_setopt($ch3, CURLOPT_HTTPHEADER, $header3);
curl_setopt($ch3, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch3, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch3, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch3, CURLOPT_RETURNTRANSFER, true); 
$result3 = curl_exec($ch3);
$result3_json = json_decode($result3, true);
$i=0;
curl_close($ch3);

//取得した情報の確認
foreach($result3_json["items"] as $value) {
	$userInfo=$result3_json["items"][$i]["ipId"].", ";
	$userInfo=$userInfo.$result3_json["items"][$i]["userId"].", ";
	$userInfo=$userInfo.$result3_json["items"][$i]["lastName"].", ";
	$userInfo=$userInfo.$result3_json["items"][$i]["firstName"].", ";
	$userInfo=$userInfo.$result3_json["items"][$i]["roleCode"].",⁻";
	$userInfo=$userInfo.$result3_json["items"][$i]["status"]."\n";
	echo($userInfo);
	$i++;
}

グループ情報取得プログラム全容

//変数の宣言
$adminId = 'admin@yellowfin.com.au';
$adminPassword = 'test';
$time = ceil(microtime(true)*1000);
$url = 'http://localhost:8080/api/refresh-tokens';
$url2 = 'http://localhost:8080/api/access-tokens';
$refreshToken = "";
$accessToken = "";

//リフレッシュトークン：HEADERデータ作成
$header = array(
	'Authorization:YELLOWFIN ts='.$time.', nonce=123',
	'Accept:application/vnd.yellowfin.api-v2+json',
	'Content-Type:application/json;charset=UTF-8'
);

//リフレッシュトークン：BODYデータ作成
$body = array(
	'userName'=>$adminId,
	'password'=>$adminPassword
);
$body_json = json_encode($body, JSON_PRETTY_PRINT);

//リフレッシュトークン：Yellowfinにトークンを要求
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $body_json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, $url);
$result = curl_exec($ch);
$json_result = json_decode($result);
$refreshToken = $json_result->securityToken;
curl_close($ch);

//アクセストークン：HEADERデータ作成
$header2 = array(
	'Authorization:YELLOWFIN ts='.$time.', nonce=123, token='.$refreshToken,
	'Accept:application/vnd.yellowfin.api-v2+json',
	'Content-Type:application/json'
);

//アクセストークン：Yellowfinにトークンを要求
$ch2 = curl_init();
curl_setopt($ch2, CURLOPT_HTTPHEADER, $header2);
curl_setopt($ch2, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch2, CURLOPT_POSTFIELDS, '');
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_URL, $url2);
curl_close($ch);
$result2 = curl_exec($ch2);
$json_result2 = json_decode($result2);
$accessToken=$json_result2->securityToken;

//変数の宣言
$url3='http://localhost:8080/api/user-groups';

//グループ参照：HEADERデータ作成
$header3 = array(
	'Authorization:YELLOWFIN ts='.$time.', nonce=123, token='.$accessToken,
	'Accept:application/vnd.yellowfin.api-v2+json'
);

//グループ参照：Yellowfinから情報取得
$ch3 = curl_init();
curl_setopt($ch3, CURLOPT_URL, $url3);
curl_setopt($ch3, CURLOPT_HTTPHEADER, $header3);
curl_setopt($ch3, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch3, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch3, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch3, CURLOPT_RETURNTRANSFER, true); 
$result3 = curl_exec($ch3);
$result3_json = json_decode($result3, true);

curl_close($ch3);

//取得した情報の確認
$i=0;
foreach($result3_json["items"] as $value) {
    echo($result3_json["items"][$i]["userGroupId"]."\t".$result3_json["items"][$i]["shortDescription"]."\n");
	$i++;
}

最後に

Yellowfin REST API の仕様に関する詳細な説明は、開発者用ドキュメントに詳しく記述されています、しかし、同ドキュメントを参照して、実際のコードに落とすのには少々手間がかかりますよね。ドキュメントの情報を補完するサンプルコードなどは、もう少し整備が必要かと思っています。Qiita などを使って、必要な情報を補完し、皆さんの運用を効率化できるお手伝いができればと思っています。
何はともあれ、皆様、良いデータ分析を! See you then! Cheers! Santé! Skål!