翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# C2C コネクタインターフェイスオペレーションの実装
のマネージド統合は、コネクタとして認定するために処理 AWS Lambda する必要がある 4 つのオペレーション AWS IoT Device Management を定義します。C2C コネクタは、以下の各オペレーションを実装する必要があります。
1. `AWS.ActivateUser` - AWS IoT Device Management サービスのマネージド統合は、この API を呼び出して、提供された OAuth2.0 トークンに関連付けられたグローバルに一意のユーザー識別子を取得します。このオペレーションは、オプションでアカウントリンクプロセスの追加要件を実行するために使用できます。
1. `AWS.DiscoverDevices` - AWS IoT Device Management サービス用の マネージド統合は、この API をコネクタに呼び出してユーザーのデバイスを検出します。
1. `AWS.SendCommand` - AWS IoT Device Management サービス用の マネージド統合は、この API をコネクタに呼び出して、ユーザーのデバイス用のコマンドを送信します。
1. `AWS.DeactivateUser` - AWS IoT Device Management サービス用の マネージド統合では、この API をコネクタに呼び出して、ユーザーのアクセストークンを非アクティブ化し、認可サーバーでリンクを解除します。
のマネージド統合は、 AWS IoT Device Management 常に アクションを通じて JSON 文字列ペイロードを使用して Lambda 関数を呼び出します AWS Lambda `invokeFunction`。リクエストオペレーションには、すべてのリクエストペイロードに `operationName`フィールドを含める必要があります。詳細については、 AWS Lambda 「 API [リファレンス」の「呼び出し](https://docs.aws.amazon.com//lambda/latest/api/API_Invoke.html)」を参照してください。
各呼び出しタイムアウトは 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 オペレーションを実装する](discover-devices-op.md)「」、[AWS.SendCommand オペレーションを実装する](send-command-op.md)「」、「」を参照してください[SendConnectorEvent API を使用してデバイスイベントを送信する](send-connector-events.md)。
例えば、C2C コネクタが`DiscoverDevices`リクエストを受信した場合、AWS IoT Device Management のマネージド統合では、上記で定義されたレスポンス形式で同期的に応答することが期待されます。次に、DEVICE\$1DISCOVERY イベントに対して[AWS.DiscoverDevices オペレーションを実装する](discover-devices-op.md)、 で定義されたリクエスト構造を使用して `SendConnectorEvent`API を呼び出す必要があります。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\$1DISCOVERY**」 — このイベントオペレーションは、特定のアクセストークン用にサードパーティークラウド内で検出されたデバイスのリストを送信するために使用されます。
+ **「DEVICE\$1COMMAND\$1RESPONSE**」 – このイベントオペレーションは、コマンド実行の結果として特定のデバイスイベントを送信するために使用されます。
+ **「DEVICE\$1EVENT**」 – このイベントオペレーションは、ユーザーベースのコマンドの直接の結果ではないデバイスから発生したイベントに使用されます。これは、デバイスの状態の変更や通知をプロアクティブに報告するための一般的なイベントタイプとして機能します。