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

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

1. AWS.ActivateUser - AWS IoT Device Management サービスのマネージド統合は、この API を呼び出して、提供された OAuth2.0 トークンに関連付けられたグローバルに一意のユーザー識別子を取得します。このオペレーションは、オプションでアカウントリンクプロセスの追加要件を実行するために使用できます。

2. AWS.DiscoverDevices - AWS IoT Device Management サービス用の マネージド統合は、この API をコネクタに呼び出してユーザーのデバイスを検出します。

3. AWS.SendCommand - AWS IoT Device Management サービス用の マネージド統合は、この API をコネクタに呼び出して、ユーザーのデバイス用のコマンドを送信します。

4. AWS.DeactivateUser - AWS IoT Device Management サービス用の マネージド統合では、この API をコネクタに呼び出して、ユーザーのアクセストークンを非アクティブ化し、認可サーバーでリンクを解除します。

のマネージド統合は、 AWS IoT Device Management 常に アクションを通じて JSON 文字列ペイロードを使用して Lambda 関数を呼び出します AWS Lambda invokeFunction。リクエストオペレーションには、すべてのリクエストペイロードに operationNameフィールドを含める必要があります。詳細については、 AWS Lambda 「 API リファレンス」の「呼び出し」を参照してください。

各呼び出しタイムアウトは 2 秒に設定され、呼び出しが失敗すると 5 回再試行されます。

コネクタに実装する 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);
    };
}

注記

コネクタの開発者はactivateUserManager.activateUser(request)、前の例に示す deviceDiscoveryManager.listDevices(request)、sendCommandManager.sendCommand(request)、、および deactivateUser.deactivateUserオペレーションを実装する必要があります。

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

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

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

デフォルトのヘッダーフィールドは次のとおりです。

{
    "header": {
        "auth": {                 
            "token": string,    // end user's Access Token
            "type": ENUM ["OAuth2.0"], 
        }
    }
}

コネクタによってホストされる API は、次のヘッダーパラメータを処理する必要があります。

デフォルトのヘッダーとフィールド

フィールド	必須/オプション	[Description] (説明)
header:auth	あり	コネクタの登録中に C2C コネクタビルダーによって提供される認可情報。
header:auth:token	あり	サードパーティーのクラウドプロバイダーによって生成され、 にリンクされたユーザーの認可トークンconnectorAssociationID。
header:auth:type	あり	必要な認可のタイプ。

注記

コネクタへのすべてのリクエストには、エンドユーザーのアクセストークンがアタッチされます。エンドユーザーとマネージド統合の顧客との間のアカウントリンクが既に発生していると仮定できます。

リクエストペイロード

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

リクエストペイロードフィールド：

• operationName: 指定されたリクエストのオペレーション。、AWS.ActivateUser、AWS.SendCommand、 AWS.DiscoverDevicesのいずれかの値に相当しますAWS.DeactivateUser。

• operationVersion: すべてのオペレーションは、時間の経過とともに進化し、サードパーティーコネクタの安定したインターフェイス定義を提供するようにバージョン管理されています。 マネージド統合は、すべてのリクエストのペイロードでバージョンフィールドを渡します。

• connectorId: リクエストが送信されたコネクタの ID。

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

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

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

すべてのオペレーションレスポンスには、次の共通ヘッダーが必要です。

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

次の表に、デフォルトのレスポンスヘッダーを示します。

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

フィールド	必須/オプション	[Comment] (コメント)
header:responseCode	あり	リクエストの実行ステータスを示す値の ENUM。

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

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

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

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

例えば、C2C コネクタがDiscoverDevicesリクエストを受信すると、AWS IoT Device Management のマネージド統合では、上記で定義したレスポンス形式で同期的に応答することが期待されます。次に、DEVICE_DISCOVERY イベントに対してAWS.DiscoverDevices オペレーションを実装する、 で定義されたリクエスト構造を使用して SendConnectorEventAPI を呼び出す必要があります。API SendConnectorEvent上の 呼び出しは、C2C コネクタの Lambda AWS アカウント 認証情報にアクセスできる任意の場所で実行できます。AWS IoT Device Management のマネージド統合がこのイベントを受信するまで、デバイス検出フローは成功しません。

注記

または、必要に応じて C2C コネクタの Lambda 呼び出しレスポンスの前に SendConnectorEvent API コールが発生することがあります。ただし、このフローはソフトウェア開発の非同期モデルと矛盾します。

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

  • 「DEVICE_DISCOVERY」 – このイベントオペレーションは、特定のアクセストークンについてサードパーティークラウド内で検出されたデバイスのリストを送信するために使用されます。

  • 「DEVICE_COMMAND_RESPONSE」 – このイベントオペレーションは、コマンド実行の結果として特定のデバイスイベントを送信するために使用されます。

  • 「DEVICE_EVENT」 – このイベントオペレーションは、ユーザーベースのコマンドの直接の結果ではないデバイスから発生したイベントに使用されます。これは、デバイスの状態の変更や通知をプロアクティブに報告するための一般的なイベントタイプとして機能します。