FlashAir IoT Hub APIの使い方

最終更新: 2017/9

概要

このチュートリアルでは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の詳細な仕様については触れません。以下を参考にしてください。

ご利用の流れ

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

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にログインし、画面の 開発者向けサイトリンクをクリックしてください。

開発者向けサイトへのリンク

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

アプリ追加のリンク

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

アプリ情報登録
項目 要否 説明
名前 必須 アプリケーションの名称。
説明 省略可 アプリケーションの概要。
URL 省略可 アプリケーション提供サイトやWeb サービスのURL。
タイプ 必須

クライアントの利用形態に合わせた認可方法。

  • サーバーサイドWebアプリ (Authorization Code)

    Webサーバー上で実行されるWebサービスからの利用を想定した認可方法です。
    RFC6749のOAuth 2.0 Authorization Code Grantに則り、クライアントからのアクセスを認可します。

  • クライアントサイド (JavaScript) Webアプリ (Implicit)

    クライアントにロードされたJavaScriptからの利用を想定した認可方法です。
    RFC6749のOAuth 2.0 Implicit Grantに則り、クライアントからのアクセスを認可します。

  • モバイル/デスクトップアプリ (OAuth PKCE)

    スマートフォン用ネイティブアプリやデスクトップアプリからの利用を想定した認可方法です。
    RFC7636のOAuth PKCEに則り、クライアントからのアクセスを認可します。

スコープ 必須

FlashAir IoT Hub APIのアクセス権限。

  • 参照のみ

    データ取得に関するAPIのみ使用可能です。

  • 参照と変更

    データ参照と変更に関するAPIが使用可能です。

リダイレクトURL 必須 認可画面にてアクセス認可を行った後、リダイレクトするURL。
リダイレクトする際、認可コードをURLのパラメータに付与しますので、Webサービスやアプリがアクセス可能なURLを指定してください。

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

アプリ一覧

アクセス認可

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

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

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

アクセス認可の流れ

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

  1. 認可要求

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

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

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

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

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

認可要求

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

パラメータ 要否 説明
response_type 必須 レスポンスタイプ。 code固定。
client_id 必須 クライアントID。開発者向けサイト画面やアプリ詳細画面に表示されるアプリのIDを指定してください。
redirect_uri 省略可 クライアントのリダイレクトURL。認可要求画面で認可を行った後に表示するページのURLを指定してください。省略時はアプリ登録時にリダイレクトURLで指定した値が使用されます。
state 必須

クライアント指定のCSRF対策用乱数文字列。リダイレクトURLのパラメータ stateに同じ値を付与します。
CSRF対策として、クライアントはこの stateの値とリダイレクトURLに付与された stateの値が同じであることを検証してください。

参考:

scope 省略可

アクセス認可を求めるスコープ文字列。次のいずれかの値を指定してください。空白区切りで複数指定可能です。省略時はアプリ登録時にスコープで指定した値が使用されます。

  • flashair.write
    データ変更の権限を表わす値
  • flashair.read
    データ参照の権限を表わす値
  • user.read
    ユーザー情報参照の権限を表わす値

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

サーバサイド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にアクセスしてください。

パラメータ 要否 説明
response_type 必須 レスポンスタイプ。 code固定。
client_id 必須 クライアントID。開発者向けサイト画面やアプリ詳細画面に表示されるアプリのIDを指定してください。
redirect_uri 省略可 クライアントのリダイレクトURL。認可要求画面で認可を行った後に表示するページのURLを指定してください。省略時はアプリ登録時にリダイレクトURLで指定した値が使用されます。
state 必須

クライアント指定のCSRF対策用乱数文字列。リダイレクトURLのパラメータ stateに同じ値を付与します。
CSRF対策として、クライアントはこの stateの値とリダイレクトURLに付与された stateの値が同じであることを検証してください。

参考:

scope 省略可

アクセス認可を求めるスコープ文字列。次のいずれかの値を指定してください。空白区切りで複数指定可能です。省略時はアプリ登録時にスコープで指定した値が使用されます。

  • flashair.write
    データ変更の権限を表わす値
  • flashair.read
    データ参照の権限を表わす値
  • user.read
    ユーザー情報参照の権限を表わす値
code_challenge_method 必須 チャレンジコードの生成方法。 S256のみ対応。
code_challenge 必須

チャレンジコード。RFC7636のOAuth PKCEに基づき、 code_verifierの値より生成してください。
code_verifierトークン発行の際に使用します。
チャレンジコードの生成方法は S256のみ対応しており、以下の式を満たす必要があります。(RFC7636より引用)

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

参考:


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

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

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

認可要求

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

パラメータ 要否 説明
response_type 必須 レスポンスタイプ。 token固定。
client_id 必須 クライアントID。開発者向けサイト画面やアプリ詳細画面に表示されるアプリのIDを指定してください。
redirect_uri 省略可 クライアントのリダイレクトURL。認可要求画面で認可を行った後に表示するページのURLを指定してください。省略時はアプリ登録時にリダイレクトURLで指定した値が使用されます。
state 必須

クライアント指定のCSRF対策用乱数文字列。リダイレクトURLのパラメータ stateに同じ値を付与します。
CSRF対策として、クライアントはこの stateの値とリダイレクトURLに付与された stateの値が同じであることを検証してください。

参考:

scope 省略可

アクセス認可を求めるスコープ文字列。次のいずれかの値を指定してください。空白区切りで複数指定可能です。

  • flashair.write
    データ変更の権限を表わす値
  • flashair.read
    データ参照の権限を表わす値
  • user.read
    ユーザー情報参照の権限を表わす値

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

クライアントサイド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アプリのトークン発行(新規発行)
パラメータ 要否 説明
grant_type 必須

グラント種別。 authorization_code固定。

code 必須 認可コード。 アクセス認可により取得した認可コードを指定してください。
client_id 必須 クライアントID。アプリ一覧画面や詳細画面に表示されるIDの値を指定してください。
redirect_uri クライアントのリダイレクトURL。※ アクセス認可redirect_uriを指定した場合、必須。
それ以外は省略可。省略時はアプリ登録時にリダイレクトURLで指定した値が使用されます。
モバイル/デスクトップアプリのトークン発行(新規発行)
パラメータ 要否 説明
grant_type 必須

グラント種別。 authorization_code固定。

code 必須 認可コード。 アクセス認可により取得した認可コードを指定してください。
client_id 必須 クライアントID。アプリ詳細画面に表示されるIDの値を指定してください。
redirect_uri クライアントのリダイレクトURL。※ アクセス認可redirect_uriを指定した場合、必須。
それ以外は省略可。省略時はアプリ登録時にリダイレクトURLで指定した値が使用されます。
code_verifier 必須 検証コード。チャレンジコード生成に使用した値。
トークン発行(更新)
パラメータ 要否 説明
grant_type 必須

グラント種別。 refresh_token固定。

refresh_token 必須 更新用トークン。前回、ユーザトークン取得時に取得した refresh_tokenの値を指定します。
scope 省略可

アクセス認可を求めるスコープ文字列。次のいずれかの値を指定してください。空白区切りで複数指定可能です。省略時はアプリ登録時にスコープで指定した値が使用されます。

  • flashair.write
    データ変更の権限を表わす値
  • flashair.read
    データ参照の権限を表わす値
  • user.read
    ユーザー情報参照の権限を表わす値

トークンの取得方法

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を実際に使用するサンプルを紹介致します。