【Ask SORACOM Vol.2】 SORACOM サービスと API の対応が知りたい (2019年版)

カテゴリープラットフォーム

こんにちは、サポートエンジニアの三國です。

ソラコムでは日々たくさんのお客様からお問い合わせを頂いておりますが、多くのお客様のナレッジとできるようなお問い合わせ・回答を不定期に紹介していきたいと思います。SORACOM サービスのご利用にあたって気付きになれば幸いです。

Ask SORACOM 第二回は #ソラコムサンタとのコラボ企画として、以下のご要望にお応えするエントリーです。

API ドキュメントの逆引きが欲しい。サービス名から「このサービスに関連する API はこちら」とリンクがあるだけでもいいので。

こちら他の多くのお客様から同様のご要望をいただいていました。この記事では各サービスに対応する API に簡単なコメントを添えて紹介します。

注意 : 2019 年 12 月 24 日時点での情報となります。

はじめに

SORACOM で一番最初にリリースされたサービスは SORACOM Air for セルラーと SORACOM Beam であることはご存じの方も多いかもしれませんが、実は同じタイミングで重要な機能がリリースされています。それが SORACOM API です。

開発者サイトと API を公開しました – SORACOM エンジニアブログ

私たちは創業当初から SORACOM プラットフォームおよびサービスを制御するシンプルな API を提供し、開発者のみなさまがプログラムやスクリプトを使って多数の IoT デバイスを効率的に管理できるようにしたいと考えていました。API の一番わかりやすい利用例は、お客様が一番最初に、そして一番たくさん触れることになる SORACOM ユーザーコンソールです。SORACOM ユーザーコンソールは SORACOM API を元に構築されています。すなわち、ユーザーコンソールで普段ふれている機能は、ほとんどすべて API で呼び出し可能です。

しかしながら、SORACOM Beam に続いて SORACOM Canal / Direct / Door, Endorse, Funnel, Funk, Gate, Harvest, Inventory, Junction, Krypton, Lagoon, Napter、LTE-M Button powered by AWS と多数のサービスやデバイスのリリースに伴って、サービス名と API の対応が分かりづらくなってきたことも事実です。長期的には各種サービスの Getting Started ドキュメントに API や SORACOM CLI を用いた手順を併記し使いやすくしたいと考えていますが、まずは簡単にサービスと API の対応をご紹介です。

API の使い方や仕様はリファレンスおよび利用ガイドに掲載しています。まず利用ガイドにざっと目を通して全体像を把握してこのエントリに戻っていただくとより分かりやすいと思います。以下の順番で紹介していきます。

SORACOM サービスの管理に使う API
課金・支払・発注の管理に使う API
ユーザー管理関連の API
共通

ここで紹介する「API」とは、API リファレンスでいうサービス名 (SORACOM のサービス名とは異なります)を指しています。この配下に listSubscribers, getSubscriber といったオペレーションがあります。

それではまいりましょう！

1. SORACOM サービスの管理に使う API

SORACOM は、モバイル通信サービスを提供する SORACOM Air に加え、セキュアな IoT / M2M システムの構築を可能にするネットワークサービス、アプリケーション連携サービスを提供しています。まずはここからコネクティビティ、デバイス、ネットワーク、アプリケーションの順に紹介です。

(SORACOM のサービスより引用)

コネクティビティ

SORACOM Air は IoT 向けのコネクティビティを提供する SORACOM の基盤となるサービスです。SIM そのものや LoRaWAN デバイス、Sigfox デバイスの登録・解約・データ取得・グループ変更・タグ追加などは以下の API を利用します。

サービス	対象の API	コメント
Air for Cellular	Subscriber	一番よく使う API と思うのですが Air とも SIM とも Cellular とも関係ないように見えて戸惑われてしまうかもしれません。 API 利用ガイドにあるように SORACOM API を用いて管理する対象の SIM のことを Subscriber と呼んでいます (SIM は Subscriber Identity Module の略)。まずはこの API だけでも使えるようになると楽しいです。
Air for LoRaWAN	LoraDevice, LoraGateway, LoraNetworkSet	Device/Gateway/NetworkSet の違いはSORACOM Air for LoRaWAN のシステム構成がわかりやすいです。
Air for Sigfox	SigfoxDevice

また、関連して以下のような API もあります。

機能	対象の API	コメント
イベントハンドラー機能	EventHandler	イベントハンドラー機能とは特定の SIM・特定のグループ・特定のタグ・全 SIM に対してデータ転送容量の閾値を元に、メールでの通知・速度クラスの変更・AWS Lambda ファンクションを実行できる機能です。実はユーザーコンソールでは指定できないものもあったりしますので一度ガイドをご覧いただくと面白いと思います。
検索	Query	SIM、Sigfox デバイスの検索と SIM 通信量ランキングの取得ができます。

デバイス

チップ型 eSIM と LTE-M 回線で電池で動く LTE-M Button 3 モデルを用意しています。

サービス	対象の API	コメント
LTE-M Button Powered by AWS	Gadget	LTE-M Button for Enterprise と LTE-M Button Plus はそれぞれ通常の SIM として管理しますが、AWS ボタンは専用の API があります。ユーザーコンソールの左側のメニューでも AWS ボタンだけ独立していますね。

ネットワークサービス

お客様の Amazon Web Services (AWS) 仮想プライベートクラウドと SORACOM プラットフォームを直接接続する Canal、専用線で接続する Direct、仮想専用線で接続する Door、お客様のシステムとデバイス間でデバイス LAN 接続を構築する Gate、パケットレベルでのトラフィックの制御ができる Junction 、簡単にセキュアにリモートアクセスできる Napter と多くのサービスがあります。

実は Napter を除くとそれぞれのサービスを直接操作する API はなく、いずれも Virtual Private Gateway (VPG) を操作する API で管理します。

サービス	対象の API	コメント
Canal, Direct, Door, Gate, Junction	VirtualPrivateGateway	VPG は SORACOM の各種サービスを利用する上でとても重要なコンポーネントで、お客様からのリクエストに応じて個別に用意される専用ゲートウェイです。ネットワークサービスをご利用の際はぜひ Virtual Private Gateway 開発者向けガイドをご覧ください。
Napter	PortMapping	NAPT (Network Address Port Translation) 用のアドレス・ポートを割り当てるため PortMapping となります

なお、現時点では Direct と Door のご利用にはお申し込みが必要です。

SORACOM Direct ご利用申請 / SORACOM Door ご利用申請

アプリケーションサービス

アプリケーションサービスはネットワークサービス以上にたくさんありますが、大きくデータ転送 / データ活用 / デバイス支援の 3 つのカテゴリに分かれますのでそれぞれ紹介します。

データ転送

暗号化等の高負荷処理や接続先の設定を、クラウドにオフロードできる Beam、デバイスからのデータを特定のクラウドサービスに直接転送するクラウドリソースアダプター Funnel、クラウドサービスの Function を直接実行できる Funk があります。

サービス	対象の API	コメント
Beam, Funnel, Funk	Group	いずれも SIM グループ / LoRa グループ / Sigfox グループを作成し、対象のサービスを設定し、対象の SIM あるいはデバイスを所属することで使用しますので Group API を使用することになります。グループコンフィギュレーションに詳細が記載されていますが、慣れないうちはまずユーザーコンソールでグループを作成しお好みの設定をしたあとに Group API の getGroup オペレーションでどのような感じで設定が入るのかを見ていただくとイメージが掴めると思います。

データ活用

IoT デバイスからのデータを収集、蓄積する Harvest Data / Harvest Files、ダッシュボードを作成する Lagoon の 2 種類があります。SORACOM でも人気のサービス達です。こちらもデータ転送サービスと同様グループで有効にします。また、保存したデータやファイルを取得するために DataEntry / FileEntry API を使用します。

サービス	対象の API	コメント
Harvest Data	Group, DataEntry	DataEntry は SORACOM Harvest Data のデータを取得する場合などに用います。
Harvest Files	Group, FileEntry	FileEntry は SORACOM Harvest Files のデータを取得する場合などに用います。
Lagoon	Lagoon	ダッシュボードで表示されるデータは上記で取得いただいて、ユーザーやプラン (Free / Maker /Pro) の制御にこちらの API を使います。

デバイス支援

SORACOM が認証プロバイダーとしてデバイスの認証サービスを提供する Endorse、OMA Lightweight M2M (LwM2M) をベースにしたデバイス管理のための Inventory、SIM の認証技術を応用して IoT デバイスのセキュアプロビジョニング（初期設定）を支援する Kryptonの 3 種類があります。

サービス	対象の API	コメント
Endorse, Krypton	Group	Endorse と Krypton は上記と同様グループで有効にしますので Group API ですね。
Inventory	Device, DeviceObjectModel	デバイスを管理するサービスが Inventory と覚えると使いやすいです。ユーザーコンソールのメニューでも独立しているようにオブジェクトモデルの管理などがあり、独立した API となっています。

各サービスの補助機能

コネクティビティ、ネットワークサービス、アプリケーションサービスで共通に使用する補助的な機能ももちろん API で制御できます。

機能	対象の API	コメント
認証情報	Credential	たとえば Beam で使用する接続先の認証情報をまとめて登録できます。デバイスに認証情報を持たせなくともクラウド側で制御できる素敵な機能です。
エラーログ	Log	ユーザーコンソールの「エラーログ」で見られるログも API から取得できます。
監査ログ	AuditLog	リモートアクセスへ Napter でアクセスしたときのログです。1 日分は無料で見られます！詳細は【新機能】SORACOM Napter に監査ログ機能が導入されました – SORACOM エンジニアブログも参照してください。
使用量の計算	Stats	特に SIM の通信量確認によく使われます。Stats から取得できない各サービスの使用量は Billing:exportBilling より課金詳細 CSV をダウンロードして確認します。

2. 課金・支払・発注の管理に使う API

ここまでサービスに関連する API を駆け足で紹介してきましたが、まだまだあります。SORACOM では課金や支払い、発注の管理も API で変更できます。このあたりは見られたり変更されると困るケースもあると思いますので、通常の操作の際は SORACOM Access Management 機能で個別のユーザーを作成し、操作権限をコントロールすることをお勧めします。

機能	対象の API	コメント
課金	Billing	月毎、日毎、過去の課金情報を取得できます。 exportLatestBilling オペレーションで詳細な課金詳細情報 CSV もゲットできます。
支払	Payment	クーポンの登録や支払い履歴の確認、過去の利用明細の取得ができます。
発注	Order	API から在庫状況に応じて自動的に SIM を発注したりできます。また、registerOrderedSIM オペレーションで SIM の受け取り確認も可能です。
配送先	ShippingAddress	配送先の登録・削除も API でできます。SIM を自動発注して任意の配送先にプログラマブルに出荷でき、受け取りができます。

3. ユーザー管理関連の API

もちろんユーザー管理も API で可能です。

機能	対象の API	コメント
オペレーター	Operator	SORACOM プラットフォームの用語では、電気通信事業者としてのアナロジーを使っています。アカウントのことを Operator (オペレーター) と呼んでいます。SORACOM ユーザーコンソールでログインする際のアカウントが Operator に相当します。
SAM ユーザー	User	大規模な IoT システムを構築する際、様々な役割を持つ管理者やプログラムが想定され、全ての管理者やプログラムにすべてのアクセス権限を付与する必要はありません。このような場合に SAM を利用すると、アカウントに関する全操作ができるオペレーターの下に、アクセス権限が限定されたユーザーである「SAM ユーザー」を作成し利用できる API を設定できます。とてもお勧めです。ソラコムでも社員は SAM ユーザーを作成し、重要なサービスの削除などができないように制御しています。
ロール	Role	SAM ユーザーに割り当てるロールを制御できます。

4. 共通

これまでの API に含まれない共通機能を 2 つ紹介します。

機能	対象の API	コメント
ファイルダウンロード	Files	Files は Billing:exportBilling などで async オプションを指定した際に返却される exported_file_id を用いてダウンロードします。Harvest Files (FileEntry) とは違うのでご注意ください。
認証	Auth	API リファレンスのページ上で認証を行ったときもこの API が呼ばれています。API 呼び出しに必要な認証キー ID と認証キーシークレットから API Key と Token をゲットするための API で、非常に地味ですがすべての基本となることから呼び出しランキングトップ 3 の API のひとつでもあります。

まとめ

かなり長くなってしまいましたが、SORACOM API でどのようなことができるかイメージいただけましたら嬉しいです。この記事で見つからないユーザーコンソールの操作や、どのようなリクエストを送っていいか分からないなどありましたら、ブラウザーの開発者ツールを開いてどのようなリクエストが行われているかを見ていただくと、API リファレンスを探索する手がかりになると思います。もちろんお困りの際はユーザーコンソールからサポートチケット経由でご相談ください。

バックナンバーは asksoracom カテゴリで確認できます。

それでは、次回もお楽しみに！