翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# C2C コネクタインターフェイスオペレーションの実装
Managed Integrations for は、コネクタとして認定するために処理 AWS Lambda する必要がある 4 つのオペレーション AWS IoT Device Management を定義します。C2C コネクタは、以下の各オペレーションを実装する必要があります。
1. `AWS.ActivateUser` - AWS IoT Device Management マネージド統合サービスでは、この API を呼び出してグローバルに一意のユーザー識別子を取得します。OAuth 2.0 の場合、これは提供された OAuth 2.0 トークンに関連付けられます。このオペレーションは、オプションでアカウントリンクプロセスの追加要件を実行するために使用できます。
1. `AWS.DiscoverDevices` - マネージド統合 AWS IoT Device Management サービスでは、この API をコネクタに呼び出してユーザーのデバイスを検出します。
1. `AWS.SendCommand` - マネージド統合 AWS IoT Device Management サービスがこの API をコネクタに呼び出して、ユーザーのデバイス用のコマンドを送信します。
1. `AWS.DeactivateUser` - Managed Integrations for AWS IoT Device Management Service は、この API をコネクタに呼び出して、認可サーバーでリンクを解除するためのユーザーのアクセストークンを非アクティブ化します。
## 呼び出しの詳細
Managed Integrations for AWS IoT Device Management は常に、 AWS Lambda `invokeFunction`アクションを通じて JSON 文字列ペイロードを使用して Lambda 関数を呼び出します。リクエストオペレーションでは、すべてのリクエストペイロードに `operationName`フィールドを含める必要があります。
**呼び出し設定:**
+ **タイムアウト:** 呼び出しあたり 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`オペレーションを実装する必要があります。
## リクエスト形式の例
次の例では、すべての必須インターフェイスへの共通フィールドが存在する 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"
}
}
}
```
**ヘッダーパラメータ**
| | | |
| --- |--- |--- |
| フィールド | 必須/オプション | [Description] (説明) |
| `header:auth` | はい | コネクタの登録中に C2C コネクタビルダーによって提供される認可情報。 |
| `header:auth:token` | 条件付き | サードパーティーのクラウドプロバイダーによって生成され、 にリンクされたユーザーの認可トークン`connectorAssociationID`。OAuth 2.0 に必須、一般認可には存在しません。 |
| `header:auth:secretsManager` | 条件付き | AWS Secrets Manager 認可認証情報を含む ARN とバージョン ID。一般認可に必須。OAuth 2.0 には存在しません。 |
| `header:auth:type` | はい | 認可のタイプ: `OAuth2.0`または `GeneralAuthorization`。 |
**注記**
コネクタへのすべてのリクエストには、認可情報が含まれます。OAuth 2.0 の場合、これにはエンドユーザーのアクセストークンが含まれます。一般認可の場合、これには AWS Secrets Manager ARN とバージョン ID が含まれます。適切な認可が既に確立されていることを前提とすることができます。
## リクエストペイロード
一般的なヘッダーに加えて、すべてのリクエストにはペイロードがあります。このペイロードにはオペレーションタイプごとに一意のフィールドがありますが、各ペイロードには、常に存在する一連のデフォルトフィールドがあります。
**リクエストペイロードフィールド:**
+ `operationName`: 指定されたリクエストのオペレーション。、`AWS.ActivateUser`、`AWS.SendCommand`、 `AWS.DiscoverDevices`のいずれかの値に相当します`AWS.DeactivateUser`。
+ `operationVersion`: すべてのオペレーションは、時間の経過とともに進化し、サードパーティーコネクタの安定したインターフェイス定義を提供するようにバージョン管理されています。マネージド統合は、すべてのリクエストのペイロードでバージョンフィールドを渡します。
+ `connectorId`: リクエストが送信されたコネクタの ID。
## デフォルトのレスポンスヘッダー
すべてのオペレーションは、AWS IoT Device Management のマネージド統合`ACK`に で応答し、C2C コネクタがリクエストを受信して処理を開始したことを確認します。
**Example 一般的なレスポンスの例**
```
{
"header":{
"responseCode": 200
},
"payload":{
"responseMessage": “Example response!”
}
}
```
**Example レスポンスヘッダー形式**
```
{
"header": {
"responseCode": Integer
}
}
```
**デフォルトのレスポンスヘッダーとフィールド**
| | | |
| --- |--- |--- |
| フィールド | 必須/オプション | [Comment] (コメント) |
| `header:responseCode` | はい | リクエストの実行ステータスを示す値の ENUM。 |
このドキュメントで説明されているさまざまなコネクタインターフェイスと 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 期待します。
+ 上記で定義したレスポンス形式を使用して同期的に応答する
+ DEVICE\_DISCOVERY イベントを使用して `SendConnectorEvent` API を呼び出す
`SendConnectorEvent` API コールは、C2C コネクタの Lambda AWS アカウント 認証情報にアクセスできる任意の場所で実行できます。AWS IoT Device Management のマネージド統合がこのイベントを受信するまで、デバイス検出フローは成功しません。
**注記**
または、必要に応じて C2C コネクタの Lambda 呼び出しレスポンスの前に `SendConnectorEvent` API コールが発生する場合があります。ただし、このフローはソフトウェア開発の非同期モデルと矛盾します。
コネクタは、AWS IoT Device Management API のこのマネージド統合を呼び出して、デバイスイベントを送信します。3 種類のイベントのみが受け入れられます。
+ **「DEVICE\_DISCOVERY**」 - 特定のアクセストークンのサードパーティークラウド内で検出されたデバイスのリストを送信するために使用されます
+ **「DEVICE\_COMMAND\_RESPONSE**」 - コマンド実行の結果として特定のデバイスイベントを送信するために使用されます
+ **「DEVICE\_EVENT**」 - ユーザーベースのコマンドの直接の結果ではないデバイスから発生するイベントに使用されます。これは、デバイスの状態の変更や通知をプロアクティブに報告するための一般的なイベントタイプとして機能します。