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:

1. AWS.ActivateUser- Integrasi terkelola untuk AWS IoT Device Management layanan memanggil API ini untuk mengambil pengenal pengguna unik secara global yang terkait dengan token.0 yang disediakan OAuth2. Operasi ini secara opsional dapat digunakan untuk melakukan persyaratan tambahan apa pun untuk proses penautan akun.

2. AWS.DiscoverDevices- Integrasi terkelola untuk layanan AWS IoT Device Management memanggil API ini ke konektor Anda untuk menemukan perangkat pengguna

3. AWS.SendCommand- Integrasi terkelola untuk layanan AWS IoT Device Management memanggil API ini ke konektor Anda untuk mengirim perintah untuk perangkat pengguna

4. AWS.DeactivateUser- Integrasi terkelola untuk layanan AWS IoT Device Management memanggil API ini ke konektor Anda untuk menonaktifkan token akses pengguna untuk menghapus tautan di server otorisasi Anda.

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. Untuk selengkapnya, lihat Memanggil di Referensi AWS Lambda API.

Setiap batas waktu pemanggilan diatur ke dua detik, dan jika pemanggilan gagal, itu akan dicoba ulang lima kali.

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

catatan

Pengembang konektor harus mengimplementasikanactivateUserManager.activateUser(request),deviceDiscoveryManager.listDevices(request),sendCommandManager.sendCommand(request), dan deactivateUser.deactivateUser operasi yang tercantum dalam contoh sebelumnya.

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.

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

Header permintaan default

Bidang header default adalah sebagai berikut.

{
    "header": {
        "auth": {                 
            "token": string,    // end user's Access Token
            "type": ENUM ["OAuth2.0"], 
        }
    }
}

API apa pun yang dihosting oleh konektor harus memproses parameter header berikut:

Header dan bidang default

Bidang	Dibutuhkan/Opsional	Deskripsi
header:auth	Ya	Informasi otorisasi yang diberikan oleh pembuat konektor C2C selama pendaftaran konektor mereka.
header:auth:token	Ya	Token otorisasi pengguna yang dihasilkan oleh penyedia cloud pihak ketiga dan ditautkan keconnectorAssociationID.
header:auth:type	Ya	Jenis otorisasi yang dibutuhkan.

catatan

Semua permintaan ke konektor Anda akan memiliki token akses pengguna akhir yang terpasang. Anda dapat berasumsi bahwa penautan akun antara pengguna akhir dan integrasi terkelola pelanggan telah terjadi.

Meminta muatan

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

Minta bidang payload:

• operationName: Pengoperasian permintaan yang diberikan, sama dengan salah satu nilai berikut:AWS.ActivateUser,AWS.SendCommand,AWS.DiscoverDevices,AWS.DeactivateUser.

• operationVersion: Setiap operasi diberi versi untuk memungkinkan evolusinya dari waktu ke waktu dan memberikan definisi antarmuka yang stabil untuk konektor pihak ketiga. integrasi terkelola melewati bidang versi dalam muatan semua permintaan.

• connectorId: ID konektor di mana permintaan telah dikirim ke.

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. Berikut ini adalah contoh umum dari tanggapan tersebut:

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

Setiap respon operasi harus memiliki header umum berikut:

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

Tabel berikut mencantumkan header respon default:

Header dan bidang respons default

Bidang	Dibutuhkan/Opsional	Komentar
header:responseCode	Ya	ENUM nilai yang menunjukkan status eksekusi permintaan.

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.

Dengan menggunakan SendConnectorEvent API, konektor Anda diharapkan mengirim jenis peristiwa dari daftar di bawah ini ke for AWS.DiscoverDevices dan AWS.SendCommand operasi, serta peristiwa perangkat proaktif (seperti lampu yang dinyalakan dan dimatikan secara manual). Untuk membaca penjelasan rinci tentang jenis acara ini dan kasus penggunaannya, lihatMenerapkan AWS. DiscoverDevices operasi,Menerapkan AWS. SendCommand operasi, danMengirim peristiwa perangkat dengan SendConnectorEvent API.

Misalnya, jika konektor C2C Anda menerima DiscoverDevices permintaan, integrasi terkelola untuk AWS IoT Device Management mengharapkannya merespons secara serempak dengan format respons yang ditentukan di atas. Kemudian, Anda harus memanggil SendConnectorEvent API dengan struktur permintaan yang ditentukan dalamMenerapkan AWS. DiscoverDevices operasi, untuk acara DEVICE_DISCOVERY. Panggilan API aktif dapat dilakukan SendConnectorEvent 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.

catatan

Atau, panggilan SendConnectorEvent API dapat terjadi sebelum respons pemanggilan Lambda konektor C2C jika perlu. Namun, aliran ini bertentangan dengan model asinkron untuk pengembangan perangkat lunak.

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

  • “DEVICE_DISCOVERY" — Operasi acara ini akan digunakan untuk mengirim daftar perangkat yang ditemukan dalam cloud pihak ketiga untuk token akses tertentu.

  • “DEVICE_COMMAND_RESPONSE" - Operasi peristiwa ini akan digunakan untuk mengirim peristiwa perangkat tertentu sebagai hasil dari eksekusi perintah.

  • “DEVICE_EVENT" - Operasi peristiwa ini harus digunakan untuk setiap peristiwa yang berasal dari perangkat yang bukan merupakan hasil langsung dari perintah berbasis pengguna. Ini dapat berfungsi sebagai jenis acara umum untuk secara proaktif melaporkan perubahan atau pemberitahuan status perangkat.