FlashAir IoT Hub APIの使い方

このチュートリアルではFlashAir IoT Hub APIの紹介とご利用手順の説明を致します。

FlashAir IoT HubではWebサービスやアプリなどのFlashAirにアクセスするプログラムを開発するために利用できるAPIを提供しています。
FlashAir IoT Hub APIを使ってぜひ皆さんもFlashAirを活用したWebサービスやアプリを開発してみましょう。

本チュートリアルではAPIを使う準備までを説明しますが、次回以降はAPIを使ったアプリのプログラミングについて、具体例を交えて紹介していますので、アプリ開発の際にご参考にしてみてください。

APIについて

FlashAir IoT Hub API はRESTfulで理解しやすい設計になっています。API仕様はFlashAir IoT Hub APIドキュメント に公開しております。 APIはFlashAir IoT Hub 利用規約 をご承諾の上でご利用ください。

認証について

FlashAir IoT Hub APIには次の認証方法があります。

• デバイス認証

  FlashAir登録にて取得したアクセストークンを使ったBasic認証です。
  FlashAirのGPIOの値など、主にFlashAirからFlashAir IoT Hubへデータ登録する際に使用します。

• クライアント認証

  開発者が登録したアプリか認証します。認証後に発行するアクセストークンは後述するユーザートークン認証の際に必要となります。
  アプリの認証には予め開発者がアプリ登録した際の情報（クライアントIDなど）を使いますので、 開発者はアプリにそれらの情報を埋め込む必要があります。

• ユーザトークン認証

  OAuth 2.0に準じた認証です。主にFlashAir IoT Hub APIに登録されたFlashAirのデータを参照するアプリにて使用します。
  前述のクライアント認証と合わせ、アプリ使用時にユーザがアクセス認可する必要があります。
  本チュートリアルでは、このアクセス認可した際に発行されるアクセストークンをユーザトークンと表記します。

また、各APIで使用する認証方法が決められています。例えば、デバイス認証が指定されているAPIにユーザトークン認証を使用するとエラーとなります。 ただし、複数の認証方法が使用可能なAPIもあります。

各APIの認証方法はFlashAir IoT Hub APIドキュメント をご覧ください。

なお、本チュートリアルでは、OAuth 2.0の詳細な仕様については触れません。以下を参考にしてください。

• OAuth Community
• OAuth.com
• OAuth (Wikipedia)
• RFC6749 (OAuth 2.0)
• RFC6750 (The OAuth 2.0 Bearer Token Usage)
• RFC7636 (OAuth PKCE)
• RFC6749 (OAuth 2.0) 日本語訳
• RFC6750 (The OAuth 2.0 Bearer Token Usage) 日本語訳

ご利用の流れ

FlashAir IoT Hub APIを使ってみましょう。次の手順で行います。

アプリ利用者、アプリ開発者のそれぞれの手順を説明します。

アプリ利用者の手順

FlashAir IoT Hub APIを利用したアプリの使用手順です。

アカウント登録

ご登録・ログインに従い、FlashAir IoT Hubのアカウントをご登録ください。

アクセス認可

アプリがFlashAir IoT Hubのログイン画面を表示します。ご自身（アプリ利用者）のアカウントでログインしてください。

アプリがFlashAir IoT Hubのデータにアクセスして良いか確認しますので、同意する場合は承認ボタンをクリックしてください。

以上でFlashAir IoT Hubを利用したアプリが利用可能になります。

アプリ開発者の手順

アプリでFlashAir IoT Hub APIを利用するための手順です。

アカウント登録

ご登録・ログインに従い、FlashAir IoT Hubのアカウントをご登録ください。

アプリ登録

FlashAir IoT Hub APIの利用にはOAuth 2.0 (RFC6749) および、OAuth PKCE (RFC7636) に準じたアクセス認可が必要です。
アプリの情報を元にアクセス認可を行いますので、必要事項を入力してアプリを登録してください。

FlashAir IoT Hubにログインし、画面の開発者向けサイトリンクをクリックしてください。

開発者向けサイト画面のアプリを追加リンクをクリックしてください。

必要事項を入力し、追加ボタンをクリックすると、アプリが登録されます。

登録後、アプリのIDが表示されます。IDは認可要求する際に使用します。WebサービスやアプリでこのIDを参照出来る様に実装しましょう。

アクセス認可

FlashAir IoT Hubにアクセスするための認可を行います。

FlashAir IoT Hubの認可画面を表示してアプリ利用者から承認を得るようにアプリを実装しましょう。
アクセス認可はFlashAir IoT Hub APIにアクセスして行います。その際、登録したアプリのタイプにより、一部パラメーターや手順が異なります。

まず、基本的なアクセス認可の手順を説明しますので、全体の流れを掴みましょう。
次にタイプ別に詳細を説明しますので、開発したいアプリに合わせてご覧ください。

• アクセス認可の流れ
• サーバーサイドWebアプリの場合
• モバイル/デスクトップアプリの場合
• クライアントサイドWebアプリの場合

アクセス認可の流れ

アクセス認可は次の手順で行います。

1. 認可要求

   アプリ利用者にFlashAir IoT Hubへのアクセス認可が必要であることを知らせ、認可要求のAPIにアクセスしてください。 認可要求のAPIにアクセスするとFlashAir IoT Hubのログイン画面を表示します。
   認可要求のAPIへアクセスするためにはクライアント認証 が必要になります。

2. アクセス承認と認可コードの取得

   アプリ利用者がログインし、アクセス承認すると、認可コードの値をアプリに渡します。
   この認可コードはトークン発行の引き換え券の役割を果たします。

アクセス認可の流れが掴めたでしょうか？次はアプリのタイプ別の手順を説明します。

サーバーサイドWebアプリの場合

認可要求

アプリより以下のパラメータを付与したサーバサイドWebアプリ向け認可要求 のURLにブラウザよりアクセスしましょう。

アクセス承認と認可コードの取得

サーバサイドWebアプリ向け認可要求 にアクセスすると、FlashAir IoT Hubのログイン画面を表示します。
アプリ利用者がログインし、認可要求画面にてアクセス承認をすると、redirect_uriに次のパラメータを付与してリダイレクトしますので、 そのパラメータを開発したアプリにて取得してください。

• code

  認可コード。トークン発行の際に使用します。

• state

  クライアント指定のCSRF対策用乱数文字列。リクエスト時に指定したstateの値と同じ値であることを検証してください。

例えば、redirect_uriがhttps://example.com/callbackの場合、以下の様なURLにリダイレクトされます。

https://example.com/callback?code=xxxxxxxxxxxxxxxxxxxxxx&state=xyz

モバイル/デスクトップアプリの場合

認可要求

アプリより以下のパラメータを付与したモバイル・デスクトップアプリ向け認可要求のURLにアクセスしてください。

BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge

アクセス承認と認可コードの取得

モバイル・デスクトップアプリ向け認可要求にアクセスした後の動作 および、認可コードの取得方法はサーバサイドWebアプリ向け認可要求と同様です。

クライアントサイドWebアプリの場合

認可要求

アプリより以下のパラメータを付与したクライアントサイドWebアプリ向け認可要求のURLにアクセスしてください。

アクセス承認とユーザートークンの取得

クライアントサイドWebアプリ向け認可要求にアクセスした後、ログイン画面を表示するのは サーバサイドWebアプリ向け認可要求と同じですが、 アクセス承認後に直接ユーザートークンが返却される事に注意してください。

承認ボタンをクリックすると、redirect_uriに次のパラメータを付与してリダイレクトします。そのパラメータを開発したアプリで取得してください。

• access_token

  ユーザトークン。ユーザトークン認証を行うFlashAir IoT Hub APIをリクエストする際、HTTPヘッダーに以下を追加してください。

  Authorization: Bearer <アクセストークン>

• token_type

  トークンタイプ。FlashAir IoT Hub APIではBearerのみ対応。

• expires_in

  ユーザトークン有効期限（単位:秒）。発行後、有効期限を経過すると、そのユーザトークンは無効になります。
  その際は新たにユーザトークンを取得してください。

• state

  クライアント指定のCSRF対策用乱数文字列。リクエスト時に指定したstateの値と同じ値であることを検証してください。

• scope

  アクセス認可を求めるスコープ文字列。リクエスト時に指定された値を返却します。

例えば、redirect_uriがhttps://example.com/callbackの場合、以下の様なURLにリダイレクトされます。
パラメータは?ではなく#以降であることに注意してください。

https://example.com/callback#access_token=xxxxxxxxxxxxxxxxxxxx&state=xyz&token_type=bearer&expires_in=86400&scope=user%2eread%20flashair%2eread%20flashair%2ewrite

トークン発行

アクセス認可により、認可コードを入手出来たら、FlashAir IoT Hub APIの トークン発行にてユーザトークンを発行しましょう。
トークン発行のAPIへアクセスするためにはクライアント認証 が必要になります。

クライアントサイドWebアプリの場合はアクセス認可にて、ユーザトークンを発行するため、本作業は不要です。

トークン発行は新規発行と有効期限切れの後に行う更新があります。
更新することで毎回アプリ利用者にアクセス認可させずに新しいユーザートークンが取得出来ますので、ユーザーの利便性上必要でしょう。

ユーザトークンの発行は新規発行と更新の場合、および、アプリのタイプで一部パラメータが異なります。

トークンの発行方法

• 新規発行
• サーバーサイドWebアプリのトークン発行（新規発行）
• モバイル/デスクトップアプリのトークン発行（新規発行）
• 更新
• トークン発行（更新）

  ※更新時のパラメータは各アプリのタイプで共通です。

また、トークンの発行方法によらずトークンの取得方法は全て共通です。

トークンの取得方法

FlashAir IoT Hub APIにてトークンを発行すると、JSONフォーマットの値が返却されます。以下にサンプルの値を示します。

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

• access_token

  ユーザトークン。ユーザトークン認証を行うFlashAir IoT Hub APIをリクエストする際、HTTPヘッダーに以下を追加してください。

  Authorization: Bearer <アクセストークン>

• token_type

  トークンタイプ。FlashAir IoT Hub APIではBearerのみ対応。

• expires_in

  ユーザトークン有効期限（単位:秒）。発行後、有効期限を経過すると、そのユーザトークンは無効になります。
  その際はトークンの更新をして、新たにユーザトークンを取得してください。

• refresh_token

  更新用トークン。同じ認可方法にてユーザートークンを更新する際、使用します。

開発用トークン発行

通常、ユーザトークンはOAuth 2.0に準じ、上記の手順にて発行する必要がありますが、アプリ開発時など第三者にユーザトークンを発行せずに開発者がすぐに使いたい場合、 FlashAir IoT Hubの画面よりユーザトークンを認可なしに発行することが出来ます。

開発用トークンを発行するには、アプリ登録後、一覧からアプリ詳細画面を開き、アクセストークンの取得するリンクをクリックしてください。

画面にユーザトークンが表示されますので、その値をご使用ください。なお、有効期限がありますので、ご注意ください。

次のチュートリアルではFlashAir IoT Hub APIを実際に使用するサンプルを紹介致します。

• ← Luaスクリプトを実行
• FlashAir IoT Hub APIの利用例（サーバーサイドWebアプリ） →