Soracom API を叩くには API Keyと Tokenのペアが必用となる。
例:
curl -X GET \--header'Accept: application/json'\--header'X-Soracom-API-Key: api-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx'\--header'X-Soracom-Token: eyJQiOiJBUraWUVDQ(以下略)'\'https://api.soracom.io/v1/subscribers/your_imsi/data?sort=desc'この API Keyと TokenをサーバとかLambdaとか、要はUIの無いバックエンドサービスからどう叩くべきか？の話。
基本、公式ドキュメントをはじからはじまでちゃんと目を通せば書いてあるのだが、以下の要因からすげー迷ったので備忘録兼ねて書いとく。
- 巷にあふれる解説記事が API Referenceで暫定的に取得した値を使用する前提のものが多い。
- 認証に係る要素が、
Auth Key ID,Auth Key Secret,API key,Tokenの 4セットあるのだが、- 日本語と英語の表記の空目
API KeyとAuth Key IDがまぎらわしい。- 公式APIでも
Auth Key Secretを入れるべきフィールドをauthKeyってたりするので、仕様書読んでて混乱する。
- 先にAPIリファレンスを斜め読みして、
API Keyで調べて SORACOM API 利用ガイドの 「API Key と API Token」 だけ読むと混乱する。- その数項目先の 「API 呼び出し例」まで読み進めると、認証に係る4つの要素の使い分けをちゃんと理解できる。
- Ruby 以外に公式のSDKが無い。
- 公式ドキュメントにユースケースとベストプラクティスがあんま載ってない。
Overview
- まず、プログラムアクセス用の SAMユーザを作れ。
- AWS の IAM ユーザと同じ理解。
- SAMユーザの 認証キーID (
Auth Key Id) と 認証キーシークレット (Auth Key Secret) は固定で持ってOK。- AWS Secrets Manager で管理するなり、 CIで環境変数に突っ込むなりお好きにどうぞ。
- ただし、これは絶対に漏らしたらNG。漏れたら再発行する。
API KeyとTokenは SAMユーザの認証を通すことによって即時で発行して使い捨てるべきもの。
ちゃんと Overview 理解できてればシンプルで使いやすいよ！
詳細
SAM ユーザ作成
- 基本は公式ドキュメントの通りでOK
- コンソールログイン用のパスワードは設定するな。何のためにSAMユーザ分けたかわからなくなる。
- SAM ユーザーの権限設定 は多分
:list*とか:get*とか。かならず絞るように。
API Key, Token の取得
SORACOM API 利用ガイドの 1. API Key, API Token の取得の SAM ユーザーの API Key と API Token を取得する例を参照のこと。
具体的には以下。
curl -X POST \-H'Content-Type: application/json'\-d'{"authKeyId": "keyId-xxxxxxx", "authKey": "secret-xxxxxxx"}'\
https://api.soracom.io/v1/auth
# Response:# 200 OK## {# "apiKey": "API Key",# "token": "API Token",# "operatorId": "当該OperatorのID",# "userName": "SAMユーザー名"# }なお、node で axios 使う場合はこんな感じ。
constaxios=require('axios');constgetTokenByAuthKey=async(authKeyId,authKeySecret,tokenTimeoutSeconds)=>{consturl='https://api.soracom.io/v1/auth';constbody={authKeyId,authKey:authKeySecret,tokenTimeoutSeconds};constheaders={'Content-Type':'application/json'};constres=awaitaxios.post(url,body,{headers,responseType:'json'});console.log(res.data);constapiKey=res.data.apiKey;consttoken=res.data.token;// const operatorId = res.data.operatorId;return{apiKey,token};};// SAM user の情報 (認証キー ID と認証キーシークレット)constauthKeyId='keyId-xxxxxxxxxxxxxxxxxxxxxxxxxxx';constauthKeySecret='secret-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';// SAM user の認証をかけて、 API Key, Token を取得するconsttokenTimeoutSeconds=3*60;// 最短3分const{apiKey,token}=awaitgetTokenByAuthKey(authKeyId,authKeySecret);// 以降、 apiKey, token を使用して Soracom の API を呼び出しできる。理解すればこんだけ。
tokenTimeoutSecondsは SORACOM API 利用ガイドによれば 「デフォルトでは24時間で、最短3分、最長で48時間まで指定でき」る。- 通常のサーバちっくなデータ取得であれば 3分あれば十分すぎるので、3分で良い認識。
operatorIdは別途設定で持つでいいと思うが、auth のレスポンスで取得できるものを使うでも良さそう。- API設計思想的にどっちを想定してるんだろう？
その他
公式の API Reference読んでも API Key, Tokenをどうやって取得するか書いてないので、ぐぐるじゃないですか？
「API Key と API Token に移動」 するじゃないですか？
え、Token更新し続けろって言ってる？ってなるんすわ。
このページをだーっと下まで読んでいって「1. API Key, API Token の取得」まで行くと、別途SAMユーザと認証キーID/認証キーシークレットがちゃんとあるのね！って理解できる。。。
あと、流石にそろそろ公式で node 版の SDKが欲しいです．．． async/await 対応したやつ．．．．．．
(Soracom Beam 使えってことですよねわかります)