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レスポンスを処理
// ...

コメントを残す