みなさんこんにちはソリューションアーキテクトの松本(ysk: ユースケと読みます、ユースケと呼んでください!)です。
今回はSORACOM APIを活用する際に知っておくと便利なTipsをご紹介します。
内容が技術者向け(一般的なHTTP APIの利用方法をご存じの方向け)になっています。そもそもなんでAPIを活用するんだっけ、、、な方はまず先に同僚であるjetのブログ記事 システム連携や自動化に役立つ「SORACOMのAPI」基礎から実際の操作 を是非ご覧ください。
SORACOM API 利用ガイド にも大切なことが記載されています。一度目を通してもらえたらと思います。
ではTipsを紹介していきます!
1. 認証API関連のTips
まずは認証APIについてです。すべての機能APIへのアクセスのベースになる認証APIの使い方のポイントを押えていきましょう。
1. プログラマブルなアクセスには「認証キーID」と「認証キーシークレット」を使いましょう
Tipsを紹介する前に、まずは認証APIの挙動をおさらいします。
SORACOM APIではリクエストを「APIキー」と「APIトークン」のセットで認証します。APIキーとAPIトークンにはリクエストの主体が誰なのか、どんな権限を持つかが記載されていて、リクエストのたびにSORACOM側で内容を検証しています。
SORACOM APIでSIMの一覧を取得する例
curl -X GET \ 'https://api.soracom.io/v1/sims' \ --header 'Content-Type: application/json' \ --header 'X-Soracom-API-Key: api-xxxx' \ --header 'X-Soracom-Token: eyJraxxxx'
X-Soracom-API-Keyヘッダの値が「APIキー」、X-Soracom-Tokenヘッダの値が「APIトークン」です
APIキーとAPIトークンはあらかじめ払い出しておいた「認証キー ID」と「認証キーシークレット」を使って発行します。ちょっとややこしく感じるかもしれませんが、秘密情報を元に一時的な秘密情報を再度発行して、後者をAPIアクセスに使う方式になっています。
SORACOM APIでは認証キー IDと認証キーシークレットを使う方式の他に、「オペレーター ID」、「SAM ユーザー名」、「コンソールログインパスワード」を使ってAPIキーとAPIトークンを発行する方法もありますが、こちらは人向けの方式です。
業務システムとの連携などプログラマブルなAPIアクセスでは認証キー IDと認証シークレットをご利用ください。
認証キー IDと認証キーシークレットのローテーションの方法
認証キー IDと認証キーシークレットはSAMユーザごとに2つまで同時に発行できます。運用上キーを一定期間ごとにローテーションしたい場合でも、もう一つSAMユーザを作って別のキーを発行する必要はありません。一つのSAMユーザで新しいキーを発行してアプリケーションに設定したのち、古いキーを削除すればエラーなく移行できますね。
2. APIトークンには適切な有効期限を設定しキャッシュしましょう
業務システムとの連携のように継続的にSORACOM APIにアクセスするシナリオでは、機能APIへのアクセスのたびに毎回APIトークンを作成するとパフォーマンス上の課題があります。また認証APIでは時間あたりのAPIトークン発行回数に制限があり、頻繁なAPIトークンの発行はできません。SORACOMでは一度作成したAPIトークンをキャッシュして後続のリクエストで再利用する使い方を想定しており、ユースケースにあわせて適切なAPIトークンの有効期限を設定したうえでのキャッシュを推奨します。
トークンの有効期限はAPIトークン作成リクエスト時にパラメータとして指定します。2023年2月現在で、未指定の場合はデフォルトで86,400秒(24時間)で、最小180秒から最大で172,800秒(48時間)までの秒数を指定できます。最新の情報はAPIドキュメントを参照ください。
APIトークンの有効期限が過ぎたあとはAPIリクエストがエラーになります。エラーになる前に更新してください。
また、APIトークンにはトークンを発行した時点での「どのSORACOMサービスにアクセスできるか」の権限 = SAMユーザ(またはロール)の権限が含まれます。権限変更の際にはAPIトークンをリフレッシュするようにしましょう。
2023年2月現在でAPIトークンはJWT方式になっていて、ペイロード部をBase64デコードするとトークンの有効期限( .exp がトークンの有効期限を意味する絶対時間です)や含まれる権限( .operator.permissions がSAMユーザまたロール権限)を確認できます。
ペイロード部のサンプル
{
"iss": "soracom.io",
"aud": "Operator",
"exp": 167581xxxx,
"jti": "xxxxxxxxxxxxxxxxxx",
"iat": 167581xxxx,
"nbf": 167581xxxx,
"sub": "soracom",
"operator": {
"coverageTypes": [
"jp",
"g"
],
"permissions": [
{
"statements": [
{
"effect": "allow",
"api": [
"*"
]
}
]
}
],
"accountType": "0",
"userName": "ysk",
"paymentMethodStatus": "registered",
"operatorId": "OP00xxxxxxxx",
"homeCountry": "JP",
"coverageTypeAttributes": {
"jp": {
"termsVersion": "1",
"paymentMethodStatus": "registered",
"contracts": [
"lagoon"
],
"contractDetail": {
"lagoon": {
"licensePack": {},
"plan": "free",
"availableVersions": [
"classic",
"v2"
]
}
}
},
"g": {
"termsVersion": "2",
"paymentMethodStatus": "registered",
"contracts": [],
"contractDetail": {}
}
}
}
}2. リクエストリトライ関連のTips
APIアクセスでは失敗のハンドリングが、安定な運用を目指すうえで重要なポイントになります。SORACOM APIの利用においてもリトライは重要です。このTipsではどのようなリトライをすべきかご紹介します。
1. リトライが必要なエラー
SORACOM APIからのレスポンスステータスコードに応じてリトライが必要な場合があります。リトライが必要なエラーは大きくわけて次2つの種類に分類できます。
- SORACOM APIで問題が発生していている場合
- SORACOM APIへのアクセスにレート制限を受けている場合
上記いずれも解決には時間がかかる問題です。エラーを検出した際にはSORACOM APIへのアクセスを一時的に停止し、しばらく時間をおいてからリトライする仕組みをご検討ください。
1.1. SORACOM APIで問題が発生している場合
この場合はSORACOM APIからのレスポンスがタイムアウトする、またはレスポンスステータスコードが500番台(500-599)のものが該当します。このエラーを受け取った場合はリトライが必要です。
リトライ戦略はFull JitterのExponential Backoffを推奨します。詳細はAWSブログのExponential Backoff And Jitterの記事を参考にしてみてください。
1.2. SORACOM APIへのアクセスにレート制限を受けている場合
SORACOM APIへのアクセスにはレート制限があります。レート制限の詳細はドキュメントを参照ください。レート制限を受けるとレスポンスステータスコードに429が返ります。429を受け取ったのであればレスポンスヘッダの X-Soracom-Ratelimit-Seconds-Before-Refresh に含まれる値の秒数間、待ってからリトライを行ってください。
レート制限は定期的に水が注がれるコップのようなものです。一度に沢山消費してしまうと、次に水が注がれるまで待たなければなりません。一方でそんなに消費しなかったとしても、コップの容量以上に水を保持しつづけることはできません。
上限の緩和が必要な場合は、ユースケースとご希望の上限をサポート窓口までご相談ください。
2. リトライしてはいけないエラー
APIのレスポンスが400番台(400-499、ただし429を除く)の場合、同じ内容のリクエストをリトライしてはいけません。このエラーが発生する代表的なものとして以下のものがあります。
- APIトークンが期限切れになっている
- APIトークンのアカウントとアクセスしているリソースのアカウントが異なる(アクセス対象のリソース指定が誤っている)
- 必須リクエストパラメータが不足している
- HTTPメソッドの指定が異なる
もし400番台のステータスコードを受け取った場合はリトライをせずリクエストの内容を確認してみてください。もし解決方法で不明点があればサポート窓口までご連絡ください。
3. セキュリティ関連のTips
1. アクセス権限を適切に指定しましょう
APIトークンのアクセス権はSAMユーザ(またはロール)の権限になります。権限は必要最小限に絞って付与します。全ての権限を許可すると予期せぬ操作ミスをした場合の影響が大きくなってしまったりリスクが大きくなります。必要な権限だけを付与するようにしましょう。
良い例: 必要な権限(この例ではSIMのスピードクラスの変更とセッション切断)だけを付与
{
"statements": [
{
"effect": "allow",
"api": [
"Sim:updateSimSpeedClass",
"Sim:deleteSimSession"
]
}
]
}悪い例: 強過ぎる権限(この例では全てのAPI操作権限)を付与
{
"statements": [
{
"effect": "allow",
"api": ["*"]
}
]
}API トークンに付与される権限は、発行時点の権限です。権限を変更した時は、API トークンを新たに再発行しましょう。
2. 監査ログを活用しましょう
SORACOMではお客様のAPIアクセスを記録しておいて、あとから確認できる監査ログ機能を提供しています。標準(無償枠)で24時間以内の認証APIへのアクセスログが閲覧できます。また、期間と対象を拡大するオプション(有償)も用意しています。
お客様でSORACOM APIへのアクセスをレスポンス含めて全て記録に残しておくのは開発コスト、保存しておくストレージコスト、監査ログとしての運用やセキュリティの整理など課題が山盛りです。必要に応じてこの機能を活用して予期していないアクセス元からのAPIアクセスがないか、意図していないAPIへのアクセスがないか定期的に確認していただくと良いのではないでしょうか。
まとめ
今回はSORACOM APIを活用するうえでのTipsを紹介しました。
APIをうまく活用して業務を自動化・省力化したり、安心安全なIoTシステムを実現していきましょう。
― ソラコム松本 (ysk / ユースケ)