C2C コネクタインターフェイスオペレーションの実装

Managed Integrations for は、コネクタとして認定するために処理 AWS Lambda する必要がある 4 つのオペレーション AWS IoT Device Management を定義します。C2C コネクタは、以下の各オペレーションを実装する必要があります。

呼び出しの詳細

Managed Integrations for AWS IoT Device Management は常に、 AWS Lambda invokeFunctionアクションを通じて JSON 文字列ペイロードを使用して Lambda 関数を呼び出します。リクエストオペレーションでは、すべてのリクエストペイロードに operationNameフィールドを含める必要があります。

呼び出し設定:

実装例

コネクタに実装する Lambda は、リクエストペイロードoperationNameから を解析し、対応する機能を実装してサードパーティークラウドにマッピングします。

public ConnectorResponse handleRequest(final ConnectorRequest request) 
        throws OperationFailedException {
    Operation operation;
    try {
        operation = Operation.valueOf(request.payload().operationName());
    } catch (IllegalArgumentException ex) {
        throw new ValidationException(
           "Unknown operation '%s'".formatted(request.payload().operationName()), 
           ex
        );
    }

    return switch (operation) {
        case ActivateUser -> activateUserManager.activateUser(request);
        case DiscoverDevices -> deviceDiscoveryManager.listDevices(request);
        case SendCommand -> sendCommandManager.sendCommand(request);
        case DeactivateUser -> deactivateUser.deactivateUser(request);
    };
}

リクエスト形式の例

次の例では、すべての必須インターフェイスへの共通フィールドが存在する Managed Integrations からの汎用コネクタリクエストについて詳しく説明します。この例では、リクエストヘッダーとリクエストペイロードの両方があることがわかります。リクエストヘッダーは、すべてのオペレーションインターフェイスで共通です。

OAuth 2.0 の例:

{
        "header": {
                "auth": { 
                        "token": "ashriu32yr97feqy7afsaf", 
                        "type": "OAuth2.0"
                }
        },
        "payload":{
                "operationName": "AWS.SendCommand",
                "operationVersion": "1.0",
                "connectorId": "exampleId",
        …
        }
}

一般的な認可の例:

{
        "header": {
                "auth": { 
                        "secretsManager": {
                                "arn": "string",
                                "versionId": "string"
                        },
                        "type": "GeneralAuthorization"
                }
        },
        "payload":{
                "operationName": "AWS.SendCommand",
                "operationVersion": "1.0",
                "connectorId": "exampleId",
        …
        }
}

デフォルトのリクエストヘッダー

デフォルトのヘッダーフィールドは、認可タイプによって異なります。コネクタは、OAuth 2.0 と一般認可リクエストヘッダーの両方を処理する必要があります。

OAuth 2.0 デフォルトヘッダー:

{
    "header": {
        "auth": {
            "token": string,    // End user's Access Token
            "type": "OAuth2.0"
        }
    }
}

一般認可のデフォルトヘッダー:

{
    "header": {
        "auth": {
            "secretsManager": {
                "arn": "string",
                "versionId": "string"
            },
            "type": "GeneralAuthorization"
        }
    }
}

リクエストペイロード

一般的なヘッダーに加えて、すべてのリクエストにはペイロードがあります。このペイロードにはオペレーションタイプごとに一意のフィールドがありますが、各ペイロードには、常に存在する一連のデフォルトフィールドがあります。

デフォルトのレスポンスヘッダー

すべてのオペレーションは、AWS IoT Device Management のマネージド統合ACKに で応答し、C2C コネクタがリクエストを受信して処理を開始したことを確認します。

{
 	"header":{
 		"responseCode": 200 
 	},
 	"payload":{
 		"responseMessage": “Example response!”
 	}
}

{
    "header": {
        "responseCode": Integer
    }
}

レスポンスヘッダーフィールド

このドキュメントで説明されているさまざまなコネクタインターフェイスと API スキーマには、 responseMessageまたは Messageフィールドがあります。これは、C2C コネクタ Lambda がリクエストとその実行に関するコンテキストで応答するために使用されるオプションのフィールドです。以外のステータスコードが発生するエラーには、エラーを説明するメッセージ値を含める200ことをお勧めします。

SendConnectorEvent API を使用して C2C コネクタオペレーションリクエストに応答する

Managed Integrations for では、コネクタが AWS.SendCommandおよび AWS.DiscoverDevicesオペレーションごとに非同期的に動作すること AWS IoT Device Management を想定しています。つまり、これらのオペレーションに対する最初のレスポンスは、C2C コネクタがリクエストを受け取ったことを「承認」するだけです。

SendConnectorEvent API を使用すると、コネクタはAWS.DiscoverDevices、 および AWS.SendCommandオペレーションの以下のリストからイベントタイプと、プロアクティブデバイスイベント (手動でオンまたはオフになっているライトなど) を送信することが期待されます。

ワークフローの例

C2C コネクタがDiscoverDevicesリクエストを受信すると、 の Managed Integrations は次のことを AWS IoT Device Management 期待します。

SendConnectorEvent API コールは、C2C コネクタの Lambda AWS アカウント 認証情報にアクセスできる任意の場所で実行できます。AWS IoT Device Management のマネージド統合がこのイベントを受信するまで、デバイス検出フローは成功しません。

SendConnectorEvent API

コネクタは、AWS IoT Device Management API のこのマネージド統合を呼び出して、デバイスイベントを送信します。3 種類のイベントのみが受け入れられます。