共通リソースの利用方法（API仕様など)

前章【My-IoTが提供する共通リソース一覧】に記載した共通リソースのうち、Lambdaを利用した以下のリソースについて説明します。

No.	サービス	用途
2	Lambda	IoTデータへのアクセス
4	Lambda	IoTデータへのアクセス
6	Lambda	イベントデータの登録
8	Lambda	IoT Coreへのメッセージ送信
11	Lambda	一時保存データへのアクセス

No.2 IoTデータへのアクセス

• Lambda関数名：myiot-rel-es-access-lambda

No.1のMy-IoTデータストア（OpenSearch）へのアクセスに利用するLambdaです。
カスタムLambdaからこのLambda関数を呼び出すことで、My-IoTデータストアのデータへアクセスすることが可能になります。

本Lambda関数は、実行基盤にOpenSearchを利用したMy-IoTデータストアが構築されている場合のみ使用することができます。

My-IoTデータストアの種別や、データ検索の際に使用するインデックス名などのMy-IoTデータストアの仕様については My-IoTデータストア仕様 を参照してください。

また、インデックスの指定時に利用するテナントIDは、Lambdaの環境変数から取得することができます。カスタムLambdaで利用できる環境変数については、後述の 環境変数 を参照してください。

カスタムLambdaからクラウドアプリのコネクタIDに紐づいたデータを検索して利用する場合は、 環境変数からクラウドアプリに設定されているコネクタIDを取得し、queryでコネクタIDに紐づいているデータを検索して利用する必要があります。

カスタムLambdaからMy-IoTデータストアにデータを登録する場合は、データ利用の観点からコネクタIDとコネクタ定義に従ってデータを登録することを推奨します。

【参考】用途別のクラウドアプリケーション構築 パターン1、パターン5
【参考】OpenSearch Guide

• 入力（JSON形式）

key名	型	必須	説明
method	文字列	○	操作内容。追加（Post)、検索（Get)。
index	文字列	○	インデックス名。{テナントID}_YYYY.MM.DDの形式で指定する。 テナントIDはカスタムLambdaの環境変数 TENANT_ID より取得可能。
item	dict		追加の場合必須。追加したいデータ（JSON形式）
query	dict		検索の場合必須。検索条件（JSON形式） フォーマットはOpenSearchの検索（_search）APIのリクエスト仕様と同様。

注意

検索結果の件数が多い場合は処理時間が長くなり、30秒以上かかる場合は408エラーが返却されます。

また、レスポンスサイズがAWS Lambdaの制限(6MB)を超過する場合は、500エラーが返却されます。

上記エラーが発生した場合や検索結果の件数が多くなることが予想される場合は、できるだけqueryキーによる条件の絞り込みやsizeパラメータによる取得件数上限の調整(最大10000)、または数回に分割して結果を取得するなどの方法を検討してください。

• 出力（JSON形式）

key名	型	必須	説明
statusCode	数値	○	ステータスコード。正常終了200、不正な引数400、存在しないindex404、タイムアウト408、内部エラー500。OpenSearchアクセス時のエラーコードはそのまま返す。
body	dict	○	実行結果。以下を要素として持つ。
message	文字列		エラーメッセージ。エラー時のみ存在する。
result	dict		検索の場合、引数の条件に合致したデータ（JSON形式）。それ以外は空｛｝。

No.4 IoTデータへのアクセス

• Lambda関数名：myiot-rel-datastore-dynamo-access-lambda

No.3のMy-IoTデータストア（DynamoDB）へのアクセスに利用するLambdaです。
カスタムLambdaからこのLambda関数を呼び出すことで、My-IoTデータストアのデータへアクセスすることが可能になります。

本Lambda関数は、実行基盤にDynamoDBを利用したMy-IoTデータストアが構築されている場合のみ使用することができます。

My-IoTデータストアの種別や、データ検索の際に使用するプロパティ名などのMy-IoTデータストアの仕様については My-IoTデータストア仕様 を参照してください。

入力で指定するテナントIDは、Lambdaの環境変数から取得することができます。カスタムLambdaで利用できる環境変数については、後述の 環境変数 を参照してください。

カスタムLambdaからクラウドアプリのコネクタIDに紐づいたデータを検索して利用する場合は、 環境変数からクラウドアプリに設定されているコネクタIDを取得し、queryでコネクタIDに紐づいているデータを検索して利用する必要があります。

カスタムLambdaからMy-IoTデータストアにデータを登録する場合は、データ利用の観点からコネクタIDとコネクタ定義に従ってデータを登録することを推奨します。

【参考】用途別のクラウドアプリケーション構築 パターン1、パターン5
【参考】DynamoDB のクエリオペレーション - Amazon DynamoDB
【参考】Class: AWS.DynamoDB.DocumentClient — AWS SDK for JavaScript

• 入力（JSON形式）

key名	型	必須	説明
method	文字列	○	操作内容。追加（Post)、検索（Get)。
tenantId	文字列	○	テナントID。 テナントIDはカスタムLambdaの環境変数 TENANT_ID より取得可能。
dates	配列<文字列>		method=Getの場合は必須。 検索する日付を(YYYY.MM.DD)の形式で指定する。最大7個まで指定可能。
item	dict/配列<dict>		method=Postの場合は必須。 データストアに追加するデータをJSON形式で指定する
query	dict		method=Getの場合に指定可能。 検索条件を指定する。以下を要素として持つ。
filterExpression	文字列		フィルタ条件式。 記載方法については 参考資料の Class: AWS.DynamoDB.DocumentClient — AWS SDK for JavaScript を参照してください。
expressionAttributeValues	dict		フィルタに属性値を指定するパラメータ。 記載方法については 参考資料の Class: AWS.DynamoDB.DocumentClient — AWS SDK for JavaScript を参照してください。
expressionAttributeNames	dict		フィルタの予約語をエスケープする際に設定するパラメータ。 記載方法については 参考資料の Class: AWS.DynamoDB.DocumentClient — AWS SDK for JavaScript を参照してください。
option	dict		method=Getの場合に指定可能。 検索条件の補助項目を指定する。以下を要素として持つ。
connectorIds	配列<文字列>		検索するデータのコネクタIDを配列形式で指定する。
limit	数値		取得するデータ数を0以上の数で指定する。指定無しの場合は全件取得を行う。

注意

レスポンスサイズがAWS Lambdaの制限(6MB)を超過する場合は、500エラーが返却されます。

上記エラーが発生した場合や検索結果の件数が多くなることが予想される場合は、できるだけqueryキーによる条件の絞り込みやlimitパラメータによる取得件数上限の調整、または数回に分割して結果を取得するなどの方法を検討してください。

• 出力（JSON形式）

key名	型	必須	説明
statusCode	数値	○	ステータスコード。正常終了200、不正な引数400、内部エラー500。
body	dict	○	実行結果。以下を要素として持つ。
message	文字列		エラーメッセージ。エラー時のみ存在する。
result	配列<dict>		method=Postの場合、追加結果。 method=Getの場合、引数の条件に合致したデータ。

No.6 イベントデータの登録・取得

• Lambda関数名：myiot-rel-event-access-lambda

No.3のイベントテーブル（DynamoDB）にアクセスし、イベントを登録する際に利用するLambdaです。
カスタムLambdaからこのLambda関数を呼び出すことで、イベントテーブルへイベントデータの登録、およびイベントのクローズを行うことができます。

引数に指定するテナントIDやイベントキーは、カスタムLambdaの環境変数より取得することができます。カスタムLambdaで利用できる環境変数については、後述の 環境変数 を参照してください。

注釈

登録したイベントデータは、イベントがクローズされてから1時間後に自動で削除されます。

【参考】用途別のクラウドアプリケーション構築 パターン5

• 入力（JSON形式）

key名	型	必須	説明
method	文字列	○	操作内容。下記のいずれかを指定する。 register: イベントの登録 close: イベントのクローズ get: イベント情報の取得
tenantId	文字列	○	テナントIDを指定する。 テナントIDはカスタムLambdaの環境変数 TENANT_ID より取得可能。
eventKey	文字列		method = registerの場合は必須。 イベントキーを指定する。 イベントキーはカスタムLambdaの環境変数 EVENT_KEY より取得可能。
detail	dict		method = registerの場合は必須。 イベント発火先のカスタムLambda関数へ渡されるペイロードをJSON文字列形式で指定する。
timeout	数値		method = registerの場合に指定可能。 登録したイベントがタイムアウトになるまでの時間を分単位で指定する。 タイムアウトの下限は1分。整数のみ指定可能。
eventId	文字列		method = close, getの場合に指定可能。 method = closeの場合 必須指定。クローズするイベントのイベントIDを指定する method = getの場合 任意指定。取得するイベントのイベントIDを指定する。 指定しない場合はテナント内全てのイベント情報を取得する。

• 出力（JSON形式）

key名	型	必須	説明
statusCode	数値	○	ステータスコード。正常終了200、不正な引数400、存在しないイベントID404、タイムアウト408、内部エラー500。
body	dict	○	実行結果。以下を要素として持つ。
message	文字列		エラーメッセージ。エラー時のみ存在する。
result	dict	○	method = registerの場合、登録結果が返却される。 method = getの場合、取得したイベント情報がJSON形式で返却される。

No.8 IoT Coreへのメッセージ送信

• Lambda関数名：myiot-rel-publish-mqtt-lambda

No.7のIoT Coreを経由してエッジにメッセージを送信する際に利用するLambdaです。
カスタムLambdaからこのLambda関数を呼び出すことで、対象のエッジにメッセージを送信することができます。

引数に指定するテナントIDは、カスタムLambdaの環境変数より取得することができます。カスタムLambdaで利用できる環境変数については、後述の 環境変数 を参照してください。

【参考】用途別のクラウドアプリケーション構築 パターン6
【参考】MQTT

• 入力（JSON形式）

key名	型	必須	説明
tenantId	文字列	○	テナントIDを指定する。 テナントIDはカスタムLambdaの環境変数 TENANT_ID より取得可能。
edgeId	文字列	○	Publish対象のエッジIDを指定する。
payload	dict	○	送信したいメッセージ内容。 JSON文字列に変換されて送信されます。 送信可能なサイズはJSON文字列に変換後のサイズで128KB未満です。
qos	数値	○	QoSの値。0または1が指定可能。

• 出力（JSON形式）

key名	型	必須	説明
statusCode	数値	○	ステータスコード。正常終了200、不正な引数400、タイムアウト408、内部エラー500。
body	dict	○	実行結果。以下を要素として持つ。
message	文字列		エラーメッセージ。エラー時のみ存在する。

No.11 一時保存データへのアクセス

• Lambda関数名：myiot-rel-temporary-data-access-lambda

No.8の一時保存データベース（DynamoDB）へのアクセスに利用するLambdaです。
カスタムLambdaからこのLambda関数を呼び出すことで、一時保存データへアクセスすることが可能になります。
以前の処理結果を利用したい場合などに利用することができます。

引数に指定するテナントIDは、カスタムLambdaの環境変数より取得することができます。カスタムLambdaで利用できる環境変数については、後述の 環境変数 を参照してください。

注意

一時保存データをデータの一時保存以外の用途で使用しないでください。

カスタムLambdaが同時実行された場合など、同じデータへの読み込み・書き込みが複数発生した場合は、意図せずデータが上書きされる可能性があります。

データの整合性は保証できませんのであらかじめご了承ください。

• 入力（JSON形式）

key名	型	必須	説明
method	文字列	○	操作内容。下記のいずれかを指定する。 post: 一時保存データの保存 get: 一時保存データの取得
tenantId	文字列	○	テナントIDを指定する。 テナントIDはカスタムLambdaの環境変数 TENANT_ID より取得可能。
name	文字列	※	一時保存データを識別するデータ名を指定する。 method = postの場合は必須入力となり、入力したデータ名で一時保存データが登録される。 method = getの場合は任意入力となり、未指定の場合はテナントIDとLambda名に紐づいたすべての一時保存データが取得される。
lambdaName	文字列	○	一時保存データを識別するLambda名を指定する。 実行しているカスタムLambdaのLambda名は、AWSの定義済み環境変数 AWS_LAMBDA_FUNCTION_NAME より取得可能。
data	文字列	※	method = postの場合のみ必須入力。 JSON文字列形式で保存するデータを指定する。 JSON文字列全体で400KBまで指定可能。 プロパティ名として以下の文字列は利用不可。 temporaryDataId, name, lambdaName, ttl, createdAt, updatedAt
ttl	文字列		method = postの場合のみ指定可能。 一時保存データの有効期限を指定する。単位は(秒)。 最大604,800秒（7日後）まで指定可能。 保存されたタイミングから指定された秒数だけ一時保存データが保存される。 指定しない場合はデフォルトの有効期限が設定される（保存から1日後まで） 有効期限が経過した場合は、一時保存データは削除される。

注意

入力全体の文字列の大きさがAWS Lambdaの制限(6MB)を超過する場合は、500エラーが返却されます。

一時保存データ名を分けて複数のデータを登録するなどの方法を検討してください。

• 出力（JSON形式）

key名	型	必須	説明
statusCode	数値	○	ステータスコード。正常終了200、不正な引数400、存在しないデータ404、内部エラー500。
body	dict	○	実行結果。以下を要素として持つ。
message	文字列		エラーメッセージ。エラー時のみ存在する。
result	文字列		method = postの場合、登録結果が返却される。 method = getの場合、取得したデータが格納される。
Items	配列<文字列>		method = getの場合、取得したデータのJSON文字列が格納される。

環境変数

カスタムLambdaでは、下記の環境変数が利用可能です。

• AWSで定義されている環境変数

• CloudFormationファイルで設定した環境変数

• My-IoTの定義済み環境変数

カスタムLambdaで使用できる、My-IoTの定義済み環境変数については、下記のとおりです。

環境変数名	説明
TENANT_ID	クラウドアプリをインストールしたユーザーのテナントID
CONNECTOR_INFO	クラウドアプリに設定されているコネクタIDと内包元コネクタID 文字列の1次元配列をJSON文字列に変換したものが格納されている ex: ["connectorID01", "connectorID02"]
EVENT_KEY	イベントによる連携を行う際に必要になるキー イベントを登録する際には、共通Lambdaのパラメータにこのイベントキーを指定する

共通リソースの利用時にテナントIDなどを指定する必要がある場合は、上記の定義済み環境変数から取得して設定してください。