Getting Started: Microsoft Azure Event Hubs アダプターを使用する | SORACOM Funnel

Funnel の Microsoft Azure Event Hubs アダプターを使用して、デバイスから送信するデータを Microsoft Azure (以下、Azure) のストリーム処理を行うサービス Event Hubs に送信します。

Funnel の Microsoft Azure Event Hubs アダプターを利用すると、デバイスから直接 Event Hub にデータを送信する場合と比べて、少ない手間で、デバイスと Event Hub を利用した IoT システムを構築できます。主なメリットは以下のとおりです。

デバイスに Azure の SDK をインストールすることなく、Event Hub にデータを送信できます。
認証情報をデバイスに保管する必要はありません。

Azure に Event Hub を作成して、以下の情報を SORACOM に設定し、デバイスから TCP もしくは UDP、HTTP でデータを送信するだけで、Event Hub にデータを転送できます。

お客様の Azure アカウントに作成した Event Hub にアクセスするための認証情報
転送先 URL (Event Hub によって発行される URL)

ステップ 1: Azure を設定する

リソースグループを作成する

Microsoft Azure Portal にアクセスし、検索ボックスに「リソースグループ」を入力して、[リソースグループ] をクリックします。
[＋作成] をクリックします。

以下の項目を設定します。

項目	説明
[サブスクリプション]	任意のサブスクリプションを選択します。
[リソースグループ]	リソースグループの名前を設定します。例: `SoracomFunnelDemo0`
[リージョン]	リソースグループのリージョンを選択します。例: `(Asia Pacific) Japan East`

[確認および作成] をクリックします。

Event Hubs を作成する

ここでは「Event Hubs 名前空間」と「Event Hub」を作成します。

Microsoft Azure Portal にアクセスし、検索ボックスに「Event Hubs」を入力して、[Event Hubs] をクリックします。

Event Hubs 画面が表示されます。まず、「Event Hubs 名前空間」を作成します。
[＋作成] をクリックします。

以下の項目を設定します。

項目	説明
[サブスクリプション]	任意のサブスクリプションを選択します。
[リソースグループ]	リソースグループを作成するで作成したリソースグループを選択します。
[名前空間の名前]	「Event Hubs 名前空間」の名前を設定します。「Event Hubs 名前空間」の名前は、これ以降、${event_hubs_namespace} と表記します。例: `funnel-test`
[場所]	リソースグループから自動的に決定されます。
[価格レベル]	価格レベルを選択します。
[スループットユニット]	スループットユニットを選択します。

[確認と作成] をクリックします。
1 - 2 分経つと「Event Hubs 名前空間」が作成されます。
次に「Event Hub」を作成します。
Event Hubs 画面で、作成した Event Hubs 名前空間をクリックします。
Event Hubs 名前空間画面が表示されます。
[エンティティ] → [Event Hubs] の順にクリックします。
[＋イベントハブ] をクリックします。

以下の項目を設定します。

項目	説明
[名前]	Event Hub の名前を設定します。Event Hub の名前は、これ以降、${event_hub_name} と表記します。例: `event-hub-1`
[パーティション数]	パーティションの数を設定します。

[確認と作成] をクリックします。
Event Hub が作成されます。

RootManageSharedAccessKey のプライマリキーをコピーする

カスタムのポリシーを使うこともできます

RootManageSharedAccessKey を使用せず、自分で権限を限定したポリシーを作成して使用することもできます。その場合、ポリシーには Send 権限を付けてください。

Funnel が Event Hubs へ送信するために、今回は RootManageSharedAccessKey を使用します。

Event Hubs 画面で、作成した Event Hubs 名前空間をクリックします。
[設定] → [共有アクセスポリシー] の順にクリックします。
使用するポリシー (例: RootManageSharedAccessKey) をクリックして、[プライマリキー] をコピーします。

ステップ 2: SORACOM を設定する

認証情報ストアに Azure 認証情報を登録する

Funnel から Azure Event Hubs にデータを送信するために、Azure 認証情報を、SORACOM ユーザーコンソールに登録します。

具体的には、認証情報ストアの「認証情報を登録」画面で以下のように登録します。この画面の表示方法については、認証情報を登録するを参照してください。

項目	説明
[認証情報 ID]	認証情報を識別するために任意の名前を入力します。例: `azure-eventhubs`
[種別]	「Azure 認証情報」を選択します。
[Policy name]	使用するポリシーの名前を入力します。例: `RootManageSharedAccessKey`
[Key]	RootManageSharedAccessKey のプライマリキーをコピーするでコピーしたプライマリキーを入力します。

SORACOM Funnel を有効化する

Funnel の設定はグループに対して行います

ここでは、グループの設定を変更する操作のみを説明します。グループの仕組みやグループを作成する操作について詳しくは、グループ設定を参照してください。

SIM グループ画面で [SORACOM Funnel 設定] をクリックします。
SIM グループ画面を表示する操作について詳しくは、グループの設定を変更するを参照してください。
スイッチをクリックして「ON」にします。

以下の項目を設定します。

項目	説明
[転送先サービス]	「Microsoft Azure Event Hubs」を選択します。
[転送先 URL]	「https://${event_hubs_namespace}.servicebus.windows.net/${event_hub_name}/messages」を入力します。例: `https://funnel-test.servicebus.windows.net/event-hub-1/messages` URL の構造について詳しくは、イベントを送信しますを参照してください。
[認証情報]	認証情報ストアに AWS IAM ロール認証情報を登録するで登録した認証情報を選択します。例: `azure-eventhubs`
[送信データ形式]	ここでは、「JSON」を選択します。[送信データ形式] について詳しくは、SORACOM Funnel から送信されるデータを参照してください。

[保存] をクリックします。
IoT SIM が所属するグループを切り替えます。
IoT SIM の Funnel の設定が完了しました。

ステップ 3: データを送信する

いよいよ、Funnel を使用して、Event Hubs にデータを送信します。

SORACOM Air を使用したデバイス (例として Raspberry Pi + USB ドングル型モデムを想定します) から Unified Endpoint を利用して Funnel にデータを送信します。ここでは Funnel のみが設定されたグループで、Unified Endpoint にリクエストします。

TCP
UDP
HTTP

送信コマンド例

$ nc uni.soracom.io 23080
{"message":"Hello SORACOM Funnel via TCP!"}

上記のように、レスポンスとして 204 が返ってくれば、データ送信に成功しています。

送信コマンド例

$ nc -u uni.soracom.io 23080
{"message":"Hello SORACOM Funnel via UDP!"}

上記のように、レスポンスとして 204 が返ってくれば、データ送信に成功しています。

送信コマンド例

$ curl -v http://uni.soracom.io \
    -d '{"message":"Hello SORACOM Funnel via HTTP!"}' \
    -H "Content-Type: application/json"

* Host uni.soracom.io:80 was resolved.
* IPv6: (none)
* IPv4: 100.127.69.42
*   Trying 100.127.69.42:80...
* Connected to uni.soracom.io (100.127.69.42) port 80
> POST / HTTP/1.1
> Host: uni.soracom.io
> User-Agent: curl/8.7.1
> Accept: */*
> Content-Type:application/json
> Content-Length: 44
> 
* upload completely sent off: 44 bytes
< HTTP/1.1 204 No Content
< Date: Thu, 26 Dec 2024 09:17:32 GMT
< Connection: close
< 
* Closing connection

上記のように、レスポンスとして HTTP/1.1 204 No Content が返ってくれば、データ送信に成功しています。

他のレスポンスコードが返ってきた場合には、レスポンスコードを元に、送信データの形式などを確認してください。

Unified Endpoint からのレスポンスは条件によって変わります

Unified Endpoint のレスポンス形式を設定で変更できます。詳しくは Unified Endpoint のレスポンスの形式を設定するを参照してください。

たとえば、レスポンスフォーマットを「Auto (デフォルト)」にして、Unified Endpoint に HTTP でデータを送信し、Funnel と Harvest Data の 2 つに転送された場合、どちらのデータ送信も成功したときのレスポンスは、次のとおりです。

* Host uni.soracom.io:80 was resolved.
* IPv6: (none)
* IPv4: 100.127.69.42
*   Trying 100.127.69.42:80...
* Connected to uni.soracom.io (100.127.69.42) port 80
> POST / HTTP/1.1
> Host: uni.soracom.io
> User-Agent: curl/8.7.1
> Accept: */*
> content-type:application/json
> Content-Length: 28
> 
* upload completely sent off: 28 bytes
< HTTP/1.1 200 OK
< content-type: application/json
< Date: Thu, 28 Nov 2024 05:33:57 GMT
< Connection: close
< Content-Length: 97
< 
* Closing connection
{"result":"ok","detail":{"SoracomFunnel":{"statusCode":204},"SoracomHarvest":{"statusCode":201}}}%

リクエスト成功時のレスポンスのステータスコードは HTTP/1.1 200 OK です
レスポンスボディに、各サービス (ここでは Funnel と Harvest Data) それぞれへのリクエストの成否が JSON で返されます

ステップ 4: データの送信を確認する

Event Hubs 画面で、作成した Event Hub (例: event-hub-1) をクリックします。
[Data Explorer] をクリックします。
[イベントの表示] をクリックします。

受信したイベントが表示されます。