Metadata Service

Overview

Virtual machine cloud services like AWS EC2 and Google GCE provide simple metadata services that allow a VM to obtain data about itself, such as its identity or network configuration.

The Metadata Service provides similar functionality, letting an IoT SIM device obtain subscriber information about itself and perform basic management tasks directly from the device over HTTP. With Metadata Service, you can get basic information about an IoT SIM, such as IMSI and subscription status, as well as modify its Speed Class or Tags, without using an SDK or implementing the Soracom API into your application. Since the Metadata Service is handled directly between the device and the Soracom platform, no additional authentication or encryption is required.

Internally, when an IoT SIM device requests the Metadata Service using the /subscriber endpoint, Soracom will check the IMSI of the IoT SIM and map the request endpoint to /subscribers/{IMSI}. This means that all APIs underneath /subscribers/{IMSI} are available to an IoT SIM via Metadata Service. For the full list of available endpoint, refer to the Subscriber API in the API Reference.

Configuration

The Metadata Service option is found within Soracom Air for Cellular Group settings.

Login to the User Console. From the Menu, open the Groups screen.
From the list of groups, click the name of the group you want to configure to open its settings page.

You can also open the group settings page directly from the SIM Management screen. Simply find a SIM that currently belongs to the group you want to configure, then click the group name.
From the Basic Settings tab, click the SORACOM Air for Cellular panel to expand its settings.

https://console.soracom.io
Enable the Metadata Service option by switching the option to ON.
Configure any of the Options below.
Click the Save button at the bottom of the panel.

Once saved, the Metadata Service will be immediately available to any subscribers in the group.

Options

Readonly - Controls whether devices can perform API write operations, such as modifying Speed Class, when using the Metadata Service. This does not affect the ability to use the Soracom API directly.
Allow Origin - Adds a Access-Control-Allow-Origin header to the HTTP response for CORS (Cross-Origin Resource Sharing). When accessing the Metadata Service through an external resource (such as an AJAX request), you can specify the external origin to allow the request.
User data - Any user-defined data. An Air subscriber can access this user data content from http://metadata.soracom.io/v1/userdata.

Basic Usage

Since Metadata Service is remapping requests from /subscriber to the /subscribers/{IMSI} API, we have access to all APIs underneath the Subscriber API. Typically, when using the Soracom API directly, we have to include an API key and token in the HTTPS request header in order to authorize the API call. However, since requests originating from an IoT SIM device are already authenticated using cellular network SIM authentication, there is no need to obtain and include an access token.

Get the device IMSI

From your device, you can make the following HTTP request:

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

Metadata Service will return an HTTP response similar to the following:

{
  "imsi": "295050012345678",
  "msisdn": "423012345678",
  "ipAddress": "10.123.45.67",
  "operatorId": "OP0012345678",
  "apn": "soracom.io",
  "type": "s1.standard",
  "groupId": "abcdef00-0000-0000-0000-000012345678",
  "status": "active",
  "tags": {
    "name": "my-sim"
  },
  "sessionStatus": {
    "imei": "860000012345678",
    "cell": {
      "radioType": "lte",
      "mcc": 310,
      "mnc": 410,
      "lac": 42973,
      "sac": 14702,
      "rac": 255
    },
    "ueIpAddress": "10.123.45.67",
    "dnsServers": [
      "100.127.0.53",
      "100.127.1.53"
    ],
    "online": true
  },
  "speedClass": "s1.standard",
  "moduleType": "trio",
  "plan": 1,
  "iccid": "8942310000012345678",
  "subscription": "plan01s"
}

You can then parse the response to extract the IMSI. For example, if accessing the Metadata Service directly from a Linux shell environment with jq installed, you can pipe the output like this:

curl -s http://metadata.soracom.io/v1/subscriber | jq -r .imsi
>295000012345678

Change the Speed Class

With the regular Soracom API, we would normally make an API call to the updateSpeedClass API as follows:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "speedClass": "s1.standard"
>      }' \
>  https://api.soracom.io/v1/subscribers/295050012345678/update_speed_class

Since Metadata Service will remap the API call for us and doesn't require an API key and token, we can simplify the API call:

curl -X POST \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "speedClass": "s1.standard"
>      }' \
>  http://metadata.soracom.io/v1/subscriber/update_speed_class

We should get an HTTP response similar to the response above, indicating our updated speed class. We can similarly pipe the output using | jq .speedClass to filter the response.

Notice that our HTTP request using the Metadata Service does not require us to specify the IoT SIM IMSI in the request URL — Soracom gets that automatically from the network carrier! This means that we can implement the API request as a generalized call within our code. Then, when we deploy the code across multiple devices, the IMSI will automatically be filled in by Soracom.

We can use the same method for accessing other /subscribers/{IMSI} APIs.

Note that when accessing APIs that modify the properties of an IoT SIM, the Metadata Service Readonly option must be unchecked.

Accessing User Data

In addition to accessing the /subscribers/{IMSI} APIs, Metadata Service allows us to enter user-defined content that an IoT SIM device can access directly at http://metadata.soracom.io/v1/userdata.

For example, the following User data:

Hello, world!

Will return the following on the device:

curl -s http://metadata.soracom.io/v1/userdata
>Hello, world!

We can take advantage of the text being returned to our device's environment. For example, if our device has a Linux shell environment, we can change our User data to the following:

#!/bin/bash
echo Hello! My IMSI is $( curl -s http://metadata.soracom.io/v1/subscriber | jq -r .imsi )

Now when we run the same HTTP request, we can simply pipe the response to bash to execute:

curl -s http://metadata.soracom.io/v1/userdata | bash
>Hello! My IMSI is 295000012345678

This technique can be adapted for a variety of use cases, such as defining what firmware version a remote device should download or running an initialization script, all of which can be configured from the Soracom platform rather than being manually defined on the device.

Advanced Configuration

Metadata Service settings can also be configured through the Soracom API or CLI by using the SoracomAir namespace.

Configuration Structure

"SoracomAir": {
  "metadata": {
    "enabled": true|false,
    "readonly": true|false,
    "allowOrigin": ""
  },
  "userdata": "",
  // additional SoracomAir settings
}

Parameters

Configure Metadata Service settings:

key - metadata
value (object, required) - Metadata Service options.
- enabled (boolean, default: false) - Enables or disables the Metadata Service option.
- readonly (boolean, default: true) - Enables or disables a device's ability to modify values through the Metadata Service.
- allowOrigin (string, default: "") - Returns a Access-Control-Allow-Origin header with the HTTP response for use with CORS.

Modify userdata parameter:

key - userdata
value (string, default: "") - Arbitrary data that can be accessed from a device using /userdata endpoint.

Example

The following configuration will set and enable Metadata Service:

[
  {
    "key": "metadata",
    "value": {
      "enabled": true,
      "readonly": true,
      "allowOrigin": "http://my.example.com"
    }
  },
  {
    "key": "userdata",
    "value": "my custom data"
  }
]

Programmatic Usage

You can use the advanced configuration structure to configure the Metadata Service option programmatically using the Soracom API and Soracom CLI.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the putConfigurationParameters API with the SoracomAir namespace to set the Metadata Service option:

Global
Japan

curl -X PUT \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '[
>        {
>          "key": "metadata",
>          "value": {
>            "enabled": true,
>            "readonly": true,
>            "allowOrigin": "http://my.example.com"
>          }
>        },
>        {
>          "key": "userdata",
>          "value": "my custom data"
>        }
>      ]' \
>  https://g.api.soracom.io/v1/groups/<GROUP-ID>/configuration/SoracomAir

curl -X PUT \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '[
>        {
>          "key": "metadata",
>          "value": {
>            "enabled": true,
>            "readonly": true,
>            "allowOrigin": "http://my.example.com"
>          }
>        },
>        {
>          "key": "userdata",
>          "value": "my custom data"
>        }
>      ]' \
>  https://jp.api.soracom.io/v1/groups/<GROUP-ID>/configuration/SoracomAir

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, run the following command to set the Metadata Service option:

Global
Japan

soracom groups put-config --group-id "<GROUP-ID>" --namespace "SoracomAir" --body "<CONFIG>" --coverage-type g

soracom groups put-config --group-id "<GROUP-ID>" --namespace "SoracomAir" --body "<CONFIG>" --coverage-type jp

Here, the JSON array from the API example above should be passed in to the --body parameter.