Berinteraksi dengan bayangan lokal - AWS IoT Greengrass

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

Berinteraksi dengan bayangan lokal

Gunakan layanan IPC bayangan untuk berinteraksi dengan bayangan lokal pada perangkat. Perangkat yang Anda pilih untuk berinteraksi dapat berupa perangkat inti atau perangkat klien yang terhubung.

Untuk menggunakan operasi IPC ini, sertakankomponen manajersebagai dependensi dalam komponen kustom Anda. Anda kemudian dapat menggunakan operasi IPC di komponen kustom Anda untuk berinteraksi dengan bayangan lokal di perangkat Anda melalui manajer bayangan. Untuk mengaktifkan komponen kustom untuk bereaksi terhadap perubahan di keadaan bayangan lokal, Anda juga dapat menggunakan layanan IPC publikasi/berlangganan untuk berlangganan bayangan peristiwa. Untuk informasi lebih lanjut tentang cara menggunakan layanan publikasi/berlangganan, lihat Pesan lokal publikasi/berlangganan.

catatan

Untuk mengaktifkan perangkat inti berinteraksi dengan bayangan perangkat klien, Anda juga harus mengonfigurasi dan menerapkan komponen jembatan MQTT. Untuk informasi selengkapnya, lihatAktifkan pengelola bayangan untuk berkomunikasi dengan perangkat klien.

SDK (Versi Minimum)

Tabel berikut menjelaskan versi minimum AWS IoT Device SDK yang harus Anda gunakan untuk berinteraksi dengan bayangan lokal.

Otorisasi

Untuk menggunakan layanan IPC bayangan dalam komponen kustom, Anda harus menentukan kebijakan otorisasi yang memungkinkan komponen Anda untuk berinteraksi dengan bayangan. Untuk informasi tentang cara menentukan kebijakan otorisasi, lihat Otorisasi komponen untuk melakukan operasi IPC.

Kebijakan otorisasi untuk interaksi bayangan memiliki properti berikut.

Pengenal layanan IPC: aws.greengrass.ShadowManager

Operasi Deskripsi Sumber daya

aws.greengrass#GetThingShadow

Memungkinkan komponen untuk mengambil bayangan suatu objek.

Salah satu string berikut:

  • $aws/things/thingName/shadow/, untuk mengizinkan akses ke bayangan perangkat klasik.

  • $aws/things/thingName/shadow/name/shadowName, untuk memungkinkan akses ke bayangan bernama.

  • *untuk mengizinkan akses semua bayangan.

aws.greengrass#UpdateThingShadow

Memungkinkan komponen untuk memperbarui bayangan suatu objek.

Salah satu string berikut:

  • $aws/things/thingName/shadow/, untuk mengizinkan akses ke bayangan perangkat klasik.

  • $aws/things/thingName/shadow/name/shadowName, untuk memungkinkan akses ke bayangan bernama.

  • *untuk mengizinkan akses semua bayangan.

aws.greengrass#DeleteThingShadow

Memungkinkan komponen untuk menghapus bayangan suatu objek.

Salah satu string berikut:

  • $aws/things/thingName/shadow/, untuk mengizinkan akses ke bayangan perangkat klasik

  • $aws/things/thingName/shadow/name/shadowName, untuk mengizinkan akses ke bayangan bernama

  • *, untuk mengizinkan akses semua bayangan.

aws.greengrass#ListNamedShadowsForThing

Memungkinkan komponen untuk mengambil daftar bayangan bernama untuk suatu objek.

Sebuah string nama objek yang memungkinkan akses ke objek untuk mencantumkan bayangannya.

Gunakan*untuk mengizinkan akses semua hal.

Pengenal layanan IPC: aws.greengrass.ipc.pubsub

Operasi Deskripsi Sumber daya

aws.greengrass#SubscribeToTopic

Memungkinkan komponen untuk berlangganan pesan untuk topik yang Anda tentukan.

Salah satu string berikut:

  • shadowTopicPrefix/get/accepted

  • shadowTopicPrefix/get/rejected

  • shadowTopicPrefix/delete/accepted

  • shadowTopicPrefix/delete/rejected

  • shadowTopicPrefix/update/accepted

  • shadowTopicPrefix/update/delta

  • shadowTopicPrefix/update/rejected

Nilai awalan topik shadowTopicPrefix tergantung pada jenis bayangan:

  • Bayangan klasik: $aws/things/thingName/shadow

  • Bayangan bernama: $aws/things/thingName/shadow/name/shadowName

Gunakan * untuk mengizinkan akses semua topik.

MasukInti Greengrassv2.6.0 dan yang lebih baru, Anda dapat berlangganan topik yang berisi wildcard topik MQTT (#dan+). String topik ini mendukung wildcard topik MQTT sebagai karakter literal. Misalnya, jika kebijakan otorisasi komponen memberikan akses ketest/topic/#, komponen dapat berlangganantest/topic/#, tetapi tidak bisa berlangganantest/topic/filter.

Variabel resep dalam kebijakan otorisasi bayangan lokal

Jika Anda menggunakan v2.6.0 atau versi yang lebih baruInti Greengrass, dan Anda mengatur inti Greengrass 'interpolateComponentConfigurationOpsi untuktrue, Anda dapat menggunakan{iot:thingName} variabel resepdalam kebijakan otorisasi. Fitur ini memungkinkan Anda mengonfigurasi kebijakan otorisasi tunggal untuk sekelompok perangkat inti, di mana setiap perangkat inti hanya dapat mengakses bayangannya sendiri. Misalnya, Anda dapat mengizinkan akses komponen ke sumber daya berikut untuk operasi bayangan IPC.

$aws/things/{iot:thingName}/shadow/

Contoh kebijakan otorisasi

Anda dapat mereferensikan contoh kebijakan otorisasi untuk membantu mengonfigurasi kebijakan otorisasi untuk komponen Anda.

contoh Contoh: Izinkan sekelompok perangkat inti untuk berinteraksi dengan bayangan

penting

Contoh ini menggunakan fitur yang tersedia untuk v2.6.0 dan versi kemudian dariKomponen inti Greengrass. Greengrass nucleus v2.6.0 menambahkan dukungan untuk sebagian besarvariabel resep, seperti{iot:thingName}, dalam konfigurasi komponen. Untuk mengaktifkan fitur ini, setel nukleus Greengrass 'interpolateComponentConfigurationOpsi untuktrue. Untuk contoh yang bekerja untuk semua versi inti Greengrass, lihatcontoh kebijakan otorisasi untuk perangkat inti tunggal.

Kebijakan otorisasi contoh berikut memungkinkan komponencom.example.MyShadowInteractionComponentuntuk berinteraksi dengan bayangan perangkat klasik dan bayangan bernamamyNamedShadowuntuk perangkat inti yang menjalankan komponen. Kebijakan ini juga memungkinkan komponen ini untuk menerima pesan pada topik lokal untuk bayangan ini.

JSON
{ "accessControl": { "aws.greengrass.ShadowManager": { "com.example.MyShadowInteractionComponent:shadow:1": { "policyDescription": "Allows access to shadows", "operations": [ "aws.greengrass#GetThingShadow", "aws.greengrass#UpdateThingShadow", "aws.greengrass#DeleteThingShadow" ], "resources": [ "$aws/things/{iot:thingName}/shadow", "$aws/things/{iot:thingName}/shadow/name/myNamedShadow" ] }, "com.example.MyShadowInteractionComponent:shadow:2": { "policyDescription": "Allows access to things with shadows", "operations": [ "aws.greengrass#ListNamedShadowsForThing" ], "resources": [ "{iot:thingName}" ] } }, "aws.greengrass.ipc.pubsub": { "com.example.MyShadowInteractionComponent:pubsub:1": { "policyDescription": "Allows access to shadow pubsub topics", "operations": [ "aws.greengrass#SubscribeToTopic" ], "resources": [ "$aws/things/{iot:thingName}/shadow/get/accepted", "$aws/things/{iot:thingName}/shadow/name/myNamedShadow/get/accepted" ] } } } }
YAML
accessControl: aws.greengrass.ShadowManager: 'com.example.MyShadowInteractionComponent:shadow:1': policyDescription: 'Allows access to shadows' operations: - 'aws.greengrass#GetThingShadow' - 'aws.greengrass#UpdateThingShadow' - 'aws.greengrass#DeleteThingShadow' resources: - $aws/things/{iot:thingName}/shadow - $aws/things/{iot:thingName}/shadow/name/myNamedShadow 'com.example.MyShadowInteractionComponent:shadow:2': policyDescription: 'Allows access to things with shadows' operations: - 'aws.greengrass#ListNamedShadowsForThing' resources: - {iot:thingName} aws.greengrass.ipc.pubsub: 'com.example.MyShadowInteractionComponent:pubsub:1': policyDescription: 'Allows access to shadow pubsub topics' operations: - 'aws.greengrass#SubscribeToTopic' resources: - $aws/things/{iot:thingName}/shadow/get/accepted - $aws/things/{iot:thingName}/shadow/name/myNamedShadow/get/accepted

contoh Contoh: Izinkan sekelompok perangkat inti untuk berinteraksi dengan bayangan perangkat klien

penting

Fitur ini membutuhkanInti Greengrassv2.6.0 atau lebih baru,Manajer bayanganv2.2.0 atau lebih baru, danJembatan MQTTv2.2.0 atau lebih baru. Anda harus mengkonfigurasi jembatan MQTTmemungkinkan manajer bayangan untuk berkomunikasi dengan perangkat klien.

Kebijakan otorisasi contoh berikut memungkinkan komponencom.example.MyShadowInteractionComponentuntuk berinteraksi dengan semua bayangan perangkat untuk perangkat klien yang namanya dimulaiMyClientDevice.

catatan

Untuk mengaktifkan perangkat inti berinteraksi dengan bayangan perangkat klien, Anda juga harus mengonfigurasi dan menerapkan komponen jembatan MQTT. Untuk informasi selengkapnya, lihatAktifkan pengelola bayangan untuk berkomunikasi dengan perangkat klien.

JSON
{ "accessControl": { "aws.greengrass.ShadowManager": { "com.example.MyShadowInteractionComponent:shadow:1": { "policyDescription": "Allows access to shadows", "operations": [ "aws.greengrass#GetThingShadow", "aws.greengrass#UpdateThingShadow", "aws.greengrass#DeleteThingShadow" ], "resources": [ "$aws/things/MyClientDevice*/shadow", "$aws/things/MyClientDevice*/shadow/name/*" ] }, "com.example.MyShadowInteractionComponent:shadow:2": { "policyDescription": "Allows access to things with shadows", "operations": [ "aws.greengrass#ListNamedShadowsForThing" ], "resources": [ "MyClientDevice*" ] } } } }
YAML
accessControl: aws.greengrass.ShadowManager: 'com.example.MyShadowInteractionComponent:shadow:1': policyDescription: 'Allows access to shadows' operations: - 'aws.greengrass#GetThingShadow' - 'aws.greengrass#UpdateThingShadow' - 'aws.greengrass#DeleteThingShadow' resources: - $aws/things/MyClientDevice*/shadow - $aws/things/MyClientDevice*/shadow/name/* 'com.example.MyShadowInteractionComponent:shadow:2': policyDescription: 'Allows access to things with shadows' operations: - 'aws.greengrass#ListNamedShadowsForThing' resources: - MyClientDevice*

contoh Contoh: Memungkinkan perangkat inti tunggal untuk berinteraksi dengan bayangan lokal

Kebijakan otorisasi contoh berikut memungkinkan komponen com.example.MyShadowInteractionComponent untuk berinteraksi dengan bayangan perangkat klasik dan bayangan bernama myNamedShadow untuk perangkat MyThingName. Kebijakan ini juga memungkinkan komponen ini untuk menerima pesan pada topik lokal untuk bayangan ini.

JSON
{ "accessControl": { "aws.greengrass.ShadowManager": { "com.example.MyShadowInteractionComponent:shadow:1": { "policyDescription": "Allows access to shadows", "operations": [ "aws.greengrass#GetThingShadow", "aws.greengrass#UpdateThingShadow", "aws.greengrass#DeleteThingShadow" ], "resources": [ "$aws/things/MyThingName/shadow", "$aws/things/MyThingName/shadow/name/myNamedShadow" ] }, "com.example.MyShadowInteractionComponent:shadow:2": { "policyDescription": "Allows access to things with shadows", "operations": [ "aws.greengrass#ListNamedShadowsForThing" ], "resources": [ "MyThingName" ] } }, "aws.greengrass.ipc.pubsub": { "com.example.MyShadowInteractionComponent:pubsub:1": { "policyDescription": "Allows access to shadow pubsub topics", "operations": [ "aws.greengrass#SubscribeToTopic" ], "resources": [ "$aws/things/MyThingName/shadow/get/accepted", "$aws/things/MyThingName/shadow/name/myNamedShadow/get/accepted" ] } } } }
YAML
accessControl: aws.greengrass.ShadowManager: 'com.example.MyShadowInteractionComponent:shadow:1': policyDescription: 'Allows access to shadows' operations: - 'aws.greengrass#GetThingShadow' - 'aws.greengrass#UpdateThingShadow' - 'aws.greengrass#DeleteThingShadow' resources: - $aws/things/MyThingName/shadow - $aws/things/MyThingName/shadow/name/myNamedShadow 'com.example.MyShadowInteractionComponent:shadow:2': policyDescription: 'Allows access to things with shadows' operations: - 'aws.greengrass#ListNamedShadowsForThing' resources: - MyThingName aws.greengrass.ipc.pubsub: 'com.example.MyShadowInteractionComponent:pubsub:1': policyDescription: 'Allows access to shadow pubsub topics' operations: - 'aws.greengrass#SubscribeToTopic' resources: - $aws/things/MyThingName/shadow/get/accepted - $aws/things/MyThingName/shadow/name/myNamedShadow/get/accepted

contoh Contoh: Izinkan sekelompok perangkat inti bereaksi terhadap perubahan keadaan bayangan

penting

Contoh ini menggunakan fitur yang tersedia untuk v2.6.0 dan versi kemudian dariKomponen inti Greengrass. Greengrass nucleus v2.6.0 menambahkan dukungan untuk sebagian besarvariabel resep, seperti{iot:thingName}, dalam konfigurasi komponen. Untuk mengaktifkan fitur ini, setel nukleus Greengrass 'interpolateComponentConfigurationOpsi untuktrue. Untuk contoh yang bekerja untuk semua versi inti Greengrass, lihatcontoh kebijakan otorisasi untuk perangkat inti tunggal.

Contoh kebijakan kontrol akses berikut memungkinkan kustomcom.example.MyShadowReactiveComponentuntuk menerima pesan di/update/deltatopik untuk bayangan perangkat klasik dan bayangan bernamamyNamedShadowpada setiap perangkat inti yang menjalankan komponen.

JSON
{ "accessControl": { "aws.greengrass.ipc.pubsub": { "com.example.MyShadowReactiveComponent:pubsub:1": { "policyDescription": "Allows access to shadow pubsub topics", "operations": [ "aws.greengrass#SubscribeToTopic" ], "resources": [ "$aws/things/{iot:thingName}/shadow/update/delta", "$aws/things/{iot:thingName}/shadow/name/myNamedShadow/update/delta" ] } } } }
YAML
accessControl: aws.greengrass.ipc.pubsub: "com.example.MyShadowReactiveComponent:pubsub:1": policyDescription: Allows access to shadow pubsub topics operations: - 'aws.greengrass#SubscribeToTopic' resources: - $aws/things/{iot:thingName}/shadow/update/delta - $aws/things/{iot:thingName}/shadow/name/myNamedShadow/update/delta

contoh Contoh: Izinkan perangkat inti tunggal untuk bereaksi terhadap perubahan keadaan bayangan

Contoh kebijakan kontrol akses berikut memungkinkan kustomcom.example.MyShadowReactiveComponentuntuk menerima pesan di/update/deltatopik untuk bayangan perangkat klasik dan bayangan bernamamyNamedShadowuntuk perangkatMyThingName.

JSON
{ "accessControl": { "aws.greengrass.ipc.pubsub": { "com.example.MyShadowReactiveComponent:pubsub:1": { "policyDescription": "Allows access to shadow pubsub topics", "operations": [ "aws.greengrass#SubscribeToTopic" ], "resources": [ "$aws/things/MyThingName/shadow/update/delta", "$aws/things/MyThingName/shadow/name/myNamedShadow/update/delta" ] } } } }
YAML
accessControl: aws.greengrass.ipc.pubsub: "com.example.MyShadowReactiveComponent:pubsub:1": policyDescription: Allows access to shadow pubsub topics operations: - 'aws.greengrass#SubscribeToTopic' resources: - $aws/things/MyThingName/shadow/update/delta - $aws/things/MyThingName/shadow/name/myNamedShadow/update/delta

GetThingShadow

Dapatkan bayangan untuk objek tertentu.

Permintaan

Permintaan operasi ini memiliki parameter berikut:

thingName(Python:thing_name)

Nama sesuatu .

Tipe: string

shadowName(Python:shadow_name)

Nama bayangan. Untuk menentukan bayangan klasik benda itu, atur parameter ini ke string kosong ("").

Awas

KlasterAWS IoT Greengrasslayanan menggunakanAWSManagedGreengrassV2Deploymentbernama shadow untuk mengelola penyebaran yang menargetkan perangkat inti individual. Bayangan bernama ini dicadangkan untuk digunakan olehAWS IoT Greengrasslayanan. Jangan perbarui atau hapus bayangan bernama ini.

Tipe: string

Response

Tanggapan operasi ini memiliki informasi berikut:

payload

Dokumen keadaan respons sebagai gumpalan.

Jenis: object yang berisi informasi berikut:

state

Informasi keadaan.

Objek ini berisi informasi berikut.

desired

Properti keadaan dan nilai-nilai yang diminta untuk diperbarui di perangkat.

Jenis: map pasangan nilai kunci

reported

Properti keadaan dan nilai yang dilaporkan oleh perangkat.

Jenis: map pasangan nilai kunci

delta

Perbedaan antara properti dan nilai yang diinginkan dan yang dilaporkan. Properti ini hadir hanya jika keadaan desired dan reported berbeda.

Jenis: map pasangan nilai kunci

metadata

Cap waktu untuk setiap atribut dalam bagian desired dan reported agar Anda dapat menentukan kapan keadaan diperbarui.

Tipe: string

timestamp

Tanggal dan jangka waktu respons dihasilkan.

Tipe: integer

clientToken(Python:clientToken)

Token yang digunakan untuk mencocokkan permintaan tersebut dan respons yang sesuai.

Tipe: string

version

Versi dokumen bayangan lokal.

Tipe: integer

Kesalahan

Operasi ini dapat mengembalikan kesalahan berikut.

InvalidArgumentsError

Layanan bayangan lokal tidak dapat memvalidasi parameter permintaan. Hal ini dapat terjadi jika permintaan berisi JSON yang salah bentuk atau karakter yang tidak didukung.

ResourceNotFoundError

Dokumen bayangan lokal yang diminta tidak dapat ditemukan.

ServiceError

Terjadi kesalahan layanan internal, atau jumlah permintaan ke layanan IPC melebihi batas yang ditentukan dalam parameter konfigurasi maxLocalRequestsPerSecondPerThing dan maxTotalLocalRequestsRate di komponen manajer bayangan.

UnauthorizedError

Kebijakan otorisasi komponen tidak mencakup izin yang diperlukan untuk operasi ini.

Contoh

Contoh-contoh berikut ini menunjukkan cara memanggil operasi ini dalam kode komponen kustom.

Java (IPC client V1)

contoh Contoh: Dapatkan bayangan

catatan

Contoh ini menggunakanIPCUtilskelas untuk membuat koneksi keAWS IoT GreengrassLayanan IPC inti. Untuk informasi selengkapnya, lihat Hubungkan ke layanan IPC inti AWS IoT Greengrass.

package com.aws.greengrass.docs.samples.ipc; import com.aws.greengrass.docs.samples.ipc.util.IPCUtils; import software.amazon.awssdk.aws.greengrass.GetThingShadowResponseHandler; import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient; import software.amazon.awssdk.aws.greengrass.model.GetThingShadowRequest; import software.amazon.awssdk.aws.greengrass.model.GetThingShadowResponse; import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError; import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError; import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection; import java.nio.charset.StandardCharsets; import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; public class GetThingShadow { public static final int TIMEOUT_SECONDS = 10; public static void main(String[] args) { // Use the current core device's name if thing name isn't set. String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0]; String shadowName = args[1]; try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) { GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection); GetThingShadowResponseHandler responseHandler = GetThingShadow.getThingShadow(ipcClient, thingName, shadowName); CompletableFuture<GetThingShadowResponse> futureResponse = responseHandler.getResponse(); try { GetThingShadowResponse response = futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS); String shadowPayload = new String(response.getPayload(), StandardCharsets.UTF_8); System.out.printf("Successfully got shadow %s/%s: %s%n", thingName, shadowName, shadowPayload); } catch (TimeoutException e) { System.err.printf("Timeout occurred while getting shadow: %s/%s%n", thingName, shadowName); } catch (ExecutionException e) { if (e.getCause() instanceof UnauthorizedError) { System.err.printf("Unauthorized error while getting shadow: %s/%s%n", thingName, shadowName); } else if (e.getCause() instanceof ResourceNotFoundError) { System.err.printf("Unable to find shadow to get: %s/%s%n", thingName, shadowName); } else { throw e; } } } catch (InterruptedException e) { System.out.println("IPC interrupted."); } catch (ExecutionException e) { System.err.println("Exception occurred when using IPC."); e.printStackTrace(); System.exit(1); } } public static GetThingShadowResponseHandler getThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String shadowName) { GetThingShadowRequest getThingShadowRequest = new GetThingShadowRequest(); getThingShadowRequest.setThingName(thingName); getThingShadowRequest.setShadowName(shadowName); return greengrassCoreIPCClient.getThingShadow(getThingShadowRequest, Optional.empty()); } }
Python (IPC client V1)

contoh Contoh: Dapatkan bayangan

import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from awsiot.greengrasscoreipc.model import GetThingShadowRequest TIMEOUT = 10 def sample_get_thing_shadow_request(thingName, shadowName): try: # set up IPC client to connect to the IPC server ipc_client = awsiot.greengrasscoreipc.connect() # create the GetThingShadow request get_thing_shadow_request = GetThingShadowRequest() get_thing_shadow_request.thing_name = thingName get_thing_shadow_request.shadow_name = shadowName # retrieve the GetThingShadow response after sending the request to the IPC server op = ipc_client.new_get_thing_shadow() op.activate(get_thing_shadow_request) fut = op.get_response() result = fut.result(TIMEOUT) return result.payload except InvalidArgumentsError as e: # add error handling ... # except ResourceNotFoundError | UnauthorizedError | ServiceError

UpdateThingShadow

Perbarui bayangan untuk objek tertentu.

Permintaan

Permintaan operasi ini memiliki parameter berikut:

thingName(Python:thing_name)

Nama sesuatu .

Tipe: string

shadowName(Python:shadow_name)

Nama bayangan. Untuk menentukan bayangan klasik benda itu, atur parameter ini ke string kosong ("").

Awas

KlasterAWS IoT Greengrasslayanan menggunakanAWSManagedGreengrassV2Deploymentbernama shadow untuk mengelola penyebaran yang menargetkan perangkat inti individual. Bayangan bernama ini dicadangkan untuk digunakan olehAWS IoT Greengrasslayanan. Jangan perbarui atau hapus bayangan bernama ini.

Tipe: string

payload

Dokumen keadaan permintaan sebagai gumpalan.

Jenis: object yang berisi informasi berikut:

state

Informasi keadaan yang akan diperbarui. Operasi IPC ini hanya mempengaruhi kolom tertentu.

Objek ini berisi informasi berikut. Biasanya, Anda akan menggunakan properti desired atau properti reported, tetapi tidak keduanya dalam permintaan yang sama.

desired

Properti keadaan dan nilai-nilai yang diminta untuk diperbarui di perangkat.

Jenis: map pasangan nilai kunci

reported

Properti keadaan dan nilai yang dilaporkan oleh perangkat.

Jenis: map pasangan nilai kunci

clientToken(Python:client_token)

(Opsional) Token yang digunakan untuk mencocokkan permintaan dan respons yang sesuai dengan token klien.

Tipe: string

version

(Opsional) Versi dokumen bayangan lokal yang akan diperbarui. Layanan bayangan akan memproses pembaruan hanya jika versi tertentu cocok dengan versi terbaru yang dimilikinya.

Tipe: integer

Response

Tanggapan operasi ini memiliki informasi berikut:

payload

Dokumen keadaan respons sebagai gumpalan.

Jenis: object yang berisi informasi berikut:

state

Informasi keadaan.

Objek ini berisi informasi berikut.

desired

Properti keadaan dan nilai-nilai yang diminta untuk diperbarui di perangkat.

Jenis: map pasangan nilai kunci

reported

Properti keadaan dan nilai yang dilaporkan oleh perangkat.

Jenis: map pasangan nilai kunci

delta

Properti keadaan dan nilai yang dilaporkan oleh perangkat.

Jenis: map pasangan nilai kunci

metadata

Cap waktu untuk setiap atribut dalam bagian desired dan reported agar Anda dapat menentukan kapan keadaan diperbarui.

Tipe: string

timestamp

Tanggal dan jangka waktu respons dihasilkan.

Tipe: integer

clientToken(Python:client_token)

Token yang digunakan untuk mencocokkan permintaan dan respons yang sesuai.

Tipe: string

version

Versi dokumen bayangan lokal setelah pembaruan selesai.

Tipe: integer

Kesalahan

Operasi ini dapat mengembalikan kesalahan berikut.

ConflictError

Layanan bayangan lokal mengalami konflik versi selama operasi pembaruan. Hal ini terjadi ketika versi dalam permintaan muatan tidak cocok dengan versi dalam dokumen bayangan lokal terbaru yang tersedia.

InvalidArgumentsError

Layanan bayangan lokal tidak dapat memvalidasi parameter permintaan. Hal ini dapat terjadi jika permintaan berisi JSON yang salah bentuk atau karakter yang tidak didukung.

payload yang valid memiliki properti berikut:

  • Simpul state ada, dan merupakan objek yang berisi informasi keadaan desired atau reported.

  • Node desired dan reported merupakan objek atau tidak sah. Setidaknya salah satu dari objek-objek ini harus berisi informasi keadaan yang valid.

  • Kedalaman objek desired dan reported tidak dapat melebihi delapan node.

  • Panjang nilai clientToken tidak dapat melebihi 64 karakter.

  • Nilai version harus 1 atau lebih tinggi.

ServiceError

Terjadi kesalahan layanan internal, atau jumlah permintaan ke layanan IPC melebihi batas yang ditentukan dalam parameter konfigurasi maxLocalRequestsPerSecondPerThing dan maxTotalLocalRequestsRate di komponen manajer bayangan.

UnauthorizedError

Kebijakan otorisasi komponen tidak mencakup izin yang diperlukan untuk operasi ini.

Contoh

Contoh-contoh berikut ini menunjukkan cara memanggil operasi ini dalam kode komponen kustom.

Java (IPC client V1)

contoh Contoh: Memperbarui bayangan hal

catatan

Contoh ini menggunakanIPCUtilskelas untuk membuat koneksi keAWS IoT GreengrassLayanan IPC inti. Untuk informasi selengkapnya, lihat Hubungkan ke layanan IPC inti AWS IoT Greengrass.

package com.aws.greengrass.docs.samples.ipc; import com.aws.greengrass.docs.samples.ipc.util.IPCUtils; import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient; import software.amazon.awssdk.aws.greengrass.UpdateThingShadowResponseHandler; import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError; import software.amazon.awssdk.aws.greengrass.model.UpdateThingShadowRequest; import software.amazon.awssdk.aws.greengrass.model.UpdateThingShadowResponse; import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection; import java.nio.charset.StandardCharsets; import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; public class UpdateThingShadow { public static final int TIMEOUT_SECONDS = 10; public static void main(String[] args) { // Use the current core device's name if thing name isn't set. String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0]; String shadowName = args[1]; byte[] shadowPayload = args[2].getBytes(StandardCharsets.UTF_8); try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) { GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection); UpdateThingShadowResponseHandler responseHandler = UpdateThingShadow.updateThingShadow(ipcClient, thingName, shadowName, shadowPayload); CompletableFuture<UpdateThingShadowResponse> futureResponse = responseHandler.getResponse(); try { futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS); System.out.printf("Successfully updated shadow: %s/%s%n", thingName, shadowName); } catch (TimeoutException e) { System.err.printf("Timeout occurred while updating shadow: %s/%s%n", thingName, shadowName); } catch (ExecutionException e) { if (e.getCause() instanceof UnauthorizedError) { System.err.printf("Unauthorized error while updating shadow: %s/%s%n", thingName, shadowName); } else { throw e; } } } catch (InterruptedException e) { System.out.println("IPC interrupted."); } catch (ExecutionException e) { System.err.println("Exception occurred when using IPC."); e.printStackTrace(); System.exit(1); } } public static UpdateThingShadowResponseHandler updateThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String shadowName, byte[] shadowPayload) { UpdateThingShadowRequest updateThingShadowRequest = new UpdateThingShadowRequest(); updateThingShadowRequest.setThingName(thingName); updateThingShadowRequest.setShadowName(shadowName); updateThingShadowRequest.setPayload(shadowPayload); return greengrassCoreIPCClient.updateThingShadow(updateThingShadowRequest, Optional.empty()); } }
Python (IPC client V1)

contoh Contoh: Memperbarui bayangan hal

import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from awsiot.greengrasscoreipc.model import UpdateThingShadowRequest TIMEOUT = 10 def sample_update_thing_shadow_request(thingName, shadowName, payload): try: # set up IPC client to connect to the IPC server ipc_client = awsiot.greengrasscoreipc.connect() # create the UpdateThingShadow request update_thing_shadow_request = UpdateThingShadowRequest() update_thing_shadow_request.thing_name = thingName update_thing_shadow_request.shadow_name = shadowName update_thing_shadow_request.payload = payload # retrieve the UpdateThingShadow response after sending the request to the IPC server op = ipc_client.new_update_thing_shadow() op.activate(update_thing_shadow_request) fut = op.get_response() result = fut.result(TIMEOUT) return result.payload except InvalidArgumentsError as e: # add error handling ... # except ConflictError | UnauthorizedError | ServiceError

DeleteThingShadow

Menghapus bayangan untuk objek yang ditentukan.

Dimulai pada shadow manager v2.0.4, menghapus bayangan menambah nomor versi. Misalnya, ketika Anda menghapus bayanganMyThingShadowpada versi 1, versi bayangan yang dihapus adalah 2. Jika Anda kemudian menciptakan bayangan dengan namaMyThingShadow, versi untuk bayangan itu adalah 3.

Permintaan

Permintaan operasi ini memiliki parameter berikut:

thingName(Python:thing_name)

Nama sesuatu .

Tipe: string

shadowName(Python:shadow_name)

Nama bayangan. Untuk menentukan bayangan klasik benda itu, atur parameter ini ke string kosong ("").

Awas

KlasterAWS IoT Greengrasslayanan menggunakanAWSManagedGreengrassV2Deploymentbernama shadow untuk mengelola penyebaran yang menargetkan perangkat inti individual. Bayangan bernama ini dicadangkan untuk digunakan olehAWS IoT Greengrasslayanan. Jangan perbarui atau hapus bayangan bernama ini.

Tipe: string

Response

Tanggapan operasi ini memiliki informasi berikut:

payload

Dokumen keadaan tanpa respons.

Kesalahan

Operasi ini dapat mengembalikan kesalahan berikut.

InvalidArgumentsError

Layanan bayangan lokal tidak dapat memvalidasi parameter permintaan. Hal ini dapat terjadi jika permintaan berisi JSON yang salah bentuk atau karakter yang tidak didukung.

ResourceNotFoundError

Dokumen bayangan lokal yang diminta tidak dapat ditemukan.

ServiceError

Terjadi kesalahan layanan internal, atau jumlah permintaan ke layanan IPC melebihi batas yang ditentukan dalam parameter konfigurasi maxLocalRequestsPerSecondPerThing dan maxTotalLocalRequestsRate di komponen manajer bayangan.

UnauthorizedError

Kebijakan otorisasi komponen tidak mencakup izin yang diperlukan untuk operasi ini.

Contoh

Contoh-contoh berikut ini menunjukkan cara memanggil operasi ini dalam kode komponen kustom.

Java (IPC client V1)

contoh Contoh: Menghapus sesuatu bayangan

catatan

Contoh ini menggunakanIPCUtilskelas untuk membuat koneksi keAWS IoT GreengrassLayanan IPC inti. Untuk informasi selengkapnya, lihat Hubungkan ke layanan IPC inti AWS IoT Greengrass.

package com.aws.greengrass.docs.samples.ipc; import com.aws.greengrass.docs.samples.ipc.util.IPCUtils; import software.amazon.awssdk.aws.greengrass.DeleteThingShadowResponseHandler; import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient; import software.amazon.awssdk.aws.greengrass.model.DeleteThingShadowRequest; import software.amazon.awssdk.aws.greengrass.model.DeleteThingShadowResponse; import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError; import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError; import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection; import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; public class DeleteThingShadow { public static final int TIMEOUT_SECONDS = 10; public static void main(String[] args) { // Use the current core device's name if thing name isn't set. String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0]; String shadowName = args[1]; try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) { GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection); DeleteThingShadowResponseHandler responseHandler = DeleteThingShadow.deleteThingShadow(ipcClient, thingName, shadowName); CompletableFuture<DeleteThingShadowResponse> futureResponse = responseHandler.getResponse(); try { futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS); System.out.printf("Successfully deleted shadow: %s/%s%n", thingName, shadowName); } catch (TimeoutException e) { System.err.printf("Timeout occurred while deleting shadow: %s/%s%n", thingName, shadowName); } catch (ExecutionException e) { if (e.getCause() instanceof UnauthorizedError) { System.err.printf("Unauthorized error while deleting shadow: %s/%s%n", thingName, shadowName); } else if (e.getCause() instanceof ResourceNotFoundError) { System.err.printf("Unable to find shadow to delete: %s/%s%n", thingName, shadowName); } else { throw e; } } } catch (InterruptedException e) { System.out.println("IPC interrupted."); } catch (ExecutionException e) { System.err.println("Exception occurred when using IPC."); e.printStackTrace(); System.exit(1); } } public static DeleteThingShadowResponseHandler deleteThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String shadowName) { DeleteThingShadowRequest deleteThingShadowRequest = new DeleteThingShadowRequest(); deleteThingShadowRequest.setThingName(thingName); deleteThingShadowRequest.setShadowName(shadowName); return greengrassCoreIPCClient.deleteThingShadow(deleteThingShadowRequest, Optional.empty()); } }
Python (IPC client V1)

contoh Contoh: Menghapus sesuatu bayangan

import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from awsiot.greengrasscoreipc.model import DeleteThingShadowRequest TIMEOUT = 10 def sample_delete_thing_shadow_request(thingName, shadowName): try: # set up IPC client to connect to the IPC server ipc_client = awsiot.greengrasscoreipc.connect() # create the DeleteThingShadow request delete_thing_shadow_request = DeleteThingShadowRequest() delete_thing_shadow_request.thing_name = thingName delete_thing_shadow_request.shadow_name = shadowName # retrieve the DeleteThingShadow response after sending the request to the IPC server op = ipc_client.new_delete_thing_shadow() op.activate(delete_thing_shadow_request) fut = op.get_response() result = fut.result(TIMEOUT) return result.payload except InvalidArgumentsError as e: # add error handling ... # except ResourceNotFoundError | UnauthorizedError | ServiceError

ListNamedShadowsForThing

Daftar bayangan bernama untuk objek yang ditentukan.

Permintaan

Permintaan operasi ini memiliki parameter berikut:

thingName(Python:thing_name)

Nama sesuatu .

Tipe: string

pageSize(Python:page_size)

(Opsional) Jumlah nama bayangan yag akan dikembalikan pada setiap panggilan.

Tipe: integer

Default: 25

Maksimum: 100

nextToken(Python:next_token)

(Opsional) Token untuk mengambil rangkaian hasil berikutnya. Nilai ini dikembalikan pada hasil berhalaman dan digunakan dalam panggilan yang mengembalikan halaman berikutnya.

Tipe: string

Response

Tanggapan operasi ini memiliki informasi berikut:

results

Daftar nama bayangan.

Tipe: array

timestamp

(Opsional) Tanggal dan waktu respons tersebut dihasilkan.

Tipe: integer

nextToken(Python:next_token)

(Opsional) Nilai token yang akan digunakan dalam permintaan berhalaman untuk mengambil halaman berikutnya secara berurutan. Token ini tidak hadir ketika tidak terdapat lagi nama bayangan yang akan dikembalikan.

Tipe: string

catatan

Jika ukuran halaman yang diminta persis sesuai dengan jumlah nama bayangan di respons, maka token ini hadir; Namun, ketika digunakan, token tersebut akan mengembalikan daftar kosong.

Kesalahan

Operasi ini dapat mengembalikan kesalahan berikut.

InvalidArgumentsError

Layanan bayangan lokal tidak dapat memvalidasi parameter permintaan. Hal ini dapat terjadi jika permintaan berisi JSON yang salah bentuk atau karakter yang tidak didukung.

ResourceNotFoundError

Dokumen bayangan lokal yang diminta tidak dapat ditemukan.

ServiceError

Terjadi kesalahan layanan internal, atau jumlah permintaan ke layanan IPC melebihi batas yang ditentukan dalam parameter konfigurasi maxLocalRequestsPerSecondPerThing dan maxTotalLocalRequestsRate di komponen manajer bayangan.

UnauthorizedError

Kebijakan otorisasi komponen tidak mencakup izin yang diperlukan untuk operasi ini.

Contoh

Contoh-contoh berikut ini menunjukkan cara memanggil operasi ini dalam kode komponen kustom.

Java (IPC client V1)

contoh Contoh: Daftar sesuatu yang bernama bayangan

catatan

Contoh ini menggunakanIPCUtilskelas untuk membuat koneksi keAWS IoT GreengrassLayanan IPC inti. Untuk informasi selengkapnya, lihat Hubungkan ke layanan IPC inti AWS IoT Greengrass.

package com.aws.greengrass.docs.samples.ipc; import com.aws.greengrass.docs.samples.ipc.util.IPCUtils; import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient; import software.amazon.awssdk.aws.greengrass.ListNamedShadowsForThingResponseHandler; import software.amazon.awssdk.aws.greengrass.model.ListNamedShadowsForThingRequest; import software.amazon.awssdk.aws.greengrass.model.ListNamedShadowsForThingResponse; import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError; import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError; import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection; import java.util.ArrayList; import java.util.List; import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; public class ListNamedShadowsForThing { public static final int TIMEOUT_SECONDS = 10; public static void main(String[] args) { // Use the current core device's name if thing name isn't set. String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0]; try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) { GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection); List<String> namedShadows = new ArrayList<>(); String nextToken = null; try { // Send additional requests until there's no pagination token in the response. do { ListNamedShadowsForThingResponseHandler responseHandler = ListNamedShadowsForThing.listNamedShadowsForThing(ipcClient, thingName, nextToken, 25); CompletableFuture<ListNamedShadowsForThingResponse> futureResponse = responseHandler.getResponse(); ListNamedShadowsForThingResponse response = futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS); List<String> responseNamedShadows = response.getResults(); namedShadows.addAll(responseNamedShadows); nextToken = response.getNextToken(); } while (nextToken != null); System.out.printf("Successfully got named shadows for thing %s: %s%n", thingName, String.join(",", namedShadows)); } catch (TimeoutException e) { System.err.println("Timeout occurred while listing named shadows for thing: " + thingName); } catch (ExecutionException e) { if (e.getCause() instanceof UnauthorizedError) { System.err.println("Unauthorized error while listing named shadows for " + "thing: " + thingName); } else if (e.getCause() instanceof ResourceNotFoundError) { System.err.println("Unable to find thing to list named shadows: " + thingName); } else { throw e; } } } catch (InterruptedException e) { System.out.println("IPC interrupted."); } catch (ExecutionException e) { System.err.println("Exception occurred when using IPC."); e.printStackTrace(); System.exit(1); } } public static ListNamedShadowsForThingResponseHandler listNamedShadowsForThing(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String nextToken, int pageSize) { ListNamedShadowsForThingRequest listNamedShadowsForThingRequest = new ListNamedShadowsForThingRequest(); listNamedShadowsForThingRequest.setThingName(thingName); listNamedShadowsForThingRequest.setNextToken(nextToken); listNamedShadowsForThingRequest.setPageSize(pageSize); return greengrassCoreIPCClient.listNamedShadowsForThing(listNamedShadowsForThingRequest, Optional.empty()); } }
Python (IPC client V1)

contoh Contoh: Daftar sesuatu yang bernama bayangan

import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from awsiot.greengrasscoreipc.model import ListNamedShadowsForThingRequest TIMEOUT = 10 def sample_list_named_shadows_for_thing_request(thingName, nextToken, pageSize): try: # set up IPC client to connect to the IPC server ipc_client = awsiot.greengrasscoreipc.connect() # create the ListNamedShadowsForThingRequest request list_named_shadows_for_thing_request = ListNamedShadowsForThingRequest() list_named_shadows_for_thing_request.thing_name = thingName list_named_shadows_for_thing_request.next_token = nextToken list_named_shadows_for_thing_request.page_size = pageSize # retrieve the ListNamedShadowsForThingRequest response after sending the request to the IPC server op = ipc_client.new_list_named_shadows_for_thing() op.activate(list_named_shadows_for_thing_request) fut = op.get_response() list_result = fut.result(TIMEOUT) # additional returned fields timestamp = list_result.timestamp next_token = result.next_token named_shadow_list = list_result.results return named_shadow_list, next_token, timestamp except InvalidArgumentsError as e: # add error handling ... # except ResourceNotFoundError | UnauthorizedError | ServiceError