SORACOM Developers

Getting Started

How to use SORACOM Air’s metadata service feature

This page explains how to use SORACOM Air’s metadata service. The metadata service lets you obtain and update a device’s Air SIM card information over HTTP.

Introduction to the metadata service

Virtual machine services in the cloud such as Amazon Web Services (AWS)’ EC2 and Google’s GCE have a feature called “metadata service.” This feature makes it possible to obtain data about a particular instance (such as instance identity documents or network information) over HTTP.

SORACOM Air’s metadata service makes it possible to obtain and update a device’s Air SIM card information over HTTP, directly from the device fitted with an Air SIM card. Various other kinds of actions, such as changing speed or adding tags, can be carried out if write access is permitted. The API can be called with a simple code without needing to use an SDK, even when the API is called on a single device. The device does not need to hold its own credentials, which is useful for maintaining security.

Metadata read/write requests are internally mapped to API requests under https://api.soracom.io/v1/subscribers/{SIM's IMSI} . All APIs can be used so long as they are listed under subscribers/{imsi} in the API reference.

Enabling the metadata service

Go to the SORACOM user console and open the information of the group that includes the Air SIM card in question.

Attention
In order to use the metadata service, a SIM card must be registered to a group. Before enabling the metadata service, first create a group and register the SIM card to the group.

In the list of configuration options, click “SORACOM Air settings” to see the metadata service settings screen.

Metadataservice Configuration

Each value can be explained as follows.

For now, switch metadata service to ON and uncheck the read-only checkbox, as pictured below. Metadataservice Configuration

Now you are ready to use the metadata service.

Accessing the metadata service

The URL of the metadata service (the URL via which a device’s Air SIM card information can be obtained and updated) is as follows. If you access the following URL with a device that uses SORACOM Air,

http://metadata.soracom.io/v1/subscriber

you will get results identical to those obtained by accessing the API, as pictured below.

https://api.soracom.io/v1/subscribers/{SIM's IMSI}

Metadata read/write requests are internally mapped to API requests under https://api.soracom.io/v1/subscribers/{SIM's IMSI}. All APIs can be used so long as they are listed under subscribers/{imsi} in the API reference.

Reading metadata: obtaining subscriber information

Now we obtain information about the subscriber (the SIM). Run the following command from the device with the Air SIM card that is included in the group you created earlier.

$ curl -s http://metadata.soracom.io/v1/subscriber | jq .
{
  "imsi": "44010xxxxxxxxxx",
  "msisdn": "81xxxxxxxxxx",
  "ipAddress": "10.xxx.xxx.xxx",
  "apn": "soracom.io",
  "type": "s1.fast",
  "groupId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": 1437119287341,
  "lastModifiedAt": 1448436038512,
  "expiredAt": null,
  "terminationEnabled": false,
  "status": "active",
  "tags": {
    "name": "moto"
  },
  "sessionStatus": {
    "lastUpdatedAt": 1448419048209,
    "imei": "xxxxxxxxxxxxxxx",
    "location": null,
    "ueIpAddress": "10.yyy.yyy.yyy",
    "dnsServers": [
      "100.127.0.53",
      "100.127.1.53"
    ],
    "online": true
  },
  "speedClass": "s1.fast",
  "moduleType": "nano",
  "plan": 1,
  "expiryTime": null,
  "operatorId": "OPxxxxxxxxxx",
  "createdTime": 1437119287341,
  "lastModifiedTime": 1448436038512
}

Information about the Air SIM card is displayed, such as its ISMI, name, tags, speed class, and others.

Access via an API requires authentication and granting a token. When using the metadata service, however, there are no tokens involved. Authentication is already taken care of on the level of the SIM card, so access over HTTP is sufficient.

Writing metadata example: changing the speed class

Next, we try out write access. We will change the speed class.

$ curl -sX POST -d '{"speedClass":"s1.standard"}' -H 'Content-Type:application/json' \
http://metadata.soracom.io/v1/subscriber/update_speed_class | jq .speedClass
"s1.standard"
$ curl -s http://metadata.soracom.io/v1/subscriber | jq .speedClass
"s1.standard"

Changes to the speed class can be made using only HTTP POST. Where you would usually need an SDK to make an API call, this feature enables you to make an API call with very simple code. It also eliminates the need for a device to hold its own credentials.

Accessing user data

​ A user can set their own data in the “user data” field in the metadata service settings. Possible uses include inserting scripts and the like. The user data is accessible via the following URL.

http://metadata.soracom.io/v1/userdata

For now, we set the user data as pictured below. ​ Metadataservice Configuration

#!/bin/bash
echo THIS IS USERDATA.
echo My name is $(curl -s http://metadata.soracom.io/v1/subscriber | jq -r .tags.name )

Run the following command from the device with the Air SIM card that is included in the group you created.

$ curl -s http://metadata.soracom.io/v1/userdata
#!/bin/bash
echo THIS IS USERDATA.
echo My name is $(curl -s http://metadata.soracom.io/v1/subscriber | jq -r .tags.name )
$ curl -s http://metadata.soracom.io/v1/userdata | bash
THIS IS USERDATA.
My name is (Air SIM 名)

​ By running the command specified in the user data, you can obtain the name of the Air SIM card.

Note
When updating the user data from devices, please authenticate with API Key / API Token and call the putConfigurationParameters API just as when executing other SORACOM API. Because Userdata is updated via Group API.

Use cases

​ You can change your line speed by referencing the tags assigned to the Subscriber via the metadata service. ​ ​

Accessing information a SIM card’s information from a smartphone app

You can change your line speed by referencing the tags assigned to the Subscriber via the metadata service. ​ ​

Managing the device’s firmware

You can save firmware information as user data and manage the device via the metadata service. One example of what you can do is change the speed class via the metadata service when an update is available, then return the speed class to normal when the download has finished. ​ ​

Bootstrapping a device

You can save a common initialization script in the user data, then configure the software based on tag information associated with the Subscriber in the script. ​ ​

URL

The current metadata service is accessible via the following URL. ​

Getting Started

SORACOM Air for Cellular

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

Service Detail

Developer Tools

pagetop