實作 C2C 連接器界面操作

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

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

您為連接器實作的 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”,
 	…
 	}
}

預設請求標頭

預設標頭欄位如下所示。

{
    "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
    }
}

下表列出預設回應標頭：

預設回應標頭和欄位

欄位	必要/選用	註解
header:responseCode	是	表示請求執行狀態的值 ENUM。

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

使用 SendConnectorEvent API 回應 C2C 連接器操作請求

的受管整合 AWS IoT Device Management 預期您的連接器會針對每個 AWS.SendCommand和 AWS.DiscoverDevices操作以非同步方式運作。這表示對這些操作的初始回應只是「認可」您的 C2C 連接器已收到請求。

使用 SendConnectorEvent API，您的連接器預期會將事件類型從下列清單傳送至 AWS.DiscoverDevices和 AWS.SendCommand操作，以及主動裝置事件 （例如手動開啟和關閉的光源）。若要閱讀這些事件類型及其使用案例的詳細說明，請參閱 實作 AWS.DiscoverDevices 操作、 實作 AWS.SendCommand 操作和 使用 SendConnectorEvent API 傳送裝置事件。

例如，如果您的 C2C 連接器收到DiscoverDevices請求，AWS IoT Device Management 的受管整合預期它會與上述定義的回應格式同步回應。然後，您必須實作 AWS.DiscoverDevices 操作針對 DEVICE_DISCOVERY 事件，使用 中定義的請求結構叫用 SendConnectorEventAPI。API SendConnectorEvent上的 呼叫可以發生在您可以存取 C2C 連接器 Lambda AWS 帳戶 登入資料的任何位置。在 AWS IoT Device Management 的受管整合收到此事件之前，裝置探索流程不會成功。

注意

或者，如有必要，SendConnectorEventAPI 呼叫可以在 C2C 連接器 Lambda 調用回應之前進行。不過，此流程與軟體開發的非同步模型相衝突。

• SendConnectorEvent - 連接器會呼叫 AWS IoT Device Management API 的受管整合，將裝置事件傳送至 AWS IoT Device Management 的受管整合。受管整合只接受 3 種類型的事件：

  • "DEVICE_DISCOVERY" – 此事件操作應用於為特定存取字符傳送第三方雲端內探索的裝置清單。

  • "DEVICE_COMMAND_RESPONSE" – 此事件操作應用於傳送特定裝置事件作為命令執行的結果。

  • 「DEVICE_EVENT」 – 此事件操作應用於任何源自於裝置而非使用者型命令直接結果的事件。這可以做為一般事件類型，主動報告裝置狀態變更或通知。