SORACOM Users

SORACOM Funk
機能の説明

SORACOM Funk の仕組み

Funk の仕組みは以下の通りです。

Funk概要

1. クラウドサービスの Function を作成

クラウドサービスの Function サービスを設定します。 Funk は AWS Lambda , GCP Cloud Functions, Azure Functions に対応しています。

2. Funk を実行

Funk のエンドポイントに対して 任意のデバイス、プロトコルを利用し、 Funk を実行します。
Funk は通信方式 3G/LTE, LoRaWAN, Sigfox に対応し、通信プロトコルでは TCP, UDP, HTTP, SMS, USSD, LPWA に対応しています。

3. クラウドサービスの Function で認証

Funk からクラウドサービスへアクセスする際に、HTTP(S)ヘッダにトークンを付与できます。
そのトークンを検証することで、任意の回線やデバイスからのアクセスであることを認証できます。

SORACOM Funk の利用

SORACOM Funk の設定

Funk は利用する IoT SIM の所属するグループに設定します。利用するクラウドサービスや送信するデータの形式、認証情報を指定できます。
グループの設定方法はこちらを参照してください。

Funk の設定の例と各キーの説明は、以下のとおりです。

設定の例

AWS Lambda の場合

resourceUrlとして AWS Lambda の ARN を指定する際に末尾に :VERSION を指定することで呼び出すAWS Lambda の Version を指定できます。

"SoracomFunk": {
    "destination": {
        "provider": "aws",
        "service": "lambda",
        "resourceUrl": "AWS Lambda の ARN"
    },
    "credentialsId": {
        "$credentialsId": "AWS 認証情報"
    },
    "contentType": "application/json",
    "enabled": true
}

Azure Functions の場合

"SoracomFunk": {
    "destination": {
        "provider": "azure",
        "service": "function-app",
        "resourceUrl": "Azure functions の URL"
    },
    "credentialsId": {
        "$credentialsId": "Azure 認証情報"
    },
    "contentType": "application/json",
    "enabled": true
}

GCP Functions の場合

"SoracomFunk": {
    "destination": {
        "provider": "google",
        "service": "cloud-functions",
        "resourceUrl": "GCP Functions のURL"
    },
    "contentType": "application/json",
    "enabled": true
}

各キーの説明

SORACOM Funk のエンドポイント

デバイスから Funk を実行するエンドポイントは以下の通りです。Unified Endpointにも対応します。

通信プロトコル エンドポイント/宛先番号
HTTP http://funk.soracom.io
TCP funk.soracom.io:23080
UDP funk.soracom.io:23080
SMS 901041
USSD 901041

SORACOM Funk の送信するデータフォーマット

Funk は利用するクラウドに応じたデータフォーマットを送信します。

AWS Lambda に渡されるデータ

{
  "custom": {
    "srn": "srn:soracom:OP00XXXXXXXX:jp:Subscriber:44052XXXXXXXXXXX",
    "operatorId": "OP00XXXXXXXX",
    "sourceProtocol": "udp",
    "resourceId": "44052XXXXXXXXXXX",
    "resourceType": "Subscriber",
    "imsi": "44052XXXXXXXXXXX",
    "imei": "35956XXXXXXXXXX"
  }
}

Azure Functions / GCP Functions に渡されるデータ

以下のデータフォーマットが渡されます。

SORACOM Funk のトークンを検証する

HTTP(S) ヘッダーの x-soracom-token に設定された JWT ヘッダーを検証することで、任意のデバイスからの通信であることを検証できます。
トークンは Json Web Token (JWT)フォーマットとなっており、各種プログラミング言語向けの JWT ライブラリを用いることで含まれる情報の取得や、改ざんなどがされていないかどうかを簡単に確認できます。

上記のトークンを JWT の仕様に従ってデコードすると、下記のような情報がペイロードに含まれています。

{
  "iss": "https://soracom.io",
  "aud": "srn:soracom:OP00XXXXXXXX:jp:Subscriber:44052XXXXXXXXXXX",
  "jti": "4i2qn8oqu78",
  "iat": 1558673437,
  "typ": "soracom/token/v1",
  "sub": "funk.soracom.io",
  "ctx": {
    "srn": "srn:soracom:OP00XXXXXXXX:jp:Subscriber:44052XXXXXXXXXXX",
    "operatorId": "OP9012345678",
    "sourceProtocol": "udp",
    "resrouceId": "440101234567890",
    "resrouceType": "Subscriber",
    "imsi": "440101234567890"
  }
}

トークンは、SORACOM が持つ秘密鍵でその内容に署名がなされており、対応する公開鍵をダウンロードしていただくことで改ざんがされていないかどうか検証することが出来ます。
公開鍵のファイル名はトークンのヘッダ部分にkidという属性名で含まれています。

{
  "kid": "v1-f2fea060b93f510bfb722fXXXXXXXXXX-x509.pem",
  "alg": "RS256"
}

上記の例の場合、 v1-f2fea060b93f510bfb722fXXXXXXXXXX-x509.pem が公開鍵のファイル名となります。

署名検証に用いる公開鍵は、 https://s3-ap-northeast-1.amazonaws.com/soracom-public-keys/ 以下に保存して配信しており、この URL にヘッダ内の公開鍵のファイル名を連結すると、そのトークンの検証に利用可能な公開鍵の URL となります。

つまり、上記例の場合、署名検証に必要な公開鍵は https://s3-ap-northeast-1.amazonaws.com/soracom-public-keys/v1-f2fea060b93f510bfb722fXXXXXXXXXX-x509.pem からダウンロードできます。
この公開鍵を利用することでトークンの検証が可能となります。

SORACOM Funk のエラー

Funk は利用するクラウドからのエラーレスポンスを返却します。
以下は Unified Endpoint を利用した際の Unified 形式の例です。

{
    statusCode: 207,
    body: { 
        "result": "ng",
        "detail": { 
            "beam": { statusCode: 200, body: "...." },
            "funnel": { statusCode: 204, body: "...." },
            "funk": { statusCode: 400, body: "...." },
            "harvest": { statusCode: 400, body: "...." }
        }
    }
}

SORACOM Funk の料金

SORACOM Funk の料金はSORACOM Funk ご利用料金 をご確認ください。

pagetop