本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 實作 C2C 連接器界面操作
<a name="connector-operations-overview"></a>

的受管整合 AWS IoT Device Management 定義了 AWS Lambda 您必須處理的四個操作，才能符合連接器的資格。您的 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)。

每個調用逾時都會設定為兩秒，如果調用失敗，將會重試五次。

您為連接器實作的 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)`、`sendCommandManager.sendCommand(request)`、 `deviceDiscoveryManager.listDevices(request)`和 `deactivateUser.deactivateUser`操作。

下列範例詳細說明來自 受管整合的一般連接器請求，其中每個必要界面的常見欄位都存在。從範例中，您可以看到同時有請求標頭和請求承載。請求標頭在每個操作界面中都是常見的。

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

## 預設請求標頭
<a name="default-request-headers"></a>

 預設標頭欄位如下所示。

```
{
    "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` | 是 | 所需的授權類型。 | 

**注意**  
連接器的所有請求都會連接最終使用者的存取權杖。您可以假設最終使用者與受管整合客戶之間的帳戶連結已發生。

## 請求承載
<a name="request-payload"></a>

除了常見的標頭，每個請求都會有承載。雖然此承載的每個操作類型都有唯一的欄位，但每個承載都有一組永遠存在的預設欄位。

**請求承載欄位：**
+ `operationName`：指定請求的操作，等於下列其中一個值：`AWS.ActivateUser`、`AWS.SendCommand`、`AWS.DiscoverDevices`、`AWS.DeactivateUser`。
+ `operationVersion`：每個操作都會進行版本化，以允許其隨著時間演進，並為第三方連接器提供穩定的界面定義。 受管整合會在所有請求的承載中傳遞版本欄位。
+ `connectorId`：已傳送請求的連接器 ID。

## 預設回應標頭
<a name="default-response-headers"></a>

每個操作都會使用 回應 AWS IoT Device Management 的`ACK`受管整合，以確認您的 C2C 連接器已收到請求並開始處理。以下是所述回應的一般範例：

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

每個操作回應都必須具有下列常見標頭：

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

下表列出預設回應標頭：


**預設回應標頭和欄位**  

|  |  |  | 
| --- |--- |--- |
| 欄位 | 必要/選用 | 註解 | 
| `header:responseCode` | 是 | 指出請求執行狀態的值 ENUM。 | 

在本文件所述的各種連接器界面和 API 結構描述中，都有 `responseMessage`或 `Message` 欄位。這是選用欄位，用於 C2C 連接器 Lambda 回應有關請求及其執行的任何內容。最好是，導致狀態碼 以外的任何錯誤`200`都應該包含描述錯誤的訊息值。

## 使用 SendConnectorEvent API 回應 C2C 連接器操作請求
<a name="connector-operation-requests"></a>

的受管整合 AWS IoT Device Management 預期您的連接器會針對每個 `AWS.SendCommand`和 `AWS.DiscoverDevices`操作以非同步方式運作。這表示對這些操作的初始回應只是「認可」您的 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 的受管整合預期它會與上述定義的回應格式同步回應。然後，您必須針對 [實作 AWS.DiscoverDevices 操作](discover-devices-op.md)DEVICE\_DISCOVERY 事件，使用 中定義的請求結構叫用 `SendConnectorEvent`API。`SendConnectorEvent` 進行 API 呼叫時，您可以在任何可存取 C2C 連接器 Lambda AWS 帳戶 登入資料的地方進行。在 AWS IoT Device Management 的受管整合收到此事件之前，裝置探索流程不會成功。

**注意**  
或者，如有必要，`SendConnectorEvent`API 呼叫可以在 C2C 連接器 Lambda 調用回應之前進行。不過，此流程與軟體開發的非同步模型相衝突。
+ **SendConnectorEvent** - 連接器會呼叫 AWS IoT Device Management API 的受管整合，將裝置事件傳送至 AWS IoT Device Management 的受管整合。只有 3 種受管整合接受的事件類型：
  + "**DEVICE\_DISCOVERY**" – 此事件操作應用於為特定存取字符傳送第三方雲端內探索的裝置清單。
  + **"DEVICE\_COMMAND\_RESPONSE**" – 此事件操作應用於傳送特定裝置事件，作為命令執行的結果。
  + **"DEVICE\_EVENT**" – 此事件操作應用於源自於裝置的任何事件，而非使用者型命令的直接結果。這可以做為一般事件類型，主動報告裝置狀態變更或通知。