使用方法: レスポンスの形式を設定する | Unified Endpoint (Public beta)

Unified Endpoint のレスポンスのフォーマットは、グループ設定の [Unified Endpoint 設定] → [レスポンス] → [フォーマット] で変更できます。

レスポンスのフォーマットを固定するには

「Auto (デフォルト)」や「Unified」は、1 つのグループに設定されている転送先の数が変わると、デバイスへのレスポンスのフォーマットが変わります。デバイスではフォーマットが変わることを想定して実装してください。

レスポンスのフォーマットを固定するには、「SORACOM Beam」などの各サービス専用のレスポンス形式、または「カスタム」を選択してください。この場合、デバイスではフォーマットが変わることを想定することなく、シンプルに実装できます。

項目説明

Auto (デフォルト)

1 つのグループに設定されている転送先のうち、送信プロトコルに対応した転送先の数によってレスポンスが変わります。

転送先が 1 つだけ設定されている場合は、そのサービスの Unified Endpoint 用のフォーマットでレスポンスが返されます。つまり、以下の 2 つの設定は同じフォーマットのレスポンスが返されます。
- グループ設定の [Unified Endpoint 設定] → [レスポンス] → [フォーマット] で「Auto (デフォルト)」を選択して、[SORACOM Harvest Data 設定] だけを有効化した。
- グループ設定の [Unified Endpoint 設定] → [レスポンス] → [フォーマット] を「SORACOM Harvest Data」に設定した。
転送先が 2 つ以上設定されている場合は、Unified 形式のレスポンスが返されます。

なお、転送先として数えられる設定は以下のとおりです。

グループ設定の [SORACOM Beam 設定]
グループ設定の [SORACOM Funk 設定]
グループ設定の [SORACOM Funnel 設定]
グループ設定の [SORACOM Harvest Data 設定]
Flux の IoT デバイスイベントソースの [グループ] (*1)

(*1) ユーザーコンソールのグループ設定では確認できません。SORACOM CLI / SORACOM API の Group:getGroup API を利用してグループの情報を取得すると確認できます。具体的には、configuration.SoracomFulx.enabled が true の場合は転送先の 1 つとして数えられます。

{
    "operatorId": "OP1234567890",
    "groupId": "12345678-abcd-1234-abcd-123456789010",
    (省略)
    "configuration": {
        "SoracomFlux": {
            "enabled": true,
            "channelId": "1234567890ABCDEFGHIJKLMNOP"
        }
    },
    (省略)
}

Beam が有効な場合は転送先を数えるときに送信プロトコルも考慮してください

たとえば、Beam の TCP → HTTP/HTTPS エントリポイントが設定されていた場合、データの送信プロトコルによって、転送先として数えられるかどうかが変わります。

送信プロトコル	説明
TCP	TCP → HTTP/HTTPS エントリポイントは、転送先として数えられます。
UDP	TCP → HTTP/HTTPS エントリポイントは、転送先として数えられません。

デバイスではフォーマットが変わることを想定して実装してください。

Unified

Unified 形式でレスポンスが返されます。Unified 形式は、1 つのグループに設定されている転送先のうち、送信プロトコルに対応した転送先の数によってレスポンスに含まれる内容が変わります。

例:

$ echo -n "Hello" | nc -u -w10 uni.soracom.io 23080
200 {"result":"ok","detail":{"SoracomBeam":{"statusCode":200,"contentType":"application/json","body":"Hi","headers":{"date":"Thu, 25 Oct 2024 00:00:00 GMT","content-type":"application/json","content-length":"2","connection":"close","x-amzn-requestid":"12345678-90ab-cdef-1234-567890abcdef","x-amzn-trace-id":"Root=1-23456789-0abcdef1234567890abcdef1;Parent=1234567890abcdef;Sampled=0;Lineage=1:83a40c42:0"}},"SoracomFunk":{"statusCode":200,"body":"IkhpIg==","encoding":"base64"},"SoracomHarvest":{"statusCode":201}}}

デバイスではフォーマットが変わることを想定して実装してください。

SORACOM Beam

Beam のレスポンスのみが返されます。他の転送設定がある場合、データは転送しますがその結果は返されません。

例:

$ echo -n "Hello" | nc -u -w10 uni.soracom.io 23080
200 Hi

SORACOM Funk

Funk のレスポンスのみが返されます。

例:

$ echo -n "Hello" | nc -u -w10 uni.soracom.io 23080
200 "Hi"

他の転送設定がある場合、データは転送しますがその結果は返されません。

SORACOM Funnel

Funnel のレスポンスのみが返されます。

例:

$ echo -n "Hello" | nc -u -w10 uni.soracom.io 23080
204

他の転送設定がある場合、データは転送しますがその結果は返されません。

Funnel のエントリポイントに送信した場合のレスポンスと、Unified Endpoint に送信した場合のレスポンスは異なります。

SORACOM Harvest Data

Harvest Data のレスポンスのみが返されます。

例:

$ echo -n "Hello" | nc -u -w10 uni.soracom.io 23080
201

他の転送設定がある場合、データは転送しますがその結果は返されません。

カスタム

あらかじめ設定したレスポンスが常に返されます。成功時、エラー時のレスポンスをそれぞれ固定できます。詳しくは、カスタムレスポンス機能を参照してください。

$ echo -n "Hello" | nc -u -w10 uni.soracom.io 23080
200 {"result":"ok"}

UDP エントリポイントや TCP エントリポイントにデータを送信した場合のレスポンスについて

UDP エントリポイントや TCP エントリポイントにデータを送信した場合のレスポンスは、{ステータスコード} {ボディ} のフォーマットで返されます。

例: [Unified Endpoint 設定] → [レスポンス] → [フォーマット] で「Unified 形式」を選択して、UDP エントリポイントに送信した場合

$ echo -n "Hello" | nc -u -w10 uni.soracom.io 23080
200 {"result":"ok","detail":{"SoracomBeam":{"statusCode":200,"contentType":"application/json","body":"Hi","headers":{"date":"Thu, 25 Oct 2024 00:00:00 GMT","content-type":"application/json","content-length":"2","connection":"close","x-amzn-requestid":"12345678-90ab-cdef-1234-567890abcdef","x-amzn-trace-id":"Root=1-23456789-0abcdef1234567890abcdef1;Parent=1234567890abcdef;Sampled=0;Lineage=1:83a40c42:0"}},"SoracomFunk":{"statusCode":200,"body":"IkhpIg==","encoding":"base64"},"SoracomHarvest":{"statusCode":201}}}

Unified 形式

[フォーマット] で「Auto (デフォルト)」を選択して転送先を複数設定したり、「Unified」を選択すると、Unified 形式のレスポンスが返されます。Unified 形式のフォーマットは以下のとおりです。

ステータスコード

すべての転送先へのリクエストが成功した場合は 200 が、ひとつでも失敗した場合は 207 が返されます。

ボディ

プロパティ説明

result

ok: すべての転送先へのリクエストが成功しました。
ng: 1 つ以上の転送先でエラーが発生しました。
転送先に接続できなかった場合や SORACOM でエラーが発生した場合は、エラー内容に応じたステータスコードが返却されます。1 つ以上の転送先から、HTTP ステータスコードで 400 以上の値が返された場合にエラーが発生したと判断されます。

detail

各転送先のレスポンスがオブジェクト形式で含まれます。

TCP や UDP で Unified Endpoint に送信した場合も、転送のために HTTP が利用されるため、HTTP 形式で返却されます。

detail.${サービス名} (*1)

サービスごとのレスポンスが以下のフォーマットで返されます。

プロパティ	説明
`statusCode`	転送先から返された HTTP ステータスコード。
`body`	転送先から返されたレスポンスの本文。Funk の場合は、常に Base64 形式にエンコードされます。
`headers`	転送先から返されたレスポンスのヘッダー。
`encoding`	レスポンスが Base64 形式でエンコードされている場合は、`base64`。Base64 形式でエンコードされていない場合は、このプロパティは省略されます。

(*1) ${サービス名} は、以下のいずれかです。
- SoracomBeam
- SoracomFunk
- SoracomFunnel
- SoracomHarvest

転送先が設定されていない、またはすべて無効化されている場合は、[フォーマット] の設定にかかわらず 400 Subscriber configuration is not found という文字列が返されます。

レスポンスが返されるタイミングについて

すべての転送先からのレスポンスが返されてから、Unified Endpoint からデバイスにレスポンスが返されます。
Funnel は転送先へのリクエストを非同期に処理します。そのため、転送先にリクエストが転送されるタイミングと、デバイスにレスポンスが返されるタイミングには、差があります。

レスポンスの例

すべての転送先で正常に送信できた場合の例

ステータスコード: 200

ボディ:

{
  "result": "ok",
  "detail": {
    "SoracomBeam": {
      "statusCode": 200,
      "contentType": "text/html;charset=utf-8",
      "body": "Success: {\"temperature\"=>12.3, \"humidity\"=>45.6, \"time\"=>\"2024-09-02T12:34:56.789Z\"}",
      "headers": {
        "content-type": "text/html;charset=utf-8",
        "content-length": "84",
        "x-xss-protection": "1; mode=block",
        "x-content-type-options": "nosniff",
        "x-frame-options": "SAMEORIGIN",
        "connection": "close",
        "server": "thin"
      }
    },
    "SoracomHarvest": {
      "statusCode": 201
    }
  }
}

1 つ以上の転送先からエラーが返却された場合

ステータスコード: 207

ボディ:

{
  "result": "ng",
  "detail": {
    "SoracomBeam": {
      "statusCode": 200,
      "contentType": "text/html;charset=utf-8",
      "body": "Success: {\"temperature\"=>12.3, \"humidity\"=>45.6, \"time\"=>\"2024-09-02T12:34:56.789Z\"}",
      "headers": {
        "content-type": "text/html;charset=utf-8",
        "content-length": "84",
        "x-xss-protection": "1; mode=block",
        "x-content-type-options": "nosniff",
        "x-frame-options": "SAMEORIGIN",
        "connection": "close",
        "server": "thin"
      }
    },
    "SoracomHarvest": {
      "statusCode": 400,
      "body": "Invalid custom timestamp value in request"
    }
  }
}

カスタムレスポンス機能

[フォーマット] で「カスタム」を選択すると、あらかじめ設定したレスポンスが常に返されます。成功時、エラー時のレスポンスをそれぞれ固定できます。詳しくは、カスタムレスポンス機能を参照してください。

unified_endpoint_overview

すべての転送先に対して正常に送信できた場合は「成功時のレスポンス」が返却されます。いずれかの転送先でエラーが返却された場合は「失敗時のレスポンス」が返却されます。

設定	説明
[HTTP ステータスコード]	成功時および失敗時のステータスコードを指定します
[CONTENT-TYPE ヘッダーの値]	レスポンスの `Content-Type` ヘッダーの値を指定してください。たとえば `application/json` を指定します。
[BODY]	レスポンスボディの値を指定します。
[ステータスコードを省略]	デフォルトでは、TCP エントリポイントまたは UDP エントリポイントに送信したときのレスポンスは、`{ステータスコード} {ボディ}` のフォーマットで返されます。チェックを入れると、`{ボディ}` だけが返されます。