まだプログラマーですが何か?

プログラマーネタとアスリートネタ中心。たまに作成したウェブサービス関連の話も http://twitter.com/dotnsf

タグ:api

IBM Cloud から提供されている NoSQL のマネージドデータベースである Cloudant (実体は Apache CouchDB)を便利に使っています。最大の特徴の一つが「無料でも一定条件下で使える」点ですが、今回は無料である以外の便利な使い方を紹介します。

この記事の中で紹介するのはこのような使いかたです:
(1) Cloudant の CORS を有効に設定する(特定ドメインのページからの REST API リクエストを受け付けて読み書きできるようにする)
(2) Github ページに用意したウェブページから (1) で有効に設定した Cloudant のデータを読み書きする


2021022401


最終的に実現したいのは、世の中の SaaS(といっていいのかな)の中でもかなり可用性高く、安定して動いている印象の Github ページを使ったウェブアプリケーションを作ることです。ただ静的ページそのものは安定して稼働していてもデータの読み書きが出来なければウェブアプリケーションとしては不十分で、そこを REST API で読み書きできる IBM Cloud の Cloudant データベースで賄えないか、と考えました。ただそのままでは CORS の制約もあって API が実行できないのですが、Cloudant 側の設定で CORS を正しく設定して Github ページからの読み書きを可能な状態にする、そのための Cloudant の設定手順を確認する、というのが目標です。

以下では Github のアカウントを持っている方を対象に、Github ページを使って作成するウェブページから Cloudant にアクセスするサンプルを紹介します。Github ページでなくても(静的ページのホスティング環境があれば)同様に可能なはずですが、その場合は適宜読み直してください(特に CORS 設定時のドメインなど)。


【CORS】
"Cross-Origin Resource Sharing" 、つまり「オリジン間リソース共有」の略語です。ここでの「オリジン」は「ドメイン」と読み替えたほうが理解しやすいかもしれまえん。

例えば A というウェブサーバーが https://aaa.com/ 上で、また B というデータベース・サーバーが https://bbb.net/ 上で動いていると仮定します(つまり全く別々に管理されている2つのサーバーです。この状態を Cross-Origin と呼びます)。A 上のウェブページで表示される画面の中で B から取得したデータを表示しようと思っています。

例えば A が Java などのプログラミング言語によって作られたアプリケーションサーバーであった場合、A は B からのデータ取得に Java を使うことになります。A の中で Java が実行され、B にアクセスしてデータを取り出し、その結果を使って A のページの画面を作成することができます。A の内部でプログラミング言語が使われている場合は、Cross-Origin であってもこのような方法でデータを取得することができます。

ところが A がアプリケーションサーバーではなく、ただの(既存の HTML ページを表示するだけの)ウェブサーバーであった場合、A から B にアクセスしてデータを取得する手段はかなり限られてしまいます。その限られた手段の1つが AJAX などに代表される JavaScript 処理です。A のサーバーにプログラミング言語が用意されていなくても、ウェブブラウザ自体が持つ JavaScript 実行環境を使って B サーバーにアクセスしてデータを取得する、という考え方です。ただし Cross-Origin の場合、A にアクセスしたウェブブラウザから B のサーバーに JavaScript で HTTP アクセスすることは原則できないことになっています(Cross-Origin でなければ、つまり A = B であれば可能です)。これが CORS の制約です。

CORS の制約はウェブブラウザが持っている制約なので、ウェブブラウザを使わない HTTP 通信(上述の Java 言語によるプログラミングによる通信など)には関係ありませんが、(ウェブブラウザの)利用者側でこの制約を解除する方法はありません。唯一の方法がリソース提供側(この場合だと B サーバー)による許可のみです。

今回のブログエントリは IBM Cloud のデータベースの1つである Cloudant の CORS をうまく設定することで、代表的な静的ウェブページの1つである Github ページから(Cloudant 内の)外部データを読み書きする方法について紹介する、というものです。


【Cloudant の用意】
まず IBM Cloud のアカウントを取得します。IBM Cloud アカウントを新規に取得した時点では「ライトアカウント」と呼ばれる無料の制約のあるアカウントとなります。今回紹介する作業を実行するだけであれば(ライトアカウントだとデータは 1GB までの格納となりますが、この容量などに問題なければ)ライトアカウントのまま実行いただいても構いません。

改めて取得したアカウントで IBM Cloud にログインし、「リソースの作成」ボタンクリック後に「Cloudant」を選択します:
2021022501

2021022502


インスタンス作成前にいくつか設定箇所があります。主なものは以下になりますが、"Authentification Method" だけはデフォルトの "IAM" ではなく "IAM and legacy credentials" を選択してください:
・Available Regions: インスタンスを作成するエリア、お好きな場所でいいが「東京」あたりが無難
・Authentification Method: 今回は必ず "IAM and legacy credentials" を選択
・Plan: 料金プラン。「Lite」であれば無料

最後に "Create" ボタンで作成します:
2021022503


Authentification Method について補足しておくと、デフォルトの "IAM" だといわゆる API キーを使った認証/認可を行います。ただ今回はアプリケーションサーバーからではなく(GitHub ページの)静的なページから Basic 認証を使ってデータベースの REST API を使うことを想定しています。この場合は "IAM" ではなく "IAM and legacy credentials" (API キーまたは Basic 認証を使う)を選択しておく必要があるためです。


少し待つと Cloudant インスタンスが起動済みになります。インスタンスを開いて「サービス資格情報」タブを選び、「新規資格情報」ボタンを押して資格情報を作成します。作成後に作成した資格情報(「サービス資格情報-1」のような名前になっていると思います)を選択・展開して、中身を確認します:
2021022504


資格情報の中身は以下のような内容の JSON 文字列になっているはずです(この中身は他人に見せないように注意してください):
{
  "apikey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "host": "xxxxxxxxxx-bluemix.cloudantnosqldb.appdomain.cloud",
  "iam_apikey_description": "Auto-generated for key xxxxxxxxxxxxxxxxxxx",
  "iam_apikey_name": "サービス資格情報-1",
  "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager",
  "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/xxxxxxxxxxxxxxxxxxxx::serviceid:ServiceId-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "password": "パスワード",
  "port": 443,
  "url": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-bluemix.cloudantnosqldb.appdomain.cloud",
  "username": "ユーザー名"
}

この情報のうち、後で必要になるのが以下の(赤字の)4つです。メモするか、コピペできるようにしておいてください:
キー意味補足
hostnameホスト名*******-bluemix.cloudantnosqldb.appdomain.cloud といった感じの文字列になっています(******* 部分が可変)
portポート番号443 で固定のはずです
usernameユーザー名ログイン時にこの2つの値が必要です
passwordパスワード


認証情報を確認したら、実際に Cloudant データベースのダッシュボードを見てみましょう。画面左のメニューから「管理」タブを選択し、右上の「Launch Dashboard」ボタンをクリックします:
2021022505


(初期状態では空の)ダッシュボード画面が表示されます。最初にアクセスした時点ではまだ何のデータベースも作成されていないため、下図のような画面になります。後述の作業のためのデータベースをここで1つ作成しておくことにします。画面右上の「Create Database」ボタンをクリックします:
2021022506


データベースを作成するメニューが画面右に表示されます。ここでは Database name に「mydb(異なる名前を指定しても構いませんが、その場合は後述のコマンド等を作成した名前に読み替えて実行してください)」、Partitioning は「Non-partitioned」を選択し、「Create」ボタンをクリックします:
2021022507


作成した mydb データベースが出来上がりました。このデータベースもまだデータが1件もないので、このような画面になります。一旦元の画面に戻るため、画面左上の "<" マークをクリックします:
2021022508


一つ前のデータベース一覧画面に戻りました。先程は空でしたが、作成したデータベースが1つ追加された画面になっているはずです:
2021022509


Cloudant 側の準備はいったんここまでできていればOKとします。 次に CORS のための設定を行います。


【Cloudant に CORS を設定する】
次に Cloudant に CORS の設定をして外部からのアクセスを許可します。ダッシュボードのメニューから「アカウント」(下から3番め)を選び、「CORS」タブを選択します。以下のような画面(「CORS は有効になっていて、外部のどこからのリクエストも受け付けない」という内容)になるはずです:
2021022501


画面下部の「Restrict to specific domains」欄にアクセスを許可するドメインの URL を指定して「Add Domain」ボタンで追加します。ここでは "https://(github のアカウント名).github.io/" を指定することで自分の Github ページからのアクセスを許可することになるので、自分の github アカウントに合わせて設定してください:
2021022502


このような画面になれば自分の github ページ用の CORS 設定ができたことになり、自分の github ページからは JavaScript で Cloudant データを読み書きできることになります:
2021022503


【Cloudant に初期データを入力する】
今回の紹介では Github ページから Cloudant のデータを REST API 経由で表示する(CORS の設定をしていれば取得できるはず)、ということを試してみます。そのための「表示するデータ」をあらかじめ Cloudant に入力しておきます。

もちろん(ダッシュボードから)自分で好きにデータを入力いただいても構いませんが、比較的簡単に動作を確認できるサンプルを用意しており、そこで対象とするデータを curl 一発でまとめて入力できるように準備しているのでこちらの方法を紹介します。

まず以下の URL からサンプルデータをダウンロード(表示後に右クリック→名前を付けて保存で "prefs.json" という名前で保存)してください:
https://raw.githubusercontent.com/dotnsf/cloudant_cors/main/prefs.json

2021022701


このファイルの中身は以下のようなフォーマットになっており、各都道府県庁所在地と、その位置情報が格納されています:
{
  "docs": [
    { "code": 1, "prefecture": "北海道", "capital": "札幌市", "geometry": { "type": "Point", "coordinates": [ 141.34694, 43.06417 ] } },
    { "code": 2, "prefecture": "青森県", "capital": "青森市", "geometry": { "type": "Point", "coordinates": [ 140.74, 40.82444 ] } },
    { "code": 3, "prefecture": "岩手県", "capital": "盛岡市", "geometry": { "type": "Point", "coordinates": [ 141.1525, 39.70361 ] } },
    { "code": 4, "prefecture": "宮城県", "capital": "仙台市", "geometry": { "type": "Point", "coordinates": [ 140.87194, 38.26889 ] } },
    { "code": 5, "prefecture": "秋田県", "capital": "秋田市", "geometry": { "type": "Point", "coordinates": [ 140.1025, 39.71861 ] } },
    { "code": 6, "prefecture": "山形県", "capital": "山形市", "geometry": { "type": "Point", "coordinates": [ 140.36333, 38.24056 ] } },
    { "code": 7, "prefecture": "福島県", "capital": "福島市", "geometry": { "type": "Point", "coordinates": [ 140.46778, 37.75 ] } },
    { "code": 8, "prefecture": "茨城県", "capital": "水戸市", "geometry": { "type": "Point", "coordinates": [ 140.44667, 36.34139 ] } },
    { "code": 9, "prefecture": "栃木県", "capital": "宇都宮市", "geometry": { "type": "Point", "coordinates": [ 139.88361, 36.56583 ] } },
    { "code": 10, "prefecture": "群馬県", "capital": "前橋市", "geometry": { "type": "Point", "coordinates": [ 139.06083, 36.39111 ] } },
    { "code": 11, "prefecture": "埼玉県", "capital": "さいたま市", "geometry": { "type": "Point", "coordinates": [ 139.64889, 35.85694 ] } },
    { "code": 12, "prefecture": "千葉県", "capital": "千葉市", "geometry": { "type": "Point", "coordinates": [ 140.12333, 35.60472 ] } },
    { "code": 13, "prefecture": "東京都", "capital": "新宿区", "geometry": { "type": "Point", "coordinates": [ 139.69167, 35.68944 ] } },
    { "code": 14, "prefecture": "神奈川県", "capital": "横浜市", "geometry": { "type": "Point", "coordinates": [ 139.6425, 35.44778 ] } },
      :
      :
  ]
}

このデータを先程作成した Cloudant 内の mydb データベースに格納します。curl コマンドを使うと以下のコマンド(※)で格納できます:
$ curl -u "username:password" -XPOST "https://host/mydb/_bulk_docs" -H "Content-Type: application/json" -d @prefs.json

username, password, host の値は上述で確認した以下の値を指定して入力してください:
 username: 上述の資格情報で確認した username の値
 password: 上述の資格情報で確認した password の値
 host: 上述の資格情報で確認した host の値


このコマンドが成功すると Cloudant の mydb データベースに47都道府県のデータが挿入されます。ダッシュボードから mydb データベースを選択すると以下のように 47 件のデータが表示されるようになります:
2021022702


試しにどれか1つ選択してみると、個々の内容を確認することも可能です(下図は北海道の例、"Cancel" で一覧に戻ります):
2021022703


ここまでの作業で Cloudant に Github ページからアクセスするための CORS を設定し、表示用のデータも格納できました。ではこのデータを Github ページから REST API 経由で取得して表示してみましょう。


【Github ページを用意する】
では実際に Github ページからクロスオリジンな Cloudant データベースに REST API 経由でアクセスできることを確認してみます。

まず Github にログインし、その後で以下のページにアクセスし、画面右上の "Fork" をクリックしてください:
https://github.com/dotnsf/cloudant_cors

2021022706


Fork 処理が成功すると、
 https://github.com/(あなたの github アカウント名)/cloudant_cors
というリポジトリができるはずです。

このリポジトリの Github ページを有効にします。リポジトリページの右上にある "Settings" をクリックします:
2021022707


画面を下に "GitHub Pages" と書かれている箇所までスクロールします。"Source" に "main" ブランチを指定して保存すると、"main" ブランチの内容がそのまま Github ページとして公開され、この中にある CORS の動作確認用に作った index.html を参照するための URL(https://(あなたの github アカウント名).github.io/cloudant_cors/)とそのリンクが表示されます(リンク先が有効になるまで1分程度かかります):
2021022708


少し待ってからリンク先にアクセスします。以下のような画面が表示されるはずです(Github ページなので、****.github.io というドメインのページになっていることを再確認してください):
2021022704


改めて資格情報から取得した値を画面内の各該当箇所に入力します。上にある横幅の大きなフィールドには host の値、その下は左から作成した DB 名(mydb)、username、password の値を入力します。最後に "Refresh" ボタンを押すと入力された情報を使ってこのページから AJAX で Cloudant へ REST API を実行して文書一覧を取得し、表形式で出力します。成功すると以下のように47都道府県の情報が(クロスオリジンの制約を乗り越えて)表示されます:
2021022705


以上、正しく設定することでクロスオリジンの壁を超えて Github ページから Cloudant のデータを利用することができました。Github も Cloudant も(一定制限の中で)無料で利用できるので、安定したウェブページを Github で運用しつつ、表示データを Cloudant から提供する、といった形で利用することができそうです。


なお、Cloudant(CouchDB) の REST API についての詳しくは、こちらのリファレンスを参照してください:
https://docs.couchdb.org/en/stable/api/index.html


なお、今回使った「特定データベース内の全文書を取得する」 REST API はこちらです:
GET /{db}/_all_docs

また準備段階で都道府県データをバルクインサートしましたが、その REST API はこちらで紹介されています:
POST /{db}/_bulk_docs


バックエンドの技術を使わずにウェブのフロントエンドだけで、つまり HTML と JavaScript だけで QR コードリーダーを作ることに挑戦してみました:
smartphone_qr_code


まずは完成品で実際の挙動を確認ください。PC またはスマホで(できればスマホで)こちらの URL にアクセスしてください:
https://dotnsf.github.io/web_qrcode/

2021012501



↑Github Pages で公開しているページなので、フロントエンドだけで作られていることがわかると思います。クロスオリジンな AJAX なども使ってないので、興味ある方はソースコードも確認してください。

「ファイルを選択」ボタンをクリックします。スマホの場合はカメラが起動するので QR コードを撮影してください。また PC の場合は画像選択ボックスが表示されるので、QR コードが撮影された画像を選択してください。

すると画面下部に画像が表示され、同時に画面内の QR コードが(存在していれば)解析され、解析結果の文字列データが表示されます:
2021012502


フロントエンドだけでここまでできるので、後は例えばこの結果が URL 文字列になっていれば、そのアドレスのページを開くこともできますし、テキストデータだけを読み取った上でバックエンドサーバーにデータを送信する、といったサーバーとの連携処理も容易に可能です。


【ソースコードの解説】
ソースコードはこちらで MIT ライセンスで公開しています(GitHub のウェブホスティングである Github Pages を使ってそのままサービスも公開しています):
https://github.com/dotnsf/web_qrcode

特にサービスの肝である index.html ファイルはこちらから参照いただけます。実質的にこの1ファイルだけでカメラ起動から撮影、QR コード解析まで実現しています:
https://github.com/dotnsf/web_qrcode/blob/main/index.html


まずスマホでカメラを起動するボタンの部分は以下の HTML コードで実現しています(PC ブラウザでこのボタンをクリックすると、保存済みの画像ファイルを選択するダイアログが表示されます):
<input type="file" accept="image/*" capture="camera" name="file" id="file-image"/>

type="file" で accept="image/*" capture="camera" 属性のついた <input> タグをクリックすると、カメラ内蔵機種の場合はそのカメラが起動し、撮影した画像を選択したことになります。(PCのなど)カメラ内蔵機種でない場合は普通にファイル選択画面になりますが、accept 属性により画像ファイルしか選択できません(要するにここで QR コードを撮影するか、QR コードが撮影された画像を選択することを想定しています)。

また jQuery を使った JavaScript によって以下の処理が画面ロード直後に実行されています:
var canvas = null;
var ctx = null;
$(function(){
  canvas = document.getElementById( 'mycanvas' );
  ctx = canvas.getContext( '2d' );

  var file_image = document.getElementById( 'file-image' );
  file_image.addEventListener( 'change', selectReadFile, false );
});


HTML 内下部に設置された <canvas> と、そのコンテキストを取得します(この <canvas> に画像が描画されることになりますが、その処理は後述します)。また上述の <input> タグの値が変化した時(=カメラで撮影するか、画像ファイルが選択された時)に selectReadFile() 関数が実行されるよう定義されています:
<div>
  <canvas id="mycanvas"></canvas>
</div>

したがってカメラで撮影するか画像ファイルを選択すると、以下の JavaScript コードが実行されます:
function selectReadFile( e ){
  var file = e.target.files;
  var reader = new FileReader();
  reader.onload = function(){
    readDrawImg( reader, canvas, 0, 0 );
  }
  reader.readAsDataURL( file[0] );
}

HTML5 の Filesystem API を使って撮影された画像ファイルを読み込み、その内容を上述で取得した <canvas> に描画するための関数 readDrawImg() が実行されます。つまり撮影した画像が画面内にも表示されるようになります。

readDrawImg() 関数および、この中で実行される多くの関数の中身は以下のようになっています:
function readDrawImg( reader, canvas, x, y ){
  var img = readImg( reader );
  img.onload = function(){
    var w = img.width;
    var h = img.height;
    printWidthHeight( 'src-width-height', true, w, h );

    // resize
    var resize = resizeWidthHeight( 1024, w, h );
    printWidthHeight( 'dst-width-height', resize.flag, resize.w, resize.h );
    drawImgOnCav( canvas, img, x, y, resize.w, resize.h );
  }
}

function readImg( reader ){
  var result_dataURL = reader.result;
  var img = new Image();
  img.src = result_dataURL;

  return img;
}

function drawImgOnCav( canvas, img, x, y, w, h ){
  canvas.width = w;
  canvas.height = h;
  ctx.drawImage( img, x, y, w, h );

  checkQRCode();
}

function resizeWidthHeight( target_length_px, w0, h0 ){
  var length = Math.max( w0, h0 );
  if( length <= target_length_px ){
    return({
      flag: false,
      w: w0,
      h: h0
    });
  }

  var w1;
  var h1;
  if( w0 >= h0 ){
    w1 = target_length_px;
    h1 = h0 * target_length_px / w0;
  }else{
    w1 = w0 * target_length_px / h0;
    h1 = target_length_px;
  }

  return({
    flag: true,
    w: parseInt( w1 ),
    h: parseInt( h1 )
  });
}

function printWidthHeight( width_height_id, flag, w, h ){
  var wh = document.getElementById( width_height_id );
  wh.innerHTML = '幅: ' + w + ', 高さ: ' + h;
}

まず readImg() 関数の中で Filesystem API を用いて画像ファイルを読み込み、その結果を Image オブジェクトの src 属性に代入します(これで Image オブジェクトを drawImgOnCav() 関数で <canvas> に表示すると読み込んだ画像が表示されます)。またこの結果から画像の幅および高さを取得して、画面内に元画像のサイズとして表示されます。

drawImgOnCav() 関数の最後に checkQRCode() 関数が実行されています。画像の <canvas> への描画終了後にこの関数が実行され、画像に QR コードが写っていたらその内容を解析して、データを取り出します:
function checkQRCode(){
  var imageData = ctx.getImageData( 0, 0, canvas.width, canvas.height );
  var code = jsQR( imageData.data, canvas.width, canvas.height );
  if( code ){
    //console.log( code );
    alert( code.data );
  }else{
    alert( "No QR Code found." );
  }
}

具体的にはコンテキスト変数(ctx)から getImageData() 関数でイメージデータを取得し、その結果を jsQR を使って解析します。ややこしそうな QR コードの解析部分は実はライブラリによって一瞬で実現できてしまっています。jSQR バンザイ!

正しく QR コードが解析できた場合は解析結果の文字列(code.data)を alert() 関数で画面に表示し、解析できなかった場合は "No QR Code found." と表示される、という一連の処理が定義されています。


今回の処理では QR コードが正しく解析でした場合はそのまま表示しているだけですが、これが URL であればロケーションに指定してジャンプしてもよし、テキストなどのデータであればバックエンドの API にポストしてもよし、というわけで取り出したデータの使いみちは alert() の代わりに記述することで、自由に応用できると思います。


というわけで、Filesystem API と jsQR と <input> タグのカメラ拡張を使うことで、ウェブのフロントエンド技術だけで QR コードリーダーが実現できました。


アキネーターの API が存在することを知ったので、使ってみました。ついでにこれを使ったウェブアプリを作ってソースコードごと公開してみました。


【アキネーターとは】
「思い浮かべた人を当てる」ウェブサービスです。基本的にはアキネーターからの質問に「はい」「部分的にそう」「わからない」「たぶん違う」「いいえ」の5つから選んで回答していくことで対象を絞り込み、かなりの高確率でその思い浮かべた人を当ててきます。

日本語のウェブ版はこちらから遊ぶことができます。スマホのアプリも提供されています。もし知らない人がいたら、以下を試す前に是非一度使って、その凄さを体験してみてください:
https://jp.akinator.com/

2020122505


【アキネーター API とは】
このアキネーターの機能を外部から利用するための API です。Node.js 向け npm パッケージ(aki-api)として提供されています:
https://github.com/jgoralcz/aki-api

2020122504


提供されているのは参照用の API のみのように見えます。つまり新しいキャラクターを登録したり、思い浮かべた人が間違っていた時のフィードバックの機能などは API に含まれていないようです。最初の質問を返して、それに答えて、答えると次の質問を返して、また答えて、・・・を繰り返します。答えるたびにその時点での確信度も更新されます。そしてどこかのタイミングで「決定」すると、その時点での回答候補と判定確率の一覧を参照することができる(普通はその中で最も確率の高い人を答えることになります)、といった機能を持っています。

アキネーター API は Node.js で動かすこと自体は簡単ですが、ウェブアプリケーションの中で使おうとすると、少し工夫が必要です。そのあたりの解説を含めて API の説明を後述していきます。


【アキネーター API の使い方】

以下ではアキネーター API の具体的な使い方を説明します。


準備

まずアキネーター API を利用するための動作環境として Node.js 8.2.1 以上、npm 5.3.0 以上が必要です。これらのバージョン以上の Node.js および npm をインストールしておく必要があります。

アキネーター API を利用する前に以下のコマンドで aki-api パッケージをインストールしておきます:
$ npm install aki-api --save

インスタンス化するまで

ここからは実際のプログラムの内容を紹介します。

アキネーター API を利用するには、まず以下のコードでライブラリを呼び出します:
var { Aki } = require( 'aki-api' );

そして以下のようなコードで変数 aki にインスタンス化します。インスタンス化時に対応言語をパラメータで指定する必要があります(下の例では "jp"(日本)を指定しています):
var aki = new Aki( 'jp' );

なお、この時に指定可能な対応言語の一覧は以下のコードで取得できます(regions 変数内に文字列配列で格納されます):
var { regions } = require( 'aki-api' );

こうしてインスタンス化した変数 aki を使ってアキネーターが操作できるようになります。


ゲームを開始して、質問と回答を繰り返して、推測した人を特定するまで

ここからが実際のアキネーターの挙動に関わる部分の説明となります。API の肝の部分です。なおアキネーター API の多くは非同期に実行されるため、同期処理する場合は await を付けて実行する必要があります。以下の説明で await を付けて実行している部分がその該当部分だと認識ください。

まずインスタンス化したアキネーターの推測を開始するために start メソッドを実行します:
await aki.start();

スタートしたインスタンスからは(後述の win メソッドを実行するまで)いくつかのプロパティを参照できるようになります。アプリケーション化する上で必要と思われる代表的なものを以下に紹介します:
プロパティ内容
currentStepここまでの推測に要したステップ数(初期値は 0)
questionこの時点でのアキネーターからの質問内容。インスタンス化時に指定した言語での質問となる(例:「男性ですか?」)
answers質問への回答選択肢の配列。インスタンス化時に指定した言語での質問となる(例:「はい」「いいえ」「わからない」・・)
progressこの時点でのアキネーターの回答確信度(0~100)


アキネーターからの質問内容は aki.question に格納されています。その質問に対する回答選択肢は aki.answers に文字列の配列で格納されていますが、回答選択肢の内容は途中で変化することはありません(例えば 'jp' でインスタンス化した場合は、「はい」「いいえ」「わからない」「部分的にそう」「多分ちがう」の5つで常に固定されます)。

ユーザーはこの選択肢から1つ選んでアキネーターに回答するわけですが、その回答を行うメソッドが step です。パラメータとして上述の回答選択肢のインデックス番号を指定します。例えば「はい」と答える場合は「はい」は配列の最初(0番目)の選択肢なので、パラメータに 0 を指定して実行します:
await aki.step( 0 );  //. 「はい」

「いいえ」の場合は同様にパラメータに 1 を指定して実行します:
await aki.step( 1 );  //. 「いいえ」

step メソッド実行後、aki インスタンスの currentStep, question, progress の各プロパティ値が更新されます(answers プロパティは固定)。回答後にステップ数がインクリメントされ、新しい確信度と新しい質問が取得できるようになります。

start メソッド実行後の、アキネーターとしての基本的な挙動は、この
  • aki.question の質問をして、
  • aki.answers から選んだ選択肢(のインデックス番号)を aki.step() に与えて回答する
を繰り返していくことになります。

これを繰り返している中で、アキネーターは勝手に推測をやめることはありません。どこかで「もう充分」と判断して推測をやめる、という決断をする必要があり、その判断基準やロジックは API 利用者に委ねられています。つまり決断タイミングや基準をプログラマーが決める必要があります。例えば「アキネーターの確信度が 70% を超えたら推測を終了する」のようなルールを決める必要があります(実際に動かしてみた上での感想ですが、実際のアキネーターはもう少し慎重に 70% よりは上の確信度を推測終了のしきい値にしているように思えます)。

アキネーターの推測を終了する場合は win メソッドを実行します:
await aki.win();

win メソッドを実行すると step メソッドは実行できなくなります。また win メソッド実行直後に answers プロパティが変化し、回答の選択肢ではなく、この時点までに推測していた人の上位数名を示す配列値に変わります:

(win メソッド実行後のインスタンスのプロパティ)
プロパティ内容
answers 推測結果の配列
[
  {
    id: "nnnn",
    name: "1番確率が高いと推測した人の名前",
    description: "推測した人の職業など",
    absolute_picture_path: "推測した人の画像URL",
    proba: "この人が答の確率",
      :
  },
  {
    id: "nnnn",
    name: "2番目に確率が高いと推測した人の名前",
    description: "推測した人の職業など",
    absolute_picture_path: "推測した人の画像URL",
    proba: "この人が答の確率",
      :
  },
    :
]


win メソッド実行後の answers プロパティには答えの候補と考えられた数名の名前が含まれているので、(一般的には)配列の最初の要素の人の名前や画像を表示して「この人ですか?」と確認することになります。

ここまででアキネーターとしての挙動は完了します。もし同じインスタンス変数(aki)を使って、このまま別の人の推測を繰り返す場合は、再度インスタンスの初期化をしてから同じ流れを繰り返すことになります:
aki = new Aki( 'jp' );  //. 再初期化
await aki.start();  //. 再スタート

  :

【アキネーター API をウェブで使う場合の工夫】

アキネーター API そのものの使い方は上述のようになります。いくつかのメソッドとプロパティを使うだけでアキネーターが実装できるようになっていて、とても便利です。

ただ、この API をウェブで(不特定多数の複数人で)使おうとすると少し工夫が必要です。理由はこのインスタンス自体がセッションのような情報を持っていて、ユーザー間で共有するわけにはいかない※、という事情があるからです。

※具体的にはこんな感じです。Aさんが初期化して、ある程度進めた所で B さんが初期化してしまうと A さんのセッションがおかしくなってしまいます。また B さんもある程度進めた所でまた C さんが初期化してしまったり、セッションがおかしくなったことに気づかない A さんが B さんのセッションも更に進めてしまったりして、整合性が保てなくなってしまうことが考えられます。

したがってアキネーター API をウェブで使う場合はユーザー毎にアキネーター API インスタンスを用意する必要があります。ということはユーザーを識別する必要もでてきます。ログインを必須にするなどすればここは可能ですが、より気楽にユーザー登録なしに実行できるようにするにはクッキーを併用するなど、ちと面倒そうな工夫も裏で必要になってしまいます(そこまでの機能は API 側には実装されていなさそうです)。


【サンプル】
・・・と、この工夫に踏み込んだところまで含めてソースコードを解説すると本来のアキネーター API の説明の範囲ではなくなってしまう上にちと面倒な内容も含むので、実際に動くサンプルを参照し、必要に応じてそのソースコードを観ていただく形とさせていただきます。

実際に動くサンプルアプリはこちらです(ランプ魔神の画像はいらすとや様から拝借しました):
https://myakinator.mybluemix.net/

2020122501

2020122502
(本当は5位の本仮屋ユイカさんのつもりだった・・・)


わざと確信度が 70% を超えたタイミングで(本物のアキネーターと比べて、確信度が深まる前の段階で)win メソッドを実行して回答候補を表示するようにしています。なので本物のアキネーターと比べてズバリ当たる確率は低いのですが、同時に回答候補となった人の一覧も表示するようにしていて、その中には正解が含まれることが多いような印象を持っています(本物はもう少し確信度が高くなってから回答候補を出しているのだと推測しています)。

で、このサンプルアプリのソースコードがこちらです:
https://github.com/dotnsf/myakinator

2020122503


ユーザーごとにランダムな ID を生成し、その ID をクッキーで管理しつつ、アキネーター API のインスタンスもユーザー毎に生成して管理することで上述の問題点を回避しています。まあ興味ある方はソースコードを覗いてみてください。



「REST API の標準化」を考える機会がありました。実際に格納したり取得したりするデータ自体の構造は当然ケース・バイ・ケースになるわけですが、その呼び出し方とか、パラメータの指定方法とか、結果のフォーマットとかを社内や団体内で共通化すると、単に便利なだけでなく、一度使った後に新しい別の API を利用する際にも理解を早めることができます。

で、具体的にはどのように共通化すべきで、そこにはどういった要素が考慮されるべきか、といった内容を自分なりに考えてみました。

ここには色んな流派というか、考え方の基本となるパターンがあるのですが、今回は自分の経験を元に、自分はこういう API にしている、こういう API だとわかりやすい/覚えやすい、という基準で、自分なりに標準化したものを紹介します。


【考慮すべき要素】
詳しくは後述しますが、以下の6つについては標準化時に抑えておく必要がある要素であると思っています:

0. id と日付時刻の扱い
1. API をリクエストする際のメソッドと URI
2. API をリクエストする際のパラメータ
3. API からのレスポンス
4. セキュリティ
5. テスト
6. 公開方法



また、以下で説明する内容については、下図のような商品マスターデータ(items)を対象とした REST API を作ることを想定した例として紹介します:
idcategory_idnamemaker_idpriceimage_urlcreatedupdated
x100x051○○シャンプーx10001700http://xxxxx/100.jpg16054028361605402836
x101x051××シャンプーx10002800http://xxxxx/101.png16054038361605403836
x102x052□□コンディショナーx100101000http://xxxxx/102.jpg16054048361605404836
x103x053▲▲ヘアオイルx10001500http://xxxxx/103.jpg16054058361605405836
x104x061◎◎ボディソープx100211000http://xxxxx/104.png16054068361605406836
x105x071◆◆天然化粧水x100102000http://xxxxx/105.png16054078361605408836

※数字は全て integer 。category_id や maker_id は別途 category や maker のマスターデータが存在していて、外部参照キーだけが格納されているイメージです。


【0. id と日付時刻の扱い】
まずは API の考慮点というよりも、その API で対象とするデータにおける考慮点です。既に存在しているデータベース等を対象とする場合は今からの変更は難しいかもしれませんが、新たにデータベースから作成できるのであれば API 利用を想定した設計にしておくべき、という考慮点です。

まずいわゆる id 値について。基本的にはテーブル内でユニークな値であればよいのですが、ここを integer 型とすべきか string 型とすべきか、という考慮点があります。メリット・デメリットを考慮した上で選ぶべきであると思っています:
 メリットデメリット
integer 型・データ量が少ない
・データベース側に自動生成機能があることが多い
・推測しやすい、推測される可能性がある
string 型・存在する id の推測が困難
・値そのものに意味をもたせることも可能(例:メールアドレス)
・1件あたりのデータ量が増える(といっても現代では大したことはないかも)
・生成の仕組みが必要


どちらのケースも存在しているし、どちらか一方に不利な要素があるわけではないのですが、個人的には「今から新規に作るなら string 型」だと思っています。理由は「今では string 型のデメリットが大したことない」のと「 ID が自動生成されるミドルウェアでは string 型になることが多い」ので、結果的に「ID は string 型にした方が統一しやすい」と思っています。

ID に加えて、データレコードの作成日時(created)と最終更新日時(updated)は全てのレコードに加えるべきだと思っています。ソフトデリートを有効にする場合は削除日時(deleted、初期値は 0 か null)も加えます。


なお日付時刻については後述する特別な理由がない限りは UNIX タイムスタンプ値を使うべきです。YYYY-MM-DD のような特定の文字列フォーマットで格納してしまうとタイムゾーンを考慮することができなくなってしまうため、データとしてはタイムスタンプ値で格納し、表示する際に変換する、という方法が理想的です。

※ただし「日本からしか使わない」ことに加えて「特定日だけのデータを取り出す」といった用途がある場合などはあらかじめ日付フォーマット変換しておいた方が便利になることもあります。日付フォーマットを利用する場合は、そのフォーマットもあらかじめ標準化しておくべきです(YYYY-MM-DD とか YYYY-MM-DD hh:mm:ss など)。なお、このあたりは個別事情を考慮して対応する必要があるため、標準化ルールの対象外とする場合もあります。


【1. API をリクエストする際のメソッドと URI】
リクエスト時の考慮ポイントが1番多くあると思っています。順に説明します。

「メソッド」はいわゆる HTTP メソッドのことで、一般的には GET(取得・検索)、POST(作成)、PUT(更新)、DELETE(削除)が用いられます。API の用途や目的に合わせてメソッドを選びます。

より多くの考慮が必要なのは URI 部分となります。まず前提として以下の条件を逸脱しないよう注意してください:
  • 文字コードは UTF-8
  • リクエストデータに外字は使わない
  • URI ではキャメルケース(userData)ではなくスネークケース(user_data)を使う※
  • %(パーセント)でエンコーディングする必要があるデータは URI に含めない
※ホスト名部分が大文字・小文字の区別をしないためです

次にホスト名ですが、理想的にはホスト名の一部に "api" という文字が含まれていることが挙げられます。これが難しい場合はパス名のどこかに "api" を含めて、この URI が API のための URI であることを明示します。以下では api.mycompany.com というホスト名を使う想定で説明を続けます。

パス名の中には今後の仕様変更に対応できるよう、 API のバージョン("v1" など)を含めるようにします。

データの種類(この場合は items)も URI の一部に含まれている必要があります。このあたりから流派によって扱いに違いが出てくる部分ですが、自分は「単数を扱う API なら単数形(item)」、「複数を扱う API なら複数形(items)」としています。そして単数を対象とする場合はその id をパス内で指定するようにします。

例えば以下のようにする、ということです:
  • GET https://api.mycompany.com/v1/items (複数の items を取り出す
  • GET https://api.mycompany.com/v1/item/x100 (id = "x100" の item を取り出す
  • POST https://api.mycompany.com/v1/item (item を1件新規登録する)
  • PUT https://api.mycompany.com/v1/item/x101 (id = "x101" の item を更新する)
  • DELETE https://api.mycompany.com/v1/item/x102 (id = "x102" の item を削除する)
  • POST https://api.mycompany.com/v1/items (items をまとめてバルクインサートする)
  • DELETE https://api.mycompany.com/v1/items (items をまとめてバルクデリートする)
  •   :
リクエストした結果をどのようなフォーマットで取得するか、というフォーマットの指定も(特定フォーマットで固定、ということでなければ)リクエストに含めることができるべきです。一般的には URI の最後に拡張子の形で指定できるようにすることが多いようです:
  • GET https://api.mycompany.com/v1/items.json (複数の items を JSON で取り出す)
  • GET https://api.mycompany.com/v1/items.xml (複数の items を XML で取り出す)
  • GET https://api.mycompany.com/v1/item/x100.json (id = "x100" の item を JSON で取り出す)
  • GET https://api.mycompany.com/v1/item/x100.csv (id = "x100" の item を CSV で取り出す)
  •   :
拡張子が指定されていなかった場合は、エラー扱いとするか、またはあらかじめ決められたデフォルトフォーマットのリクエストに転送されて処理されるようにするか、を決めておきます。

なお、そもそも CSV で取り出すことができないようなデータ構造のオブジェクトを対象とする場合は無理に CSV に対応する必要はないと思っています。

また「検索」や「アップロード」といった処理については別の URI を用意することになります。



【2. API をリクエストする際のパラメータ】
一部 3. で考慮する内容も含まれるのですが、リクエスト時の URL パラメータをどのように標準化するべきかを記載します。

複数のデータが返ってくる可能性のある API を実行する場合、全データ量が膨大にならないようパラメータで制御することがあります。この例を使って以下を紹介します。

一般的には limit パラメータと offset パラメータを用いて取得範囲を指定します。limit は取得件数、offset は「何件目から」を指定するパラメータです。一般的に offset のデフォルト値は 0(1件目から)で、limit のデフォルト値は 100 以下が推奨されています:
  • GET https://api.mycompany.com/v1/items.json?limit=20&offset=100 (items を 100 件目から 20 件、JSON で取り出す)
  •   :

これら以外によく使われるパラメータとしては以下があります。どのようなパラメータに対応すべきかを事前に決めておきます:
パラメータ用途
sortソートキーを指定
since指定タイムスタンプ以降のデータを取り出す
until指定タイムスタンプ以前のデータを取り出す
fields実行結果に含まれるフィールド値を指定したものだけにする(カンマ区切り)


【3. API からのレスポンス】
API の(実行できなかったケースも含めた)実行結果にもある程度の共通化・標準化がされていると、実行後の処理ハンドリングに手間取ることが少なくなります。このレスポンスは (1) 成功した時と、(2) 失敗した時 の両方を考慮した上で標準化する必要があります。ただし KML や iCal, GeoJSON など、フォーマットが規定済みである場合は、そのフォーマットに従うものとします。

考慮点を以下に挙げますが、多くの場合で開発者はまず API を実行し、その結果を見て開発していく、という流れになります。そのため返却された内容で実行結果を判断できるようになっていることが望ましいと考えられます。

まず (1) 成功時のレスポンスデータには以下のような内容が含まれているべきと考えられます:
パラメータ用途
statusHTTP ステータス
resultset全データ件数、offset 値、limit 値
result実行結果(配列)


{
  status: 200,
  resultset: {
    count: 3,
    offset: 10,
    limit: 20
  },
  result: []
}


また (2) エラー時のレスポンスデータには以下の情報を返して原因追求できるようにするべきです:
パラメータ用途
statusHTTP ステータス
typeエラー種別
errorエラー内容


{
  status: 401,
  type: "not authorized",
  error: {
    message: "Not authorized to perform this operation."
  }
}

【4. セキュリティ】
フォーマットの取り決め、という意味での標準化は上述のような感じですが、フォーマット以外にも標準化の対象はあります。その1つがセキュリティ項目です。代表的なものを挙げてみました:
観点対策説明
通信の改ざん、盗聴通信暗号化SSL(https)通信に対応することで送受信データの信頼性担保および情報漏えいの防止を行う。
情報漏えいAPI キーなどによる認証API 利用者に認証をかけることで API を利用できる人を制限する。また利用者毎の利用頻度を確認できるようにすることで API キーが漏洩している可能性を早めに特定できるようになる。アクセストークンを利用する場合はアクセストークンの有効期間を適切に設定して、トークン漏洩時の2次被害を最小にする。
負荷対策利用制限、キャッシュAPI に DDoS 攻撃が行われることを想定した管理が必要。コール数に対する利用制限をかけたり、同一の GET リクエストに対してキャッシュレスポンスで対応する、など
クロスドメイン間の通信CORS 対応ウェブブラウザではクロスサイトスクリプティング防止の観点からクロスドメイン間通信は行わない仕様となっている。場合によってはクロスドメイン間通信を許可する必要が生じ、そのための対応が必要となる




【5. テスト】
API を実際に動かしてテストする上での、テスト環境やテスト方法を標準化することで、テスター担当者の負担を軽減することができます。

一般的には動作を確認できるようなフォームやサンプルプログラムを用意して実際に実行し、そのレスポンスを確認することになります。

なお、6. で後述する Swagger ドキュメントを利用することでテスト用フォームを自動生成することができます。


【6. 公開方法】
API をドキュメント化してテスターや開発者に公開するまでの流れを標準化する、という項目です。このための各種ツールも存在していますが、以下では Swagger ドキュメントを紹介します。

Swagger ドキュメントは Open API Initiative が提供するオープン企画 "OAS" で採用されている REST API のドキュメント化規格です。

Swagger Editor や、YAML による特定フォーマットで API を記述することで、インタラクティブなドキュメント UI を生成することができます。単に URI やパラメータの説明をするだけでなく、実際にAPI を動かすことができる、という点が最大の特徴となっています。開発者視点では実際に API の動作を確認しながら仕様を確認できるのでとても有用な API ドキュメントといえます:
2020111801



【参考】
 内閣官房情報通信技術(IT)総合戦略室  API テクニカルガイドブック

この記事の続きです。PayPay API を自分のアプリケーションで使うための準備やサンプルコード、使い方などはこちらを参照してください:
PayPay の API でアプリケーションに日本円での決済機能を実装する

こちらのエントリでは応用編というか、実際のアプリケーションの中で PayPay API を使って決済する際に意識することになるであろう事柄3点について考慮すべきポイントを紹介します。


1 作成した QR コードで実際に決済されたかどうかをアプリケーションから知る方法

前回の記事では簡単にウェブアプリケーションに PayPay による決済機能を組み込んで QR コードによる決済を実現することができる、という内容を紹介しました。ここまではよい、と。 ただ実際には QR コードを作成する所まではトラッキングできますが、作成した QR コードを使って決済が行われても、それは元のウェブアプリケーションの画面内で行われる決済ではないため「本当に決済までが行われた」のか、それとも「QRコードは表示されたけど、PayPay での決済は行われなかった」のかを識別する方法は別に考慮する必要があります。それをどうすればよいか、というのが実運用における最初のポイントです。

これは実は PayPay API 側で用意された機能を使うことで実現できます。前回の記事を参照いただくとわかるのですが、生成された QR コードを表示する際に以下のような JavaScript コードが実行されていました:
          :
          :
      success: function( result ){
        console.log( result );
        if( result && result.status && result.status == 201 && result.body && result.body.data ){
          var merchantPaymentId = result.body.data.merchantPaymentId; //. 支払いID(キャンセル時に必要)
          var codeId = result.body.data.codeId; //. QRコードID(QRコード削除時に必要)
          var url = result.body.data.url;  //. QRコードが表示されるページの URL

          if( url ){
            //. QRコードが表示されるページを別ウィンドウで開く
            window.open( url, 'PayPayWindow' );
          }
        }
      },
          :
          :

QR コードの表示は result オブジェクトの result.body.data.url の値を参照して、この値で示される URL を別ウィンドウで開くことで実現していました(別ウィンドウで開くため、これ以降の直接のトラッキングはできなくなっていました)。この時に取得できる result.body.data.merchantPaymentId という値を使って PayPay APIGetCodePaymentDetails 関数を実行すると、その QR コードのステータスを確認することができるのでした。ステータスを確認し、COMPLETED となっていればその決済は完了しており、そうでなければ完了していない、と判断できることになります。

より具体的にはこの merchantPaymentId をデータベースなどに保存しておいて、Webhook と使ったり、cron で定期的に確認したり、いずれも難しい環境下であっても例えば次回ログイン時などにステータスをチェックすることで決済の済/未済の判断ができるようになります。


2 作成した QR コードを「どのユーザーが」決済したかを判断する方法

1で QR コードが実際に決済されているかどうかを識別する方法を紹介しましたが、実運用においてはもう1点、その QR コードを「どのユーザーが」決済したのかを知る必要があります。これも決済そのものは簡単に実現してしまうのですが、別ウィンドウで開くページ内での決済のため、自分が作ったウェブアプリケーション内で決済ユーザーを識別するのが難しい、という問題を解決する必要があります。

こちらは少しコードを修正する必要がありますが可能です。現在のソースコードでは上述の merchantPaymentId をサーバーサイドで一意になるよう生成していますが、ここを変更し、クライアントサイドで「ユーザー名やユーザーIDを用いて merchantPaymentId を生成する(あるいはサーバーにユーザー ID を送信して、サーバーサイドでユーザー ID を用いた merchantPaymentId を生成する)ことで解決できそうです。つまり merchantPaymentId をただのランダムな文字列ではなく、(例えば頭にユーザーIDを付与するなどして)ここを見ることで誰が作成した QR コードなのかがわかれば、(1と合わせることで)誰が作成した QR コードが決済されたのか、も識別することができるようになります。


3 1回の QR コード決済で定期的な支払いをする方法

例えば月額課金のサブスクリプション型サービスと契約すると、毎月決まった額が引き落とされることになります。これを PayPay API の QR コード決済でも1回で実現できると、自分の作ったウェブアプリケーションのサブスク化ができるようになって便利だと思っています。

が、実はこの内容だけは現時点で実現の目処が立っていません。そもそも QR コードで分割払い契約って可能なんだろうか・・・

PayPay API や SDK のドキュメントも見ているのですが、なんとなく「現時点では未対応」なような気もしています。サブスクだと「解約」処理も必要になると思うのですが、そういう API も見当たらないような・・・ 今の時点においては毎月 QR コードを作って、その都度払ってもらう以外の方法はないのかもしれません(情報/アイデア求む)



というわけで、PayPay API を使うことでウェブアプリケーションに決済機能を簡単に付与することができるのですが、実運用までを意識すると、ここに挙げた3点についても考慮して設計・実装する必要があると思っています。ただ3番目の定期支払いはなんとか1回の処理で実現したり、それを途中で解約するような具体的な方法ないかなあ。。。

このページのトップヘ