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

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

タグ:api

Swagger APIはインタラクティブに動く REST API のドキュメントを比較的簡単に作ることができて便利です。自分も実際に業務やプライベートアプリに使っています。

この機能を使う場合、YAML と言われるフォーマットをベースにした記述方法で API の仕様を記述するだけで動く API ドキュメントページを作ることができます。

で、この YAML で仕様を記述する際に「コメント」を記述したくなることがあります。実質的にプログラミングする必要なく API テストページを作れるのは便利で、プログラミング時と同様にコメントを残したくなることもあると思います。 が、YAML でコメントを書いたことがなかったので、改めて明示的にコメントを残そうとした際の手法がわからず、調べてみました。

答えとしては「# から行末までがコメント」となるようです。つまり一行単位でコメントが生成されます。「ここからここまで」という範囲コメントは存在していないようです。
info:
  description: 普通の行
#  description: コメント行
  titie: タイトル   # ここはコメント  

なお、コメント扱いにしたくない # を含めたい場合は \# のようにバックスラッシュでエスケープすることで実現できます。




 

業務で「リモート操作で扉の鍵を施錠/解錠する」必要があり、いろいろ調査した結果 Akerun という入退室管理システムを使ってみました。その様子をメモ目的でブログにしました。
2019030400


扉の鍵をリモート操作で開ける、という需要はあると思っています。特定の条件を満たす人だけが入れる部屋を作りたい(そのためのロジックを加えて実装したい)とか、締め忘れて外出してしまった可能性のある家の扉の鍵をいま居る場所から施錠したいとかです。

で、いくつか調べてみました。Bluetooth や NFC などを使って比較的近い距離間で通信できるものは多く提供されているようでしたが、現在 REST API を使って離れた場所からも操作できるもの、となると(2019年2月に私が探した限りで※)株式会社フォトシンスから提供されている Akerun (Pro) という製品だけのようでした。

※他に探した範囲では REST API が提供されていなかったり、以前は提供されていたが現在は提供されていなかったり、日本向けの情報が提供されておらずそもそも日本で入手できるのか不明だったり・・・という結果でした。

なお、Akerun 自体には(買い取り式の)個人向け製品も存在しているのですが、REST API が提供されているのは業務用の Akerun Pro という月次レンタル製品のみとのことでした。気軽に使ってみるにはちとハードルが高いかもしれないと感じたのと、それ故かあまり技術情報をウェブで見かけることがあまりありませんでした。そんな背景もあって今回ブログで紹介しようかな、と思い立ったのでした。


【システム構成】
まず Akerun Pro を使った今回のシステム構成はこんな感じになります:
2019022601


Akerun(今回利用するのは正確には "Akerun Pro" ですが、以下 "Akerun" と表記します)は既存のドアに設置可能なデバイスです。外部から信号を送ってドアのサムターン部分を回して解錠/施錠します(要はサムターンが回せる位置に Akerun を取り付けて使う、というものです)。実際には NFC などのカードを使って開閉することもできます(注 Akerun Pro では一式揃っています)が、今回は使いません。

特に REST API でリモート操作する場合は、Akerun デバイスに加えて Akerun Remote と呼ばれるインターネットとのルーターとなるデバイスを追加設置します(Akerun Remote も Akerun Pro に含まれています)。上図のように Akerun と Akerun Remote は Bluetooth で接続されます。Akerun Remote は有線または無線LANでインターネットに接続します(私は WiFi テザリングで試しました)。無線 LAN の設定等はスマホ用の専用アプリを使って Akerun Remote に設定することができます。

このようにして Akerun Remote をインターネットに接続した後は管理用画面や API を使って解錠/施錠の指示を出すことができるようになります。それらの指示はインターネットを経由して Akerun Remote へ伝わり、Akerun Remote から Akerun へ Bluetooth による指示が送られてサムターンが(指示されたように)動く、というものです。


【準備】
API の使用は申込み制となっていて、こちらのページ内の「こちらのお申込みフォーム」と書かれたリンクから申し込みを行う必要があります:
https://developers.akerun.com/#introduction

申込時に名前やメールアドレス、電話番号等を登録していくのですが、 OAuth 認証のリダイレクト URI を指定する箇所があります:
2019022602

 
この URI は実在している必要はないのですが、実在しない場合はエラー時にリダイレクトされない URI である必要があります(OAuth リダイレクト時のパラメーターを受け取る必要があるため、実在しない場合でもパラメータを保持した URI でエラー表示される必要があります)。また https:// の URI である必要がある点に注意が必要です。ここで指定した URI は後で使うのでメモしておきましょう。ここでは仮に https://myapp_for_akerun.mybluemix.net/callback という URI を指定したものとして以下を紹介します。

申し込みの手続きが完了すると(数日後に) OAuth 認証用の client_id と client_secret が記載されたメールが送信されてきます。ここでは仮に
 client_id: "my_client_id"
 client_secret: "my_client_secret"
という値が送られてきたものと仮定して以下を紹介します(実際にはランダムな文字列です)。

ここまで完了するとアクセストークンの発行ができるようになります。


【アクセストークンの取得】
ウェブブラウザで以下の URL にアクセスします:
https://api.akerun.com/oauth/authorize/?client_id=(送られてきた client_id の値)&redirect_uri=(申込時に指定したリダイレクト URI の値)&response_type=code

上記の前提であれば、具体的には以下の URL となります:
https://api.akerun.com/oauth/authorize/?client_id=my_client_id&redirect_uri=https://myapp_for_akerun.mybluemix.net/callback&response_type=code


正しい値が指定されていると redirect_uri のアドレスにリダイレクトされます。その時の URI に code 
というパラメータが付与されているので、この値を取り出します。例えばリダイレクト先が
 https://myapp_for_akerun.mybluemix.net/callback?code=XXXXXXXXXX
という URI であれば、XXXXXXXXXX 部分が該当します。この値を code 値として以下を続けます(code 値は取得から 30 分間有効なので、取得から 30 分以内に以下のアクセストークンの取得を行ってください)。

取得した code 値と HTTP POST を実行できるツール(curl など)を使って、以下の HTTP POST リクエストを実行します(実際には改行せず一行で入力します):
$ curl -X POST "https://api.akerun.com/oauth/token"
  -d grant_type=authorization_code
  -d client_id=(client_id の値)
  -d client_secret=(client_secret の値)
  -d code=(code の値)
  -d redirect_uri=(申込時に指定したリダイレクト URI の値)



上記までに取得した例の場合だと、このような(一行の)リクエストになります:
$ curl -X POST "https://api.akerun.com/oauth/token"
  -d grant_type=authorization_code
  -d client_id=
my_client_id
  -d client_secret=
my_client_secret
  -d code=XXXXXXXXXX
  -d redirect_uri=
https://myapp_for_akerun.mybluemix.net/callback


成功すると以下のような JSON がレスポンスとして返されます:
{
  "access_token": "**********",
  "token_type": "bearer",
  "refresh_token": "xxxxxxxxxx.....",
  "expires_in": 7776000,
  "created_at": 1500853017
}



この結果の "access_token" の値(********** 部分)がアクセストークンです。


【REST API の実行】
ここまでの手順でアクセストークンが取得できていれば、その値を HTTP リクエストヘッダを使って、
 Authorization: Bearer (アクセストークンの値)

のように指定して、各種 REST API を実行することができるようになります。例えばアクセストークンのオーナーが所属する組織 ID の一覧は GET https://api.akerun.com/v3/organization で取得できるのですが、このリクエスト時に
 Authorization: Bearer **********
という HTTP リクエストヘッダを付与することで正しい権限で実行できます。

例えば組織 ID : OOO1、アケルン ID : AAA1 の鍵をリモートで解錠するには、以下の HTTP リクエストを発行します:
$ curl -X POST "https://api.akerun.com/v3/organizations/OOO1/akeruns/AAA1/jobs/unlock"
  -H "Authorization: Bearer **********"



同様にして、同じ鍵をリモートで施錠する場合は以下になります:
$ curl -X POST "https://api.akerun.com/v3/organizations/OOO1/akeruns/AAA1/jobs/lock" 
  -H "Authorization: Bearer **********"




なお、開発者向けの API 情報はこちらです:
https://developers.akerun.com/#introduction


グーグルマップは今やナビ代わりにも使えて非常に便利です。

この「グーグルマップでナビをする」という機能を一発で起動する URL を調べてみました。前提条件として GPS 機能が有効になったスマホのブラウザで起動し、現在地から目的地までのナビゲーションを行う画面にジャンプさせたいものとします。結論としては意外と簡単でした。

以下、いくつかのパターンの URL リンクを作成したので、このページを実際にスマホのブラウザで参照した後にリンクをクリックすると実際にナビゲーションを開始することができるので試してみてください。


【原則フォーマット】
具体例を以下に紹介しますが、原則的には以下のフォーマットの URL となります:
https://www.google.co.jp/maps/dir/出発地(/経由地のリスト)/目的地

出発地や経由地、目的地は 緯度,経度 で表します。

例えば(私の職場オフィスがある)東京の銀座シックスの位置は北緯 35.6696206 度、東経 139.7618279 度なので、35.6696206,139.7618279 と表現します。


【直接指定】
現在地から銀座シックスへの道案内は以下の URL です(経由地を指定していません):
https://www.google.co.jp/maps/dir//35.6696206,139.7618279

銀座シックスから東京タワー(35.658886,139.745787)への道案内はこちらの URL です:
https://www.google.co.jp/maps/dir/35.6696206,139.7618279/35.658886,139.745787


【経由地指定】
現在地から東京タワー(35.658886,139.745787)を経由して銀座シックスへ向かう道案内は以下の URL です:
https://www.google.co.jp/maps/dir//35.658886,139.745787/35.6696206,139.7618279

現在地から秋葉原(35.697850,139.771179)と東京タワーを経由して銀座シックスへ向かう道案内は以下の URL です:
https://www.google.co.jp/maps/dir//35.697850,139.771179/35.658886,139.745787/35.6696206,139.7618279


 

(この記事は IBM Cloud アドベントカレンダー 2018 に参加しています。3日目の記事です)

IBM Cloudant (Apache CouchDB) にあまり詳しくない人が他のデータベースと同じ感覚でデータを扱っている時に、特に既存データを更新している時にふと気づくことがあります。例えば以下のような現象を目の当たりにした時、何が起こっているのか正しく理解できるでしょうか?


IBM Cloudant のダッシュボード画面にアクセスし、今回は "testdb" という名称のデータベースを IBM Cloudant 上に新規に作成しました。以下の手順はすべてこのデータベースを対象に行います(CouchDB でも同様の結果になります)。作成したばかりなのでまだドキュメント数はゼロです:
2018100201


testdb データベースを選択した画面です。普通はここで testdb 内のドキュメント一覧が表示されますが、まだ1つも存在していないので "No Documents Found" と表示されています。ここでドキュメントを新規に作成するため "Create Document" ボタンをクリックします:
2018100202


新規に JSON ドキュメントを作成する画面に切り替わります。Cloudant(CouchDB) のドキュメントは "_id" というユニーク ID を含める必要があります(API 経由で _id を含めずに作ると自動的に割り振られます)。自動的に設定された "_id" 以外に "name" というキーを作り、適当な値(下図では "kkimura")を設定して "Create Document" ボタンをクリックします(JSON ドキュメントなので "_id" キーの最後にカンマをつけることを忘れずに):
2018100203


先程のドキュメントが作成され、ドキュメント一覧に1つのドキュメントが表示されるようになりました:
2018100204


ちなみに、この段階でデータベース一覧に戻ると testdb データベースのドキュメント数もゼロから 1 に変わっていることが確認できます:
2018100205


またドキュメント一覧からこのドキュメントを選択するとドキュメントの確認/編集画面になります。"_rev" という先ほど指定しなかったキーと値が追加されていますが、こちらは後で説明します:
2018100206


ここまでは特別におかしな所はないと思います。この文書を編集するあたりから Cloudant 特有のクセというか、「あれ?」と感じる所が出てくるようになってきます。

この画面から JSON ドキュメントを編集してみます。試しに "name" の値を(下図では "Kei Kimura" に)変更し、"Save Changes" ボタンをクリックします:
2018100207


変更内容が保存されて、ドキュメント一覧に戻ります。既存文書を編集して保存したので文書数は変わらずに1つのままです。ではこの文書を選択して開いてみます:
2018100208


"name" の値が "Kei Kimura" になった文書が開きました。が、よく見ると "_rev" の値が先程と異なっています。最初に作った直後は "1-" で始まる値だったのが、 "2-" で始まる値になっています。ここは変更しなかったはずなんですが・・・:
2018100209


また、このタイミングでデータベース一覧の画面に戻ると、testdb の文書数は1のままなんですが、データベースサイズが微妙に増えています。これほどの差がでるような変更をしたつもりはないのですが・・・:
2018100210


更にこの文書を開いて、再度 "name" 値を "kkimura" に変更して(元に戻して)みます。値を変更して "Save Changes" ボタンをクリックします:
2018100211


すると(中を開いて確認してもいいのですが)また "_rev" の値が変わっていることが一覧からもわかります。今度は "3-" で始まる値になっていました:
2018100212


この辺りから「???」と感じることが増えてきました。では最後にこの文書を削除してみます。一覧からチェックをつけてゴミ箱ボタンをクリックします:
2018100213


削除すると一覧からは文書は消えて、元通りの "No Documents Found" が表示されます:
2018100214


しかしデータベース一覧に戻って testdb を見ると、文書数は "0" ですが、横に!マークが付いています。また文書を削除した割にはデータベースサイズがあまり減っていないように見えます:
2018100215


この!マーク部分にマウスカーソルをあわせると、"This database has just 0 docs and 1 deleted docs" と表示されます。このメッセージの意味はいったい・・・:
2018100216


ドキュメントに勝手に "_rev"(と "_id")が付与されること、編集して保存すると "_rev" の値が勝手に変更されること、文書を削除してもデータベースサイズが減らないこと、文書を削除した時の謎のメッセージ、・・・ と、この辺りが Cloudant(CouchDB) を始めて使うと戸惑う点でしょうか? 前置きが長くなってしまいましたが、以下にこの謎を解くための説明を記載します。


上記の振る舞いを理解するには、まず自動付与される2つの値 "_id" と "_rev" の意味と役割を正しく理解する必要があります。

"_id" はいわゆる「文書 ID」です。この値はデータベース内でユニークな値をなっており、各文書を一意に取得することができるキー値となっています。正しい ID 値が与えられるだけで(他の絞り込み条件がなくても)データベース内から目的の文書を特定して取得することができます。ID 値については普通のデータベースでも扱うものなので、あまり難しくないと思っています。

一方、もうひとつの "_rev" 、こちらは IBM Cloudant(CouchDB) の特徴的な予約語となっており、「文書のリビジョン」を管理する値となっています。「リビジョン」は「バージョン」と読み替えていただいてもいいです。

上記の例だと、最初に "name" = "kkimura" という値で文書を作成しました。この時点ではこの文書のリビジョン(バージョン)は 1 で、"_rev" 値は "1-" で始まる値になっていました:
2018100204


次に同じ文書を "name" = "Kei Kimura" と変更して保存しました。この時点でこの文書のリビジョンは 2 となり、"_rev" 値も "2-" で始まる値に更新されました:
2018100208


更に同じ文書を "name" = "kkimura" に戻して保存しました。この時点でこの文書のリビジョンは 3 となり、"_rev" 値も "3-" で始まる値に更新されました:
2018100212


つまり "_rev" 値は "_id" 値で決まる文書のバージョンを管理する役割を持って自動的に更新されるシステム値ということになります。ただ Cloudant(CouchDB) でドキュメントが更新される際にはもう1つの特徴があります。

実は Cloudant(CouchDB) ではドキュメントが更新されることはほぼなく、「新しいドキュメントが新しい "_rev" 値を持って新規作成」されます。つまり厳密には同じ "_id" 値を持った複数のドキュメントがデータベース内には存在しているが、その中で最も大きな "_rev" 値を持ったドキュメントだけが有効になります。論理的にドキュメントを更新したつもりでいても、物理的には古いドキュメントは消えずに残っていて、新しいドキュメントが同じ "_id" 値&新しい "_rev" 値で作成されるのでした。なお最新でないリビジョンのドキュメントは _id 値を指定してドキュメントを取得する時に { revs_info: true } というオプションを指定することで取得することができます(このオプションをつけない限り、最新 _rev のものだけで取得できます):
http://docs.couchdb.org/en/stable/api/document/common.html


上記で Cloudant(CouchDB) のドキュメントが更新されることは「ほぼ」ないと書いたのですが、厳密にはあります。それが文書削除時です。Cloudant(CouchDB) の文書削除はいわゆる「ソフトデリート(論理削除)」であって、「ハードデリート(物理削除)」ではありません。文書に削除フラグ( { _deleted: true } )をつけて更新し、最新 "_rev" の文書が削除されているようにすることで、論理的に文書が削除されたことにしています。そしてこの論理削除を行う際には _id 値だけではなく、_rev 値と合わせて指定して、「この ID 値の、このリビジョンの文書を削除する」ことを明示的に指定する必要があります。論理的には _id 値だけで削除できそうな感覚を持ってしまいますが、その場合はまずその _id 値を持ったドキュメントの最新リビジョンを取得し、取得したドキュメントから _rev 値を取り出し、改めて _id 値と _rev 値を指定して論理削除する、という流れになります。


これらの部分を理解していると、文書を更新したり、削除した時にデータベースサイズが増える謎が理解できると思います。要は物理的に書き換えたり、物理的に削除しているわけではなく、新リビジョンのドキュメントを追加したり、削除フラグをつけたりしているだけなので、(別途物理削除するまでは)データベースサイズという観点では減ることがないのでした。








 

楽器苦手なオッサンエンジニアの Web Audio API 勉強シリーズ(!?)、前回はマイクから入力した音声をオーディオバッファ・インスタンスに変換して再生するコードを紹介しました。今回は前回作成したコードを改良して、音声データを折れ線グラフで可視化することに調整してみました。

作成したコードはこんな感じです。前回のものからの差分をで示しています:
<html>
<head>
<title>Audio Buffer Chart</title>
<script src="https://code.jquery.com/jquery-2.0.3.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.1.4/Chart.min.js"></script>
<script>
window.AudioContext = window.AudioContext || window.webkitAudioContext;
var context = new AudioContext();

window.onload = function(){
}

var processor = null;
var num = 0;
var duration = 0.0;
var length = 0;
var sampleRate = 0;
var floatData = null;
function handleSuccess( stream ){
  var source = context.createBufferSource();
  var input = context.createMediaStreamSource( stream );
  processor = context.createScriptProcessor( 1024, 1, 1 );
  
  //window.dotnsf_hack_for_mozzila = input;
  input.connect( processor );
  processor.onaudioprocess = function( e ){
    //. 音声データ
    var inputdata = e.inputBuffer.getChannelData(0);
    //console.log( inputdata );

    if( !num ){
      num = e.inputBuffer.numberOfChannels;
      floatData = new Array(num);
      for( var i = 0; i < num; i ++ ){
        floatData[i] = [];
      }
      sampleRate = e.inputBuffer.sampleRate;
    }
    
    var float32Array = e.inputBuffer.getChannelData( 0 );
    if( availableData( float32Array ) ){
      duration += e.inputBuffer.duration;
      length += e.inputBuffer.length;
      for( var i = 0; i < num ; i ++ ){
        float32Array = e.inputBuffer.getChannelData( i );
        Array.prototype.push.apply( floatData[i], float32Array );
      }
    }
  };
  processor.connect( context.destination );
}

function startRec(){
  $('#recBtn').css( 'display', 'none' );
  $('#stopBtn').css( 'display', 'block' );

  navigator.mediaDevices.getUserMedia( { audio: true } ).then( handleSuccess );
}

function stopRec(){
  $('#recBtn').css( 'display', 'block' );
  $('#stopBtn').css( 'display', 'none' );

  if( processor ){
    processor.disconnect();
    processor.onaudioprocess = null;
    processor = null;
    
    var audioBuffer = context.createBuffer( num, length, sampleRate );
    for( var i = 0; i < num; i ++ ){
      audioBuffer.getChannelData( i ).set( floatData[i] );
    }
    
    console.log( audioBuffer ); //. これを再生する
    
    var source = context.createBufferSource();

    source.buffer = audioBuffer;           //. オーディオデータの実体(AudioBuffer インスタンス)
    source.loop = false;                   //. ループ再生するか?
    source.loopStart = 0;                  //. オーディオ開始位置(秒単位)
    source.loopEnd = audioBuffer.duration; //. オーディオ終了位置(秒単位)
    source.playbackRate.value = 1.0;       //. 再生速度&ピッチ

    source.connect( context.destination );

    //. for lagacy browsers
    source.start( 0 );
    source.onended = function( event ){
      //. イベントハンドラ削除
      source.onended = null;
      document.onkeydown = null;
      num = 0;
      duration = 0.0;
      length = 0;

      //. オーディオ終了
      source.stop( 0 );

      console.log( 'audio stopped.' );
    };
    
    //. floatData[] (の先頭の一部)をグラフ描画する
    var dotnum = 1024;
    var ctx = document.getElementById( 'myChart' ).getContext( '2d' );
    var labels = [];
    var datasets = [];
    var colors = [ "rgba( 255, 0, 0, 0.4 )", "rgba( 0, 0, 255, 0.4 )" ];
    for( var i = 0; i < dotnum; i ++ ){
      labels.push( "" + ( i + 1 ) );
    }
    for( var i = 0; i < num; i ++ ){
      datasets.push({
        label: "data " + i,
        data: floatData[i].slice(1024,1024+dotnum),
        backgroundColor: colors[i%2]
      });
    }
    
    var myChart = new Chart( ctx, {
      type: 'line',
      data: {
        labels: labels,
        datasets: datasets
      }
    });
  }
}

function availableData( arr ){
  var b = false;
  for( var i = 0; i < arr.length && !b; i ++ ){
    b = ( arr[i] != 0 );
  }
  
  return b;
}
</script>
</head>
<body>
  <div id="page">
    <div>
      <h2>オーディオバッファ視覚化</h2>
      <input type="button" id="recBtn" value="Rec" onClick="startRec();" style="display:block;"/>
      <input type="button" id="stopBtn" value="Stop" onClick="stopRec();" style="display:none;"/>
    </div>
    <div>
      <canvas id="myChart"></canvas>
    </div>
  </div>
</body>
</html>

本当は再生する音声データ全てを折れ線グラフとして表示できるとよかったのですが、数10万~数100万個の配列データを扱うことになり、処理がかなり重くなる(見栄えもつまりすぎて折れ線に見えなくなる)ことがわかったので、上記では全データの 1024 個目から 500 個だけ取り出して折れ線グラフにするようなコードにしています(後述のように、このくらいだとかろうじて折れ線に見えます)。

変更点としてはまず HTML ボディ内に折れ線グラフを表示するための canvas 要素を記述しています。そしてこの canvas の中に Chart.js を使って折れ線グラフを描いていきます。今回は Chart.js の CDN を使ってロードしています。

今回の例ではマイクから入力した音声データ(波形データ)は floatData[] 配列に格納しています。入力がモノラルの場合は floatData[0] に、ステレオの場合は floatData[0] (左)と floatData[1] (右)に、それぞれ波形データが配列で格納されます。この中身を折れ線表示すればよいことになります。

※マイクからの入力であれば、このように波形データをあらかじめ配列に格納させておくことができますが、オーディオファイルを再生させる場合であればオーディオバッファ・インスタンスを取得してから
  audioBuffer.getChannelData( n );  ※ n: 0 または 1
を実行することで同じ配列を取り出すことができます。


このコードを実行して、マイクから音声入力するとこんな感じで音声が折れ線グラフ表示されます(以下はモノラルの例):
2018100201


最初はチンプンカンプンでしたが、だんだんオーディオバッファの中身がわかってきました。 v(^o^)


このページのトップヘ