APIを使ってみよう
技術解説
APIを使ってみよう
Sigme(xibo)のAPIとは
Sigme-cmsには非常に強力なAPI(Application Programing Interface)が用意されています。これにより、Sigme-CMSを外部アプリケーションから制御し、さまざまな処理を実行することが可能です。CMSで操作するほぼ全ての操作がAPIから実行可能です。
実装されているAPIの仕様はこちらから確認できます。
OAuth2.0に準拠したアクセス制御
Sigme-cms(Xibo-cms)のAPIはOAuth2.0の認証により、不正なアクセスがされないように保護されています。
OAuth 2.0には複数の認証手順が標準化されており、Sigme-cms(Xibo-cms)では以下の2種類の認証がサポートされています。
- 認可コードフロー
- クライアント・クレデンシャルズフロー
認可コードフロー
RFC 6749, 4.1. Authorization Code Grant で定義されているフローです。認可エンドポイントに認可リクエストを投げ、応答として短命の認可コードを受けとり、その認可コードをトークンエンドポイントでアクセストークンと交換するフローです。
APIを発行するアプリケーションが事前にユーザー認証を行っていない場合は、このフローによりアプリケーションのユーザー認証を行います。
クライアント・クレデンシャルズフロー
RFC 6749, 4.4. Client Credentials Grant で定義されているフローです。トークンエンドポイントにトークンリクエストを投げ、応答としてアクセストークンを受け取るフローです。このフローでは、ユーザーの認証はおこなわれず、クライアントアプリケーションの認証のみがおこなわれます。
すでにアプリケーションのユーザー認証が行われている場合は、この認証手順がシンプルです。
ただし、クライアントIDとクライアント・シークレットは事前に決定した固定の値となりますので、この値が漏洩しないように十分注意する必要があります。
OpenID Connect(OIDC)による認証
OpenID Connectとは、サービス間で、利用者の同意に基づきID情報を流通するための標準仕様です。上記各認証の動画ではA-Cの手順になります。Sigme-cms(Xibo-cms)では、認可サーバーがCMSに内蔵されているため、この手順は必要ありません。
クライアント・クレデンシャルズによる認可手順
ここでは、クライアント・クレデンシャルズによる認可とCMSのAPIへのアクセス手順を、具体例で解説します。ほとんどのケースで、アプリケーションはすでにユーザー認証が行われていると考えられるため、クライアント・クレデンシャルズによる認可の手順を解説します。
以下のサンプルコードは、Guzzleライブラリを利用し、xibo-cmsサーバーからAccessTokenを取得し、そのAccessTokenを使いCMSの時間を取得するAPI(clock)を呼び出して、CMSの時間を取得しています。
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$baseUri = 'https://<your subdomain>.cloud-signage.net'; // XiboサーバーのURLを指定
$clientId = '<client ID>'; // Xiboで登録したOAuthクライアントのIDを指定
$clientSecret = '<client secret> '; // Xiboで登録したOAuthクライアントのシークレットを指定
// Guzzleクライアントの作成
$client = new Client([
'base_uri' => $baseUri,
]);
// OAuth 2.0のクライアントクレデンシャルフローを実行
$response = $client->post('api/authorize/access_token', [
'form_params' => [
'grant_type' => 'client_credentials',
'client_id' => $clientId,
'client_secret' => $clientSecret,
],
]);
// レスポンスのJSONをデコード
$data = json_decode($response->getBody(), true);
// アクセストークンを取得
$accessToken = $data['access_token'];
// APIリクエストのヘッダーにアクセストークンを追加
$headers = [
'Authorization' => 'Bearer ' . $accessToken,
'Content-Type' => 'application/json',
];
// 例:自分のデータを取得するAPIリクエスト
$response = $client->get('api/clock', [
'headers' => $headers,
]);
// レスポンスのJSONをデコード
$data = json_decode($response->getBody(), true);
// 表示
echo('<pre>');
var_dump($data);
echo('</pre>');
?>
phpからGETやPOSTなどのリクエストを送信するため、ここでは、Guzzleというライブラリを使用しています。
事前に、以下のコマンドで、Guzzleをインストールしておく必要があります。
$ composer require guzzlehttp/guzzle
$baseUriはCM Sのベースアドレスです。
$clientIdと$clientSecretは、CMSにアプリケーションを登録すると取得できます。CMSにログインして、[管理]から[アプリケーション]を選択します。アプリケーション画面の右上にある[アプリケーションを追加]ボタンを押すと、アプリケーション名を入力することができます。
追加するアプリケーション名を入力すると、以下の画面が表示され、クライアントIDとクライアントシークレットが表示されます。
api/authorize/access_tokenにこの情報をPOSTすると、認可サーバーから$accessTokenが得られます。このアクセストークンをBearer認証のパラメータとして、APIにアクセスします。
サンプルコードの実行結果は、
array(1) {
["time"]=>
string(9) "22:12 JST"
}
とJSON形式で得られ、CMSサーバーの時刻を確認できます。
この例では、GETメソッドによるデータ取得を紹介していますが、POSTメソッドの場合は、
// POSTデータを指定(連想配列として)
$data = [
'key1' => 'value1',
'key2' => 'value2',
];
$response = $client->post('api/layout', [
'headers' => $headers,
'json' => $data
]);
POSTするデータを連想配列で指定して、$client->post()を呼び出します。
スコープの設定
APIから操作できる範囲をスコープといいます。これによりAPIから制御できる機能を制限することができます。セキュリティを強化する上でも、必要以外のAPIを起動できないように設定することをお勧めします。
[管理]->[アプリケーション]を起動し、アプリケーション編集ウィザードで、スコープを設定できます。
Full account accessを指定すると全てのAPIが利用可能になります。必要に応じて設定します。
まとめ
APIを利用することにより、新しいサイネージの利用の可能性が大きく広がります。
例えば、現在を気温をリアルタイムに表示したい場合には、アプリケーションからリアルタイムに気温情報を送り込み、表示することが可能になります。
データセットウェジットを配置し、そのデータをリアルタイムにAPIを使い更新することで、実現できます。
なお、更新したデータを即時に反映させるためには、XMRが有効になっている必要があります。
XMRに関しては、こちらのブログを参照してください。
アイデア次第で、今までにないデジタルサイネージを構築できます。
APIを利用して、新たなサイネージ機能をぜひ実現してください。
参考情報
今回はクライアント・クレデンシャルズでの認証を解説しましたが、認可コードフローでの実装の参考コードを掲載しておきます。
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
// Xibo APIのエンドポイントURL
$api_url = 'https://your_xibo_domain/api/';
// OAuth 2.0認証用のクライアント情報
$client_id = 'your_client_id';
$client_secret = 'your_client_secret';
$redirect_uri = 'your_redirect_uri';
$scope = 'your_scopes'; // 必要に応じてスコープを指定
// ユーザーに認証リンクを提供するURL
$auth_url = $api_url . 'oauth/authorize?' .
'client_id=' . $client_id .
'&redirect_uri=' . $redirect_uri .
'&response_type=code' .
'&scope=' . $scope;
// ユーザーに認証リンクを提供し、認証を行わせる
// ...
// ユーザーが認証コードを取得したと仮定
$auth_code = 'user_obtained_auth_code';
// アクセストークンの取得
$client = new Client();
$response = $client->post($api_url . 'oauth/token', [
'form_params' => [
'grant_type' => 'authorization_code',
'client_id' => $client_id,
'client_secret' => $client_secret,
'redirect_uri' => $redirect_uri,
'code' => $auth_code,
],
]);
$data = json_decode($response->getBody()->getContents(), true);
$access_token = $data['access_token'];
// アクセストークンを使ってAPIリクエストを送信
$headers = [
'Authorization' => 'Bearer ' . $access_token,
];
$response = $client->get($api_url . 'your_endpoint', [
'headers' => $headers,
]);
$data = json_decode($response->getBody()->getContents(), true);
// APIレスポンスを処理
// ...