Yellowfin PHP + REST API でグループメンバーをまとめて追加

## はじめに
Yellowfin の REST API 経由で、グループメンバーをまとめて追加する PHP プログラムを紹介します。

グループメンバーを追加するにあたり、グループ ID とユーザー ID の情報が必要となります。これら ID 情報の取得に関しては、[『Yellowfin 情報参照プログラム PHP + REST API でロール / ユーザー / グループなどの情報を取得』](https://qiita.com/ExtremeCarvFJ/items/0d3d9005b03e917ad839) の記事に説明があります。事前に目を通しておいてください。

## 追加するグループメンバー情報の準備
追加するグループメンバー情報を、下記例のように JSON の形式で記述します。各項目の詳細に関しては、開発者ドキュメントの [Bulk-add one or more members to this group](https://developers.yellowfinbi.com/dev/api-docs/current/#operation/bulkAddUserGroupMembers) の個所で詳細を確認してください。
ユーザーを個々に指定して登録する場合は、entityType に PERSON を、eitityId にユーザー ID をそれぞれ指定します。membershipType を INCLUDED と指定することで、該当ユーザーがグループメンバーに含まれるようになります。

```json:members.json
[
	{
		"entityType": "PERSON",
		"entityId": "13210",
		"membershipType": "INCLUDED"
	},
	{
		"entityType": "PERSON",
		"entityId": "13212",
		"membershipType": "INCLUDED"
	}
]
```

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

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

```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;
```

## グループメンバー追加
先の手順で取得したトークンを用いて、POST でグループメンバーをまとめて追加します。HEADER や BODY に必要な情報に関しては、開発者用ドキュメントの [Bulk-add one or more members to this group](https://developers.yellowfinbi.com/dev/api-docs/current/#operation/bulkAddUserGroupMembers) の個所で詳細を確認してください。
URL の一部に、対象グループのグループ ID を指定する必要があります。
以下のサンプルコードでは、作成した HEADER 情報と読み込んだグループメンバー情報を使って、curl で追加処理を行っています。

```php:グループメンバー追加
//変数の宣言
$groupId = '13173';
$url3 = 'http://localhost:8880/api/user-groups/'.$groupId.'/members/';

//メンバー追加：HEADERデータ作成
$header3 = array(
	'Authorization:YELLOWFIN ts='.$time.', nonce=123, token='.$accessToken,
	'Accept:application/vnd.yellowfin.api-v2+json',
	'Content-Type:application/json;charset=UTF-8'
);

//メンバー追加：メンバーデータ読み込み
ob_start();
include("members.json");
$memberData = ob_get_clean();

//メンバー追加：グループにメンバー追加
$ch3 = curl_init();
curl_setopt($ch3, CURLOPT_HTTPHEADER, $header3);
curl_setopt($ch3, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch3, CURLOPT_POSTFIELDS, $memberData);
curl_setopt($ch3, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch3, CURLOPT_URL, $url3);
$result3 =curl_exec($ch3);
curl_close($ch3);
```

## グループメンバー追加プログラム全容
グループメンバー追加プログラムの全容は以下の通りです。
```php:addMembers.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;

$groupId = '13173';
$url3 = 'http://localhost:8880/api/user-groups/'.$groupId.'/members/';

//メンバー追加：HEADERデータ作成
$header3 = array(
	'Authorization:YELLOWFIN ts='.$time.', nonce=123, token='.$accessToken,
	'Accept:application/vnd.yellowfin.api-v2+json',
	'Content-Type:application/json;charset=UTF-8'
);

//メンバー追加：メンバーデータ読み込み
ob_start();
include("members.json");
$memberData = ob_get_clean();

//メンバー追加：グループにメンバー追加
$ch3 = curl_init();
curl_setopt($ch3, CURLOPT_HTTPHEADER, $header3);
curl_setopt($ch3, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch3, CURLOPT_POSTFIELDS, $memberData);
curl_setopt($ch3, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch3, CURLOPT_URL, $url3);
$result3 =curl_exec($ch3);
curl_close($ch3);
```

コンソールからプログラムを実行します。
```powershell:php 実行
PS> php addMembers.php
```

該当グループのメンバーが追加されていることが確認できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2128512/382d9e86-a62f-8c9c-bd07-6f3cc8ec2f90.png)


## 最後に
[ユーザー登録](https://qiita.com/ExtremeCarvFJ/items/1ddf337a6b24a948dc1e)に続いて、グループメンバー登録のサンプルプログラムを作成してみました。
今後も、基本的な処理のサンプルコードを、継続的に提供していこうと思います。
何はともあれ、皆様、良いデータ分析を! See you then! Cheers! Santé! Skål!