Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# 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 yang unik secara global. Untuk OAuth 2.0, ini terkait dengan token OAuth 2.0 yang disediakan. Operasi ini secara opsional dapat digunakan untuk melakukan persyaratan tambahan apa pun untuk proses penautan akun.
1. `AWS.DiscoverDevices`- Integrasi Terkelola untuk AWS IoT Device Management layanan memanggil API ini ke konektor Anda untuk menemukan perangkat pengguna
1. `AWS.SendCommand`- Integrasi Terkelola untuk AWS IoT Device Management layanan memanggil API ini ke konektor Anda untuk mengirim perintah untuk perangkat pengguna
1. `AWS.DeactivateUser`- Integrasi Terkelola untuk AWS IoT Device Management layanan memanggil API ini ke konektor Anda untuk menonaktifkan token akses pengguna untuk delink di server otorisasi Anda.
## 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:**
+ Batas **waktu:** 2 detik per doa
+ **Mencoba lagi:** 5 coba lagi pada kegagalan
## 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);
};
}
```
**catatan**
Pengembang konektor harus mengimplementasikan`activateUserManager.activateUser(request)`,`deviceDiscoveryManager.listDevices(request)`,`sendCommandManager.sendCommand(request)`, dan `deactivateUser.deactivateUser` operasi yang tercantum dalam contoh sebelumnya.
## 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"
}
}
}
```
**Parameter Header**
| | | |
| --- |--- |--- |
| Bidang | Required/Optional | Deskripsi |
| `header:auth` | Ya | Informasi otorisasi yang diberikan oleh pembuat konektor C2C selama pendaftaran konektor mereka. |
| `header:auth:token` | Bersyarat | Token otorisasi pengguna yang dihasilkan oleh penyedia cloud pihak ketiga dan ditautkan ke`connectorAssociationID`. Diperlukan untuk OAuth 2.0, tidak ada untuk Otorisasi Umum. |
| `header:auth:secretsManager` | Bersyarat | AWS Secrets Manager ARN dan ID versi yang berisi kredensil otorisasi. Diperlukan untuk Otorisasi Umum, tidak ada untuk OAuth 2.0. |
| `header:auth:type` | Ya | Jenis otorisasi: `OAuth2.0` atau`GeneralAuthorization`. |
**catatan**
Semua permintaan ke konektor Anda akan menyertakan informasi otorisasi. Untuk OAuth 2.0, ini termasuk token akses pengguna akhir. Untuk Otorisasi Umum, ini termasuk AWS Secrets Manager ARN dan ID versi. Anda dapat berasumsi bahwa otorisasi yang sesuai telah ditetapkan.
## 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.
**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 dibuat versi untuk memungkinkan evolusinya dari waktu ke waktu dan memberikan definisi antarmuka yang stabil untuk konektor pihak ketiga. Integrasi Terkelola meneruskan 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.
**Example Contoh Respon Generik**
```
{
"header":{
"responseCode": 200
},
"payload":{
"responseMessage": “Example response!”
}
}
```
**Example Format Header Respons**
```
{
"header": {
"responseCode": Integer
}
}
```
**Header dan bidang respons default**
| | | |
| --- |--- |--- |
| Bidang | Required/Optional | 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` atau`Message`. 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).
Jika konektor C2C Anda menerima `DiscoverDevices` permintaan, Integrasi Terkelola untuk AWS IoT Device Management mengharapkannya:
+ Tanggapi secara serempak dengan format respons yang ditentukan di atas
+ Memanggil `SendConnectorEvent` API dengan acara DEVICE\_DISCOVERY
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.
**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.
Konektor Anda memanggil integrasi terkelola ini untuk AWS IoT Device Management API untuk mengirim peristiwa perangkat. Hanya 3 jenis acara yang diterima:
+ **“DEVICE\_DISCOVERY”** - Digunakan untuk mengirim daftar perangkat yang ditemukan dalam cloud pihak ketiga untuk token akses tertentu
+ **“DEVICE\_COMMAND\_RESPONSE”** - Digunakan untuk mengirim peristiwa perangkat tertentu sebagai hasil dari eksekusi perintah
+ **“DEVICE\_EVENT”** - Digunakan untuk acara apa pun 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