Menerapkan operasi antarmuka konektor C2C

Integrasi Terkelola untuk AWS IoT Device Management mendefinisikan empat operasi yang AWS Lambda harus Anda tangani agar memenuhi syarat sebagai konektor. Konektor C2C Anda harus mengimplementasikan setiap operasi berikut:

Detail Doa

Integrasi Terkelola untuk AWS IoT Device Management selalu memanggil fungsi Lambda dengan muatan string JSON melalui tindakan. AWS Lambda invokeFunction Operasi permintaan harus menyertakan operationName bidang di setiap muatan permintaan.

Pengaturan Doa:

Contoh Implementasi

Lambda yang Anda terapkan untuk konektor Anda akan mengurai operationName dari payload permintaan dan mengimplementasikan fungsionalitas yang sesuai untuk dipetakan ke cloud pihak ketiga:

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);
    };
}

Contoh Format Permintaan

Contoh berikut merinci permintaan konektor generik dari Integrasi Terkelola, di mana bidang umum untuk setiap antarmuka yang diperlukan hadir. Dari contoh, Anda dapat melihat ada header permintaan dan payload permintaan. Header permintaan umum di setiap antarmuka operasi.

Contoh OAuth 2.0:

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

Contoh Otorisasi Umum:

{
        "header": {
                "auth": { 
                        "secretsManager": {
                                "arn": "string",
                                "versionId": "string"
                        },
                        "type": "GeneralAuthorization"
                }
        },
        "payload":{
                "operationName": "AWS.SendCommand",
                "operationVersion": "1.0",
                "connectorId": "exampleId",
        …
        }
}

Header permintaan default

Bidang header default bervariasi tergantung pada jenis otorisasi. Konektor Anda harus menangani header permintaan OAuth 2.0 dan General Authorization.

Header default OAuth 2.0:

{
    "header": {
        "auth": {
            "token": string,    // End user's Access Token
            "type": "OAuth2.0"
        }
    }
}

Header default Otorisasi Umum:

{
    "header": {
        "auth": {
            "secretsManager": {
                "arn": "string",
                "versionId": "string"
            },
            "type": "GeneralAuthorization"
        }
    }
}

Minta Muatan

Selain header umum, setiap permintaan akan memiliki payload. Meskipun payload ini akan memiliki bidang unik untuk setiap jenis operasi, setiap payload memiliki satu set bidang default yang akan selalu ada.

Header Respons Default

Setiap operasi akan merespons dengan integrasi terkelola ACK untuk AWS IoT Device Management yang mengonfirmasi konektor C2C Anda telah menerima permintaan dan mulai memprosesnya.

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

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

Bidang Header Respons

Sepanjang berbagai Antarmuka Konektor dan skema API yang dijelaskan dalam dokumen ini ada bidang responseMessage atauMessage. Ini adalah bidang opsional yang digunakan untuk konektor C2C Lambda untuk merespons dengan konteks apa pun mengenai permintaan dan pelaksanaannya. Lebih disukai, kesalahan apa pun yang menghasilkan kode status selain 200 harus menyertakan nilai pesan yang menjelaskan kesalahan.

Menanggapi permintaan operasi konektor C2C dengan API SendConnectorEvent

Integrasi Terkelola untuk AWS IoT Device Management mengharapkan konektor Anda berperilaku asinkron untuk setiap operasi dan operasi. AWS.SendCommand AWS.DiscoverDevices Ini berarti bahwa respon awal untuk operasi ini, cukup “mengakui” bahwa konektor C2C Anda telah menerima permintaan.

Menggunakan SendConnectorEvent API, konektor Anda diharapkan untuk mengirim jenis peristiwa dari daftar di bawah ini untuk AWS.DiscoverDevices dan AWS.SendCommand operasi, serta peristiwa perangkat proaktif (seperti lampu yang dinyalakan dan dimatikan secara manual).

Contoh Alur Kerja

Jika konektor C2C Anda menerima DiscoverDevices permintaan, Integrasi Terkelola untuk AWS IoT Device Management mengharapkannya:

Panggilan SendConnectorEvent API dapat dilakukan di mana saja Anda memiliki akses ke kredenal Lambda konektor C2C Anda. Akun AWS Alur penemuan perangkat tidak berhasil sampai integrasi terkelola untuk AWS IoT Device Management menerima acara ini.

SendConnectorEvent API

Konektor Anda memanggil integrasi terkelola ini untuk AWS IoT Device Management API untuk mengirim peristiwa perangkat. Hanya 3 jenis acara yang diterima: