最終更新: 2017/9
このチュートリアルではFlashAir IoT Hub APIの紹介とご利用手順の説明を致します。
FlashAir IoT HubではWebサービスやアプリなどのFlashAirにアクセスするプログラムを開発するために利用できるAPIを提供しています。
FlashAir IoT Hub APIを使ってぜひ皆さんもFlashAirを活用したWebサービスやアプリを開発してみましょう。
本チュートリアルでは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を使ってみましょう。次の手順で行います。
アプリ利用者、アプリ開発者のそれぞれの手順を説明します。
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。 |
タイプ | 必須 |
クライアントの利用形態に合わせた認可方法。
|
スコープ | 必須 |
FlashAir IoT Hub APIのアクセス権限。
|
リダイレクトURL | 必須 | 認可画面にてアクセス認可を行った後、リダイレクトするURL。
リダイレクトする際、認可コードをURLのパラメータに付与しますので、Webサービスやアプリがアクセス可能なURLを指定してください。 |
登録後、アプリのIDが表示されます。IDは認可要求する際に使用します。WebサービスやアプリでこのIDを参照出来る様に実装しましょう。
FlashAir IoT Hubにアクセスするための認可を行います。
FlashAir IoT Hubの認可画面を表示してアプリ利用者から承認を得るようにアプリを実装しましょう。
アクセス認可はFlashAir IoT Hub APIにアクセスして行います。その際、登録したアプリのタイプにより、一部パラメーターや手順が異なります。
まず、基本的なアクセス認可の手順を説明しますので、全体の流れを掴みましょう。
次にタイプ別に詳細を説明しますので、開発したいアプリに合わせてご覧ください。
アクセス認可は次の手順で行います。
アプリ利用者にFlashAir IoT Hubへのアクセス認可が必要であることを知らせ、認可要求のAPIにアクセスしてください。 認可要求のAPIにアクセスするとFlashAir IoT
Hubのログイン画面を表示します。
認可要求のAPIへアクセスするためには
クライアント認証
が必要になります。
アプリ利用者がログインし、アクセス承認すると、認可コードの値をアプリに渡します。
この認可コードは
トークン発行の引き換え券の役割を果たします。
アクセス認可の流れが掴めたでしょうか?次はアプリのタイプ別の手順を説明します。
アプリより以下のパラメータを付与した サーバサイドWebアプリ向け認可要求 のURLにブラウザよりアクセスしましょう。
パラメータ | 要否 | 説明 |
---|---|---|
response_type | 必須 | レスポンスタイプ。
code 固定。 |
client_id | 必須 | クライアントID。開発者向けサイト画面やアプリ詳細画面に表示されるアプリのIDを指定してください。 |
redirect_uri | 省略可 | クライアントのリダイレクトURL。認可要求画面で認可を行った後に表示するページのURLを指定してください。省略時はアプリ登録時にリダイレクトURLで指定した値が使用されます。 |
state | 必須 |
クライアント指定のCSRF対策用乱数文字列。リダイレクトURLのパラメータ
参考: |
scope | 省略可 |
アクセス認可を求めるスコープ文字列。次のいずれかの値を指定してください。空白区切りで複数指定可能です。省略時はアプリ登録時にスコープで指定した値が使用されます。
|
サーバサイドWebアプリ向け認可要求
にアクセスすると、FlashAir IoT Hubのログイン画面を表示します。
アプリ利用者がログインし、認可要求画面にてアクセス承認をすると、
redirect_uri
に次のパラメータを付与してリダイレクトしますので、 そのパラメータを開発したアプリにて取得してください。
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のパラメータ
参考: |
scope | 省略可 |
アクセス認可を求めるスコープ文字列。次のいずれかの値を指定してください。空白区切りで複数指定可能です。省略時はアプリ登録時にスコープで指定した値が使用されます。
|
code_challenge_method | 必須 | チャレンジコードの生成方法。
S256 のみ対応。 |
code_challenge | 必須 |
チャレンジコード。RFC7636のOAuth PKCEに基づき、
BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge 参考: |
モバイル・デスクトップアプリ向け認可要求にアクセスした後の動作 および、認可コードの取得方法は サーバサイドWebアプリ向け認可要求と同様です。
アプリより以下のパラメータを付与した クライアントサイドWebアプリ向け認可要求のURLにアクセスしてください。
パラメータ | 要否 | 説明 |
---|---|---|
response_type | 必須 | レスポンスタイプ。
token 固定。 |
client_id | 必須 | クライアントID。開発者向けサイト画面やアプリ詳細画面に表示されるアプリのIDを指定してください。 |
redirect_uri | 省略可 | クライアントのリダイレクトURL。認可要求画面で認可を行った後に表示するページのURLを指定してください。省略時はアプリ登録時にリダイレクトURLで指定した値が使用されます。 |
state | 必須 |
クライアント指定のCSRF対策用乱数文字列。リダイレクトURLのパラメータ
参考: |
scope | 省略可 |
アクセス認可を求めるスコープ文字列。次のいずれかの値を指定してください。空白区切りで複数指定可能です。
|
クライアントサイドWebアプリ向け認可要求にアクセスした後、ログイン画面を表示するのは サーバサイドWebアプリ向け認可要求と同じですが、 アクセス承認後に直接ユーザートークンが返却される事に注意してください。
承認ボタンをクリックすると、
redirect_uri
に次のパラメータを付与してリダイレクトします。そのパラメータを開発したアプリで取得してください。
Authorization: Bearer <アクセストークン>
Bearer
のみ対応。
state
の値と同じ値であることを検証してください。
例えば、
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アプリの場合は アクセス認可にて、ユーザトークンを発行するため、本作業は不要です。
トークン発行は新規発行と有効期限切れの後に行う更新があります。
更新することで毎回アプリ利用者にアクセス認可させずに新しいユーザートークンが取得出来ますので、ユーザーの利便性上必要でしょう。
ユーザトークンの発行は新規発行と更新の場合、および、アプリのタイプで一部パラメータが異なります。
※更新時のパラメータは各アプリのタイプで共通です。
また、トークンの発行方法によらず トークンの取得方法は全て共通です。
パラメータ | 要否 | 説明 |
---|---|---|
grant_type | 必須 |
グラント種別。
|
code | 必須 | 認可コード。 アクセス認可により取得した認可コードを指定してください。 |
client_id | 必須 | クライアントID。アプリ一覧画面や詳細画面に表示されるIDの値を指定してください。 |
redirect_uri | ※ | クライアントのリダイレクトURL。※
アクセス認可で
redirect_uri を指定した場合、必須。
それ以外は省略可。省略時はアプリ登録時にリダイレクトURLで指定した値が使用されます。 |
パラメータ | 要否 | 説明 |
---|---|---|
grant_type | 必須 |
グラント種別。
|
code | 必須 | 認可コード。 アクセス認可により取得した認可コードを指定してください。 |
client_id | 必須 | クライアントID。アプリ詳細画面に表示されるIDの値を指定してください。 |
redirect_uri | ※ | クライアントのリダイレクトURL。※
アクセス認可で
redirect_uri を指定した場合、必須。
それ以外は省略可。省略時はアプリ登録時にリダイレクトURLで指定した値が使用されます。 |
code_verifier | 必須 | 検証コード。チャレンジコード生成に使用した値。 |
パラメータ | 要否 | 説明 |
---|---|---|
grant_type | 必須 |
グラント種別。
|
refresh_token | 必須 | 更新用トークン。前回、ユーザトークン取得時に取得した
refresh_token の値を指定します。 |
scope | 省略可 |
アクセス認可を求めるスコープ文字列。次のいずれかの値を指定してください。空白区切りで複数指定可能です。省略時はアプリ登録時にスコープで指定した値が使用されます。
|
FlashAir IoT Hub APIにてトークンを発行すると、JSONフォーマットの値が返却されます。以下にサンプルの値を示します。
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}
Authorization: Bearer <アクセストークン>
Bearer
のみ対応。
通常、ユーザトークンはOAuth 2.0に準じ、上記の手順にて発行する必要がありますが、アプリ開発時など第三者にユーザトークンを発行せずに開発者がすぐに使いたい場合、 FlashAir IoT Hubの画面よりユーザトークンを認可なしに発行することが出来ます。
開発用トークンを発行するには、アプリ登録後、一覧からアプリ詳細画面を開き、アクセストークンの 取得するリンクをクリックしてください。
画面にユーザトークンが表示されますので、その値をご使用ください。なお、有効期限がありますので、ご注意ください。
次のチュートリアルではFlashAir IoT Hub APIを実際に使用するサンプルを紹介致します。