Unified Endpoint は常に有効化されています。Unified Endpoint のレスポンスのフォーマットや、SORACOM Binary Format v1 を利用するかどうかを設定できます。
SIM グループ画面、LoRaWAN グループ画面、Sigfox グループ画面、またはデバイスグループ画面で
をクリックします。以下の項目を設定します。
項目 説明 → Unified Endpoint のレスポンスのフォーマットを設定します。詳しくは、レスポンスの形式を設定する を参照してください。 → SORACOM Binary Format v1 に準拠するものとして処理するかどうかを設定します。
では、デバイスから TCP で送信したバイナリデータを、- オン: SORACOM Binary Format v1 に準拠するバイナリデータとして処理される。具体的には、複数のパケットが 1 つのメッセージに変換されてから転送される。
- オフ: 任意のタイミングで転送される。
バイナリパーサーや Orbit と併用する場合の処理順序
バイナリパーサー や Orbit と併用する場合の処理順序については、SORACOM のエントリポイントに送信したデータの処理順序 を参照してください。
Unified Endpoint のレスポンスの形式を設定する
Unified Endpoint のレスポンスのフォーマットは、グループ設定 の → → で変更できます。
レスポンスのフォーマットを固定するには
「Auto (デフォルト)」や「Unified」は、1 つのグループに設定されている転送先の数が変わると、デバイスへのレスポンスのフォーマットが変わります。デバイスではフォーマットが変わることを想定して実装してください。
レスポンスのフォーマットを固定するには、「SORACOM Beam」などの各サービス専用のレスポンス形式、または「カスタム」を選択してください。この場合、デバイスではフォーマットが変わることを想定することなく、シンプルに実装できます。
項目 | 説明 | ||||||
---|---|---|---|---|---|---|---|
Auto (デフォルト) | 1 つのグループに設定されている転送先のうち、送信プロトコルに対応した転送先の数によってレスポンスが変わります。
なお、転送先として数えられる設定は以下のとおりです。
Beam が有効な場合は転送先を数えるときに送信プロトコルも考慮してくださいたとえば、Beam の TCP → HTTP/HTTPS エントリポイントが設定されていた場合、データの送信プロトコルによって、転送先として数えられるかどうかが変わります。
デバイスではフォーマットが変わることを想定して実装してください。 | ||||||
Unified | Unified 形式 でレスポンスが返されます。Unified 形式は、1 つのグループに設定されている転送先のうち、送信プロトコルに対応した転送先の数によってレスポンスに含まれる内容が変わります。 UDP エントリポイントにデータを送信した例:
デバイスでは、転送先の数によってフォーマットが変わることを想定して実装してください。 | ||||||
SORACOM Beam | Beam のレスポンスのみが返されます。他の転送設定がある場合、データは転送しますがその結果は返されません。 例:
| ||||||
SORACOM Funk | Funk のレスポンスのみが返されます。 例:
他の転送設定がある場合、データは転送しますがその結果は返されません。 | ||||||
SORACOM Funnel | Funnel のレスポンスのみが返されます。 例:
他の転送設定がある場合、データは転送しますがその結果は返されません。 Funnel のエントリポイントに送信した場合のレスポンスと、Unified Endpoint に送信した場合のレスポンスは異なります。 | ||||||
SORACOM Harvest Data | Harvest Data のレスポンスのみが返されます。 例:
他の転送設定がある場合、データは転送しますがその結果は返されません。 | ||||||
カスタム | あらかじめ設定したレスポンスが常に返されます。成功時、エラー時のレスポンスをそれぞれ固定できます。詳しくは、カスタムレスポンス機能 を参照してください。
|
UDP エントリポイントや TCP エントリポイントにデータを送信した場合のレスポンスについて
UDP エントリポイントや TCP エントリポイントにデータを送信した場合のレスポンスは、{ステータスコード} {ボディ}
のフォーマットで返されます。
Unified 形式
で「Auto (デフォルト)」を選択して転送先を複数設定したり、「Unified」を選択すると、Unified 形式のレスポンスが返されます。Unified 形式のフォーマットは以下のとおりです。
ステータスコード
すべての転送先へのリクエストが成功した場合は 200
が、ひとつでも失敗した場合は 207
が返されます。
ボディ
プロパティ | 説明 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
result |
| ||||||||||
detail | 各転送先のレスポンスがオブジェクト形式で含まれます。 TCP や UDP で Unified Endpoint に送信した場合も、転送のために HTTP が利用されるため、HTTP 形式で返却されます。 | ||||||||||
detail.${サービス名} (*1) | サービスごとのレスポンスが以下のフォーマットで返されます。
|
(*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" } } }
カスタムレスポンス機能
カスタムレスポンス機能 を参照してください。
で「カスタム」を選択すると、あらかじめ設定したレスポンスが常に返されます。成功時、エラー時のレスポンスをそれぞれ固定できます。詳しくは、
すべての転送先に対して正常に送信できた場合は「成功時のレスポンス」が返却されます。いずれかの転送先でエラーが返却された場合は「失敗時のレスポンス」が返却されます。
設定 | 説明 |
---|---|
成功時および失敗時のステータスコードを指定します | |
レスポンスの Content-Type ヘッダーの値を指定してください。たとえば application/json を指定します。 | |
レスポンスボディの値を指定します。 | |
デフォルトでは、TCP エントリポイントまたは UDP エントリポイントに送信したときのレスポンスは、{ステータスコード} {ボディ} のフォーマットで返されます。チェックを入れると、{ボディ} だけが返されます。 |