Greengrass discovery RESTful API - AWS IoT Greengrass

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Greengrass discovery RESTful API

AWS IoT Greengrass menyediakan operasi API Discover yang dapat digunakan oleh perangkat klien untuk mengidentifikasi perangkat inti Greengrass di mana mereka dapat terhubung. Perangkat klien menggunakan operasi bidang data ini untuk mengambil informasi yang diperlukan untuk terhubung ke perangkat inti Greengrass di mana Anda mengasosiasikannya dengan operasi API BatchAssociateClientDeviceWithCoreDevice. Ketika perangkat klien online, perangkat dapat terhubung ke layanan cloud AWS IoT Greengrass dan menggunakan API penemuan untuk menemukan:

  • Alamat IP dan port untuk setiap perangkat inti Greengrass yang terkait.

  • Sertifikat CA perangkat inti, yang dapat digunakan oleh perangkat klien untuk mengautentikasi perangkat inti Greengrass.

catatan

Perangkat klien juga dapat menggunakan klien penemuan di AWS IoT Device SDK untuk menemukan informasi konektivitas untuk perangkat inti Greengrass. Klien penemuan menggunakan API penemuan. Untuk informasi selengkapnya, lihat yang berikut:

Untuk menggunakan operasi API ini, kirim permintaan HTTP untuk API penemuan tersebut pada titik akhir bidang data Greengrass. Titik akhir API ini memiliki format berikut.

https://greengrass-ats.iot.region.amazonaws.com:port/greengrass/discover/thing/thing-name

Untuk daftar yang didukung Wilayah AWS dan titik akhir untuk API penemuan AWS IoT Greengrass, lihat titik akhir dan kuota AWS IoT Greengrass V2 di Referensi Umum AWS. Operasi API ini tersedia hanya pada titik akhir bidang data Greengrass. Titik akhir bidang kontrol yang Anda gunakan untuk mengelola komponen dan deployment berbeda dari titik akhir bidang data.

catatan

API penemuan adalah sama untuk AWS IoT Greengrass V1 dan AWS IoT Greengrass V2. Jika Anda memiliki perangkat klien yang terhubung keAWS IoT Greengrass V1inti, Anda dapat menghubungkan mereka untukAWS IoT Greengrass V2perangkat inti tanpa mengubah kode pada perangkat klien. Untuk informasi selengkapnya, lihat Greengrass Discovery RESTful API di Panduan Developer AWS IoT Greengrass Version 1.

Autentikasi dan otorisasi penemuan

Untuk menggunakan API penemuan untuk mengambil informasi konektivitas, perangkat klien harus menggunakan autentikasi bersama TLS dengan sertifikat klien X.509 untuk mengautentikasi. Untuk informasi lebih lanjut, lihat Sertifikat klien X.509 di Panduan Developer AWS IoT Core.

Perangkat klien juga harus memiliki izin untuk melakukan tindakan greengrass:Discover. Contoh kebijakan AWS IoT berikut memungkinkan objek AWS IoT bernama MyClientDevice1untuk melakukan Discover untuk dirinya sendiri.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "greengrass:Discover", "Resource": [ "arn:aws:iot:us-west-2:123456789012:thing/MyClientDevice1" ] } ] }
penting

Variabel kebijakan objek (iot:Connection.Thing.*) tidak didukung di kebijakan AWS IoT untuk perangkat inti atau operasi bidang data Greengrass. Sebaliknya, Anda dapat menggunakan wildcard yang cocok dengan beberapa perangkat yang memiliki nama yang sama. Misalnya, Anda dapat menentukan MyGreengrassDevice* agar cocok dengan MyGreengrassDevice1, MyGreengrassDevice2, dan sebagainya.

Untuk informasi selengkapnya, lihat kebijakan AWS IoT Core di Panduan Developer AWS IoT Core.

Permintaan

Permintaan berisi header HTTP standar dan dikirim ke titik akhir penemuan Greengrass, seperti yang ditunjukkan dalam contoh berikut.

Nomor port tergantung pada apakah perangkat inti dikonfigurasi untuk mengirim lalu lintas HTTPS melalui port 8443 atau port 443. Untuk informasi selengkapnya, lihat Hubungkan pada port 443 atau melalui proksi jaringan.

catatan

Contoh ini menggunakan endpoint Amazon Trust Services (ATS), yang bekerja dengan sertifikat CA akar ATS yang disarankan. Titik akhir harus sesuai dengan jenis sertifikat CA akar.

Port 8443
HTTP GET https://greengrass-ats.iot.region.amazonaws.com:8443/greengrass/discover/thing/thing-name
Port 443
HTTP GET https://greengrass-ats.iot.region.amazonaws.com:443/greengrass/discover/thing/thing-name
catatan

Klien yang terhubung pada port 443 harus menerapkan ekstensi TLS Application Layer Protocol Negotiation (ALPN) dan melewati x-amzn-http-ca sebagai ProtocolName di ProtocolNameList. Untuk informasi selengkapnya, lihat Protokol dalam Panduan Developer AWS IoT.

Response

Setelah sukses, header respon termasuk HTTP 200 kode status dan tubuh respon berisi dokumen respon menemukan.

catatan

Karena AWS IoT Greengrass V2 menggunakan API penemuan yang sama seperti AWS IoT Greengrass V1, responnya akan mengatur informasi sesuai dengan konsep AWS IoT Greengrass V1, seperti grup Greengrass. Tanggapan berisi daftar grup Greengrass. Di AWS IoT Greengrass V2, setiap perangkat inti berada dalam grupnya sendiri, di mana grup hanya berisi perangkat inti dan informasi konektivitas.

Contoh dokumen respon temuan

Dokumen berikut menunjukkan respon untuk perangkat klien yang terkait dengan satu perangkat inti Greengrass. Perangkat inti memiliki satu titik akhir dan satu sertifikat CA.

{ "GGGroups": [ { "GGGroupId": "greengrassV2-coreDevice-core-device-01-thing-name", "Cores": [ { "thingArn": "core-device-01-thing-arn", "Connectivity": [ { "id": "core-device-01-connection-id", "hostAddress": "core-device-01-address", "portNumber": core-device-01-port, "metadata": "core-device-01-description" } ] } ], "CAs": [ "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----" ] } ] }

Dokumen berikut menunjukkan respons untuk perangkat klien yang terkait dengan dua perangkat inti. Perangkat inti memiliki beberapa titik akhir dan beberapa sertifikat CA grup.

{ "GGGroups": [ { "GGGroupId": "greengrassV2-coreDevice-core-device-01-thing-name", "Cores": [ { "thingArn": "core-device-01-thing-arn", "Connectivity": [ { "id": "core-device-01-connection-id", "hostAddress": "core-device-01-address", "portNumber": core-device-01-port, "metadata": "core-device-01-connection-1-description" }, { "id": "core-device-01-connection-id-2", "hostAddress": "core-device-01-address-2", "portNumber": core-device-01-port-2, "metadata": "core-device-01-connection-2-description" } ] } ], "CAs": [ "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----" ] }, { "GGGroupId": "greengrassV2-coreDevice-core-device-02-thing-name", "Cores": [ { "thingArn":"core-device-02-thing-arn", "Connectivity" : [ { "id": "core-device-02-connection-id", "hostAddress": "core-device-02-address", "portNumber": core-device-02-port, "metadata": "core-device-02-connection-1-description" } ] } ], "CAs": [ "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----" ] } ] }

Uji API penemuan dengan cURL

Jika Anda memiliki cURL yang diinstal, Anda dapat menguji API penemuan. Contoh berikut menentukan sertifikat perangkat klien untuk mengautentikasi permintaan ke titik akhir penemuan API Greengrass.

curl -i \ --cert 1a23bc4d56.cert.pem \ --key 1a23bc4d56.private.key \ https://greengrass-ats.iot.us-west-2.amazonaws.com:8443/greengrass/discover/thing/MyClientDevice1
catatan

Argumen -i menentukan header tanggapan HTTP output. Anda dapat menggunakan opsi ini untuk membantu mengidentifikasi kesalahan.

Jika permintaan berhasil, perintah ini menghasilkan tanggapan yang serupa dengan contoh berikut.

{ "GGGroups": [ { "GGGroupId": "greengrassV2-coreDevice-MyGreengrassCore", "Cores": [ { "thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore", "Connectivity": [ { "Id": "AUTOIP_192.168.1.4_1", "HostAddress": "192.168.1.5", "PortNumber": 8883, "Metadata": "" } ] } ], "CAs": [ "-----BEGIN CERTIFICATE-----\ncert-contents\n-----END CERTIFICATE-----\n" ] } ] }

Jika aplikasi mengeluarkan kesalahan, lihat Pemecahan masalah penemuan Greengrass.