デバイスから Funnel のエントリポイントにデータを送信する際に利用可能なプロトコルは、以下のとおりです。
TCP
TCP で送信されたデータを転送先サービスに転送します。
TCP リクエスト
基本的には 1 つの TCP セグメントを 1 つのデータとして転送先サービスに転送します。
デバイスのアプリケーションが TCP で送信したデータは HTTP/HTTPS リクエストで転送されるときに分割 / 結合されることがあります
TCP (RFC 9293 Transmission Control Protocol (TCP)) は、デバイスのアプリケーションが送信したデータを、ネットワークの仕様や通信状況にあわせて適切に TCP セグメントという単位で分割して送信します。そして Funnel では、TCP で受信したデータ (TCP セグメント) を、任意のタイミングで 1 つのリクエストに変換して転送先サーバーに転送します。
その結果、デバイスのアプリケーションが TCP で送信したデータは、アプリケーションが送信した単位 (TCP コネクション単位や TCP セグメント単位) で転送されることは保証されません。たとえば、以下のようなことが発生します。
- デバイスのアプリケーションが送信したデータが、TCP の仕様に従って複数の TCP セグメントに分割されることがあります。その場合、転送先サーバーに複数のリクエストとして転送されることがあります。
- デバイスから 1 つの TCP コネクションで送信した複数のデータが Funnel で結合 (*1) され、1 つのリクエストとして転送されることがあります。
転送先では、デバイスのアプリケーションが送信したデータが分割 / 結合 (*1) されて転送されることも考慮してください。分割 / 結合されることに問題がある場合は、SORACOM Binary Format v1 や、HTTP の利用も検討してください。どちらもデバイスのアプリケーションでの対応が必要です。
- (*1) TCP コネクションを確立してから切断するまでに、アプリケーションが複数のデータを送信した場合に、データが結合されることがあります。TCP コネクションの単位を超えて結合されることはありません。
TCP エントリポイントの最大データ送信サイズ
最大データ送信サイズは、64 KB です。ただし、64 KB のデータを送信するには、SORACOM Binary Format v1 の利用が必要です。
TCP レスポンス
TCP には、HTTP のようなリクエストやレスポンスの概念はありません。そのためデータを送信すると、レスポンスとして以下のデータが TCP エントリポイントからデバイスに対して送信されます。TCP エントリポイントからレスポンスが送信されるタイミングは、転送先サービスへのデータの送信タイミングに基づきます。
| レスポンス | 説明 |
|---|---|
200 (*1) | TCP エントリポイントが期待するデータを受信しました。 |
400 Invalid JSON is sent to funnel. (*1) | TCP エントリポイントは JSON を期待していましたが、JSON として不正なデータを受信しました。 なお、このエラーメッセージのあとに、FIN フラグ付きの TCP パケットが転送先サービスに送信されます。 |
400 Buffer processing is timeout | TCP エントリポイントは、SORACOM Binary Format v1 に準拠したデータを期待していましたが、期待したデータを受信できませんでした。 |
- (*1) バイナリパーサーをオンにしていると、デバイスがどのようなデータを送信しても、バイナリパーサーが JSON 形式のデータに変換して、TCP エントリポイントに出力します。そのため、グループ設定 の → で「JSON」を選択した場合は、送信するデータにかかわらず常に
200が返されます。
以下は、グループ設定の → で「JSON」を選択した場合のデータ送信例です。なお、データ送信例に含まれる ## 以降の部分は説明文です。実際には入力したり表示されたりしません。
$ nc -v funnel.soracom.io 23080
Connection to funnel.soracom.io (100.127.65.43) 23080 port [tcp/*] succeeded!
{"key":"value"} ## JSON を送信すると、次のように `200` がレスポンスされます。
200
bad text ## JSON として不正なテキストを送信すると、次のようにエラーレスポンスが送信されます。
400 Invalid JSON is sent to funnel.
UDP
送信された TCP の 1 パケット (厳密には UDP データグラム) を 1 つのデータとして転送先サービスに転送します。
UDP リクエスト
1 メッセージあたりの最大送信データサイズは、1 つの UDP データグラムで送信できるペイロード長と同じです。
UDP エントリポイントの最大データ送信サイズ
最大データ送信サイズは、1 つの UDP データグラムで送信できるペイロード長です。
UDP レスポンス
UDP には、HTTP のようなリクエストやレスポンスの概念はありません。そのためデータを送信すると、レスポンスとして以下のデータが UDP エントリポイントからデバイスに対して送信されます。UDP エントリポイントからレスポンスが送信されるタイミングは、転送先サービスへのデータの送信タイミングに基づきます。
| レスポンス | 説明 |
|---|---|
200 (*1) | UDP エントリポイントが期待するデータを受信しました。 |
400 Invalid JSON is sent to funnel. (*1) | UDP エントリポイントは JSON を期待していましたが、JSON として不正なデータを受信しました。 なお、このエラーメッセージのあとに、FIN フラグ付きの TCP パケットが転送先サービスに送信されます。 |
400 Buffer processing is timeout | UDP エントリポイントは、SORACOM Binary Format v1 に準拠したデータを期待していましたが、期待したデータを受信できませんでした。 |
- (*1) バイナリパーサーをオンにしていると、デバイスがどのようなデータを送信しても、バイナリパーサーが JSON 形式のデータに変換して、UDP エントリポイントに出力します。そのため、グループ設定 の → で「JSON」を選択した場合は、送信するデータにかかわらず常に
200が返されます。
以下は、グループ設定の → で「JSON」を選択した場合のデータ送信例です。なお、データ送信例に含まれる ## 以降の部分は説明文です。実際には入力したり表示されたりしません。
$ nc -v -u funnel.soracom.io 23080
Connection to funnel.soracom.io port 23080 [udp/*] succeeded! ## 接続成功
## 接続に成功すると、nc は接続確認のために UDP データグラムを送信します。
## グループの設定の [送信データ形式] で「JSON」を選択している場合、以下のようにレスポンスが送信されますが、問題ありません。
400 Invalid JSON is sent to funnel.
400 Invalid JSON is sent to funnel.
400 Invalid JSON is sent to funnel.
400 Invalid JSON is sent to funnel.
400 Invalid JSON is sent to funnel.
{"key":"value"} ## JSON を送信すると、次のように `200` がレスポンスされます。
200
bad text ## JSON として不正なテキストを送信すると、次のようにエラーレスポンスが送信されます。
400 Invalid JSON is sent to funnel.
HTTP
HTTP の POST リクエストのリクエストボディで送信されたデータを、1 つのデータとして転送先サービスに転送します。
HTTP リクエスト
リクエストフォーマットは通常の POST メソッドに準じます。対応する Content-Type ヘッダーは以下のとおりです。
application/jsontext/plainapplication/xml
HTTP エントリポイントの最大データ送信サイズ
最大データ送信サイズは、約 780 KB (800000 バイト) です。
HTTP レスポンス
送信されたリクエストに基づいて、以下のようなレスポンスがデバイスに返されます。レスポンスが送信されるタイミングは、転送先サービスへのメッセージの送信タイミングに基づきます。
| HTTP ステータスコード | レスポンスボディ | 説明 |
|---|---|---|
204 No Content | なし | HTTP エントリポイントが期待するデータを受信しました。
|
400 Bad Request | {"message":"Invalid JSON is sent to funnel."} | HTTP エントリポイントは JSON を期待していましたが、JSON として不正なデータを受信しました。 |
413 | Maximum content-length is: xxxxxx | 送信データサイズが HTTP エントリポイントの最大データ送信サイズ (xxxxxx バイト) を超えているため、転送サービスに転送できません。最大データ送信サイズについては、HTTP リクエスト を参照してください。 |
415 Supported Content-Type are 'application/json', 'text/plain', 'application/xml' and 'text/csv'. Given: xxxxxxxxxx | なし |
|
以下は、グループ設定の → で「JSON」を選択した場合のデータ送信例です。なお、データ送信例に含まれる ## 以降の部分は説明文です。実際には入力したり表示されたりしません。
$ curl -v -d "{\"key\":\"value\"}" -H "Content-Type: application/json" http://funnel.soracom.io
* Trying 100.127.65.43:80...
* Connected to funnel.soracom.io (100.127.65.43) port 80 (#0)
> POST / HTTP/1.1
> Host: funnel.soracom.io
> User-Agent: curl/7.88.1
> Accept: */*
> Content-Type: application/json
> Content-Length: 15
>
< HTTP/1.1 204 No Content ## 204 が返される
< Date: Sun, 12 Jan 2025 05:51:05 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
* Connection #0 to host funnel.soracom.io left intact