Go to Qiita Advent Calendar 2024 Top
LoginSignup
15
15

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

SORACOMAdvent Calendar 2015

Day 3
@bearmini

soracom-sdk-go ベータ版でいろいろ試す

Last updated at Posted at 2015-12-02

ソラコムの小熊です。

10/26 に札幌で行われたクラスメソッドさん主催のイベント re:Growth 2015 にて、soracom-sdk-go のベータ版を Github 上で公開して開発中であることを発表させて頂きました。

soracom-sdk-go は鋭意開発中ですが、先日発表されたばかりのメタデータサービスなどにも早速対応しました！

ここでは soracom-sdk-go の簡単な使い方を紹介したいと思います。

soracom-sdk-go の基本的な使い方

まず、なにはともあれ github.com/soracom/soracom-sdk-go を go getして import します。

認証を行って API を呼び出すには APIClient を使用します。（通常はこちら）

SIM を搭載しているデバイスなどからメタデータサービスを呼び出すには MetadataClient を使用します。

APIClient

APIClient は以下のようにしてインスタンスを生成し、それを使いまわします。

ac := soracom.NewAPIClient(nil)

引数として APIClient の生成オプションを指定することも可能ですが、主にテスト用なので一般の方は単に nil を指定してください。

APIClient のインスタンスができたら、まずは Auth() を呼び出して認証を行います。
この Auth() は、一度呼び出したら API トークンの有効期限が切れるまでは呼び出す必要がありません。

err := ac.Auth("me@example.com", "SuperSecretP@ssw0rd")

Auth() の引数にはメールアドレスとパスワードを指定します。
認証に失敗すると err が nil 以外の値になります。

ここまでで準備完了です。
あとは好きな API を呼び出しましょう。

MetadataClient

MetadataClient のほうは準備がより簡単です。

mc := soracom.NewMetadataClient(nil)

こちらも APIClient と同様に、引数として生成オプションを指定することも可能ですが主にテスト用なので一般の方は単に nil を指定してください。

メタデータサービスの利用には認証は不要です。
ただし SORACOM Air の SIM を搭載したデバイス等からしか実行できません。

APIClient を用いて呼び出す API

SORACOM API と APIClient の関数の対応は以下のとおりです。

Subscriber 関連の API

Method / Path 関数名
GET /v1/subscribers ListSubscribers()
POST /v1/subscribers/{imsi}/register RegisterSubscriber()
GET /v1/subscribers/{imsi} GetSubscriber()
POST /v1/subscribers/{imsi}/update_speed_class UpdateSubscriberSpeedClass()
POST /v1/subscribers/{imsi}/activate ActivateSubscriber()
POST /v1/subscribers/{imsi}/deactivate DeactivateSubscriber()
POST /v1/subscribers/{imsi}/terminate TerminateSubscriber()
POST /v1/subscribers/{imsi}/enable_termination EnableSubscriberTermination()
POST /v1/subscribers/{imsi}/disable_termination DisableSubscriberTermination()
POST /v1/subscribers/{imsi}/set_expiry_time UpdateSubscriberExpiryTime()
POST /v1/subscribers/{imsi}/unset_expiry_time DeleteSubscriberExpiryTime()
POST /v1/subscribers/{imsi}/set_group SetSubscriberGroup()
POST /v1/subscribers/{imsi}/unset_group UnsetSubscriberGroup()
PUT /v1/subscribers/{imsi}/tags PutSubscriberTags()
DELETE /v1/subscribers/{imsi}/tags/{tag_name} DeleteSubscriberTag()

ここでは例として ListSubscribers() を呼び出してみましょう。

subscribers, _, err := ac.ListSubscribers(nil)

ListSubscribers() の引数には検索オプションなどを指定することができます。
nil を指定すると、保有するすべての Subscriber (SIM) の情報を取得します。

ListSubscribers() は 3 つの値を返します。
最初は Subscriber のスライスです。検索オプションを指定した場合は条件に適合した Subscriber のみ返されます。
2番めは LastEvaluatedKeys で、これは Subscriber の数が多くてページネーションなどをするときに使います。オプションに Limit を指定すると一度に返却される Subscriber の数が制限され、ページネーションすることができます。ここで返ってきた値をオプションの LastEvaluatedKey に指定します。
3つめの戻り値は error です。

Stats 関連の API

Method / Path 関数名
GET /stats/air/subscribers/{imsi} GetAirStats()
GET /stats/beam/subscribers/{imsi} GetBeamStats()
POST /stats/air/operators/{operator_id}/export ExportAirStats()
POST /stats/beam/operators/{operator_id}/export ExportBeamStats()

先ほどの ListSubscribers() で取得した Subscriber のうち先頭のもの (subscribers[0]) に対して、Air の stats（統計情報）を取得してみましょう。

now := time.Now()
from := now.AddDate(0, 0, -1)
airStats, err := ac.GetAirStats(subscribers[0].Imsi, from, now, soracom.StatsPeriodMinutes)

このようなコードで、1日前から現時点までの分精度（実際には約5分単位）の統計情報を取得できます。

Group 関連の API

Method / Path 関数名
GET /groups ListGroups()
POST /groups CreateGroup()
CreateGroupWithName()
DELETE /groups/{group_id} DeleteGroup()
GET /groups/{group_id} GetGroup()
GET /groups/{group_id}/subscribers ListSubscribersInGroup()
PUT /groups/{group_id}/configuration/{namespace} UpdateGroupConfigurations()
UpdateAirConfig()
UpdateBeamTCPConfig()
DELETE /groups/{group_id}/configuration/{namespace}/{name} DeleteGroupConfiguration()
PUT /groups/{group_id}/tags UpdateGroupTags()
DELETE /groups/{group_id}/tags/{tag_name} DeleteGroupTag()

POST /groups に対応する関数が CreateGroup() と CreateGroupWithName() の 2 つ用意されています。
また、PUT /groups/{group_id}/configuration/{namespace} に対応する関数も3つ用意されています。

いずれも、最初の関数が汎用的なもので、残りは特定の状況でより簡単に使えるようにという意図で用意されている関数です。

たとえば CreateGroup() と CreateGroupWithName() を見てみましょう。

POST /groups API としてはグループ作成時にいくつでもタグを指定できます。
とはいえ、グループを作成するときにいきなりたくさんのタグを指定することはあまりないかもしれません。
また、グループの作成時には最低でも名前くらいは指定すると思いますがグループの名前は実はタグで実現されています。（キー名："name"）

ということで、もっともありえそうな「名前付きのグループを作成する」という処理に特化したものが CreateGroupWithName() であり、汎用バージョンの関数である CreateGroup() でも同じことはできますが以下のように CreateGroupWithName() のほうが少し簡単になります。

// CreateGroupWithName()
g1, err := ac.CreateGroupWithName("group name")

// CreateGroup()
g2, err := ac.CreateGroup(soracom.Tags{"name": "group name"})

EventHandler 関連の API

Method / Path 関数名
GET /event_handlers ListEventHandlers()
POST /event_handlers CreateEventHandler()
GET /event_handlers/subscribers/{imsi} ListEventHandlersForSubscriber()
DELETE /event_handlers/{handler_id} DeleteEventHandler()
GET /event_handlers/{handler_id} GetEventHandler()
PUT /event_handlers/{handler_id} PutEventHandler()

ここでは例としてやはり先ほどの ListSubscribers() で取得した Subscriber のうち先頭のもの (subscribers[0]) に対して、EventHandler を作成してみましょう。

imsi := subscribers[0].Imsi
o := &soracom.CreateEventHandlerOptions{
    TargetImsi:  &imsi,
    Status:      "active",
    Name:        "Test Event handler Name",
    Description: "Test Event Handler Description",
    RuleConfig: soracom.RuleConfig{
        Type: soracom.EventHandlerRuleTypeDailyTraffic,
        Properties: soracom.Properties{
            "inactiveTimeoutDateConst":  "BEGINNING_OF_NEXT_MONTH",
            "limitTotalTrafficMegaByte": "1000",
        },
    },
    ActionConfigList: []soracom.ActionConfig{
        soracom.ActionConfig{
            Type: soracom.EventHandlerActionTypeChangeSpeedClass,
            Properties: soracom.Properties{
                "speedClass":             "s1.minimum",
                "executionDateTimeConst": "IMMEDIATELY",
            },
        },
    },
}
err = ac.CreateEventHandler(o)

Operator 関連の API

Method / Path 関数名
POST /operators/{operator_id}/token GenerateAPIToken()
POST /operators/{operator_id}/password UpdatePassword()
POST /operators/{operator_id}/support/token GetSupportToken()
POST /operators CreateOperator()
POST /operators/verify VerifyOperator()
GET /operators/{operator_id} GetOperator()

Operator 関連の API は GenerateAPIToken() 以外は滅多なことでは使わないと思います。

GenerateAPIToken() は新しい API Token を取得します。APIClient は最初の Auth() で取得した API Token を用いて API の呼び出しを行っていますが、その API Token には有効期限があります。その API Token の有効期限内に、GenerateAPIToken() を呼び出して得られた新しい API Token を APIClient にセットすることで、最初の API Token の有効期限を超えて処理を継続することができます。（再度メールアドレスとパスワードで Auth() する必要を減らすことができます）

newToken, err := ac.GenerateToken(0)

引数は有効期限の秒数で、0 を指定するとデフォルト値（24時間）が使われます。
最大値は48時間（48 * 60 * 60）で、負の値は指定できません。（指定しても API がエラーを返します）

MetadataClient を用いて呼び出す API

メタデータ API (http://metadata.soracom.io/v1/) と MetadataClient の関数との関係は以下のとおりです。

Method / Path 関数名
GET /v1/subscriber GetSubscriber()
POST /v1/subscriber/update_speed_class UpdateSpeedClass()
POST /v1/subscriber/enable_termination EnableTermination()
POST /v1/subscriber/disable_termination DisableTermination()
POST /v1/subscriber/set_expiry_time UpdateExpiryTime()
POST /v1/subscriber/unset_expiry_time DeleteExpiryTime()
POST /v1/subscriber/set_group SetGroup()
POST /v1/subscriber/unset_group UnsetGroup()
PUT /v1/subscriber/tags PutTags()
DELETE /v1/subscriber/tags/{tag_name} DeleteTag()
GET /v1/userdata GetUserdata()

MetadataClient を用いて、認証なしで呼び出す API を試してみましょう。

mc := soracom.NewMetadataClient(nil)
sub, err := mc.GetSubscriber()

クライアントを生成してすぐに（認証不要で）自分自身の Subscriber の情報が取得できます。

SORACOM Air で通信しているデバイス上で実行するか、SORACOM Air で通信しているデバイス経由で（テザリングなどで）実行してください。

Deactivate() / Terminate() は危険なので関数を用意していません。
（自分で自分の通信を止めたり解約してしまうとそれ以降通信できなくなり、自分で自分の状態を元に戻したりできなくなるため）
どうしても自分で自分を止めたり解約したいという方がいれば実装するかもしれません。。。

また、Deactivate() できないので Activate() する必要もないため用意していません。

まとめ

いかがだったでしょうか？
駆け足でしたが soracom-sdk-go の簡単なご紹介をしました。

Go の SDK なので、これを使って書かれたアプリはサーバーサイドではもちろんのこと、Linux/Windows/Mac 問わずクライアント PC 上でもバイナリ一つで動作しますし、ARM Linux 向けにビルドすれば Android 上でも動作します。

soracom-sdk-go は外部コンポーネントに依存していないのでビルドも簡単です。

ぜひいろいろ試してみてください。

15
15
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
15
15

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?