Kelola pengindeksan hal - AWS IoT Core
Mengaktifkan pengindeksan halMenggambarkan indeks sesuatuMenanyakan indeks sesuatuPembatasan dan batasanOtorisasi

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

Kelola pengindeksan hal

Indeks yang dibuat untuk semua barang Anda adalahAWS_Things. Anda dapat mengontrol apa yang akan diindeks dari sumber data berikut: data AWS IoT registri, data AWS IoT Device Shadow, data AWS IoT konektivitas, dan data AWS IoT Device Defenderpelanggaran.

Mengaktifkan pengindeksan hal

Anda menggunakan perintah CLI update-indexing-configuration atau operasi Configuration API untuk membuat indeks UpdateIndexingdan mengontrol konfigurasinya. AWS_Things Dengan menggunakan parameter --thing-indexing-configuration (thingIndexingConfiguration), Anda mengontrol jenis data (misalnya, registri, bayangan, data konektivitas perangkat, dan data pelanggaran Device Defender) yang diindeks.

--thing-indexing-configurationParameter mengambil string dengan struktur berikut:

{
  "thingIndexingMode": "OFF"|"REGISTRY"|"REGISTRY_AND_SHADOW",
  "thingConnectivityIndexingMode": "OFF"|"STATUS",
  "deviceDefenderIndexingMode": "OFF"|"VIOLATIONS",
  "namedShadowIndexingMode": "OFF"|"ON",
  "managedFields": [
    {
      "name": "string",
      "type": "Number"|"String"|"Boolean"
    }, 
    ...
  ], 
  "customFields": [
    { 
      "name": "string",
      "type": "Number"|"String"|"Boolean" 
    },
    ...
  ],
  "filter": {
     "namedShadowNames": [ "string" ],
     "geoLocations": [
        {
            "name": "String",
            "order": "LonLat|LatLon"
        }
    ]
  }
}

Mode pengindeksan hal

Anda dapat menentukan mode pengindeksan hal yang berbeda dalam konfigurasi pengindeksan Anda, tergantung pada sumber data apa yang ingin Anda indeks dan cari perangkat dari:

  • thingIndexingMode: Kontrol jika registri atau bayangan diindeks. Kapan thingIndexingMode diatur menjadiOFF, pengindeksan hal dinonaktifkan.

  • thingConnectivityIndexingMode: Menentukan apakah data konektivitas hal diindeks.

  • deviceDefenderIndexingMode: Menentukan apakah data pelanggaran Device Defender diindeks.

  • namedShadowIndexingMode: Menentukan jika bernama data bayangan diindeks. Untuk memilih bayangan bernama untuk ditambahkan ke konfigurasi pengindeksan armada Anda, setel namedShadowIndexingMode menjadi ON dan tentukan nama bayangan bernama Anda. filter

Tabel di bawah ini menunjukkan nilai yang valid untuk setiap mode pengindeksan dan sumber data yang diindeks untuk setiap nilai.

Atribut Nilai valid Registri Bayangan Konektivitas Pelanggaran DD Bernama bayangan
thingIndexingMode MATI
REGISTRASI ✓
REGISTRY_AND_SHADOW ✓ ✓
thingConnectivityIndexingMode Tidak ditentukan.
MATI
STATUS ✓
deviceDefenderIndexingMode Tidak ditentukan.
MATI
PELANGGARAN ✓
namedShadowIndexingMode Tidak ditentukan.
MATI
PADA ✓

Bidang terkelola dan bidang kustom

Bidang yang dikelola

Bidang terkelola berisi data yang terkait dengan hal-hal, grup benda, bayangan perangkat, konektivitas perangkat, dan pelanggaran Device Defender. AWS IoT mendefinisikan tipe data di bidang terkelola. Anda menentukan nilai dari setiap bidang terkelola saat Anda membuat AWS IoT sesuatu. Misalnya, nama benda, grup benda, dan deskripsi benda semuanya adalah bidang yang dikelola. Pengindeksan armada mengindeks bidang terkelola berdasarkan mode pengindeksan yang Anda tentukan. Bidang terkelola tidak dapat diubah atau ditampilkancustomFields.

Bidang kustom

Anda dapat menggabungkan atribut, data Device Shadow, dan data pelanggaran Device Defender dengan membuat bidang khusus untuk mengindeksnya. customFieldsAtribut adalah daftar nama bidang dan pasangan tipe data. Anda dapat melakukan kueri agregasi berdasarkan tipe data. Mode pengindeksan yang Anda pilih mempengaruhi bidang dapat ditentukan. customFields Misalnya, jika Anda menentukan mode REGISTRY pengindeksan, Anda tidak dapat menentukan bidang kustom dari bayangan benda. Anda dapat menggunakan perintah CLI update-indexing-configuration untuk membuat atau memperbarui bidang kustom (lihat perintah contoh di Memperbarui contoh konfigurasi pengindeksan). Untuk informasi selengkapnya, lihat Bidang kustom.

Filter pengindeksan

Filter pengindeksan menyediakan pilihan tambahan untuk bayangan bernama dan data geolokasi.

namedShadowNames

Untuk menambahkan bayangan bernama ke konfigurasi pengindeksan armada Anda, atur namedShadowIndexingMode menjadi ON dan tentukan nama bayangan bernama Anda di namedShadowNames filter.

Contoh

"filter": {
     "namedShadowNames": [ "namedShadow1", "namedShadow2" ]
}

geoLocations

Untuk menambahkan data geolokasi ke konfigurasi pengindeksan armada Anda:

  • Jika data geolokasi Anda disimpan dalam bayangan klasik (tanpa nama), atur thingIndexingMode menjadi REGISTRY_AND_SHADOW, dan tentukan data geolokasi Anda dalam filter. geoLocations

    Contoh filter di bawah ini menentukan objek GeoLocation dalam bayangan klasik (tanpa nama):

    "filter": {
     "geoLocations": [
        {
            "name": "shadow.reported.location",
            "order": "LonLat"
        }
     ]
  }

  • Jika data geolokasi Anda disimpan dalam bayangan bernama, atur namedShadowIndexingMode menjadi ON, tambahkan nama bayangan di namedShadowNames filter, dan tentukan data geolokasi Anda di geoLocations filter.

    Contoh filter di bawah ini menentukan objek GeoLocation dalam bayangan bernama ()nameShadow1:

    "filter": {
     "namedShadowNames": [ "namedShadow1" ],
     "geoLocations": [
        {
            "name": "shadow.name.namedShadow1.reported.location",
            "order": "LonLat"
        }
     ]
  }

Untuk informasi selengkapnya, lihat IndexingFilterdari Referensi AWS IoTAPI.

Memperbarui contoh konfigurasi pengindeksan

Untuk memperbarui konfigurasi pengindeksan Anda, gunakan perintah AWS IoT update-indexing-configuration CLI. Contoh berikut menunjukkan cara menggunakanupdate-indexing-configuration.

Sintaks pendek:

aws iot update-indexing-configuration --thing-indexing-configuration \
'thingIndexingMode=REGISTRY_AND_SHADOW, deviceDefenderIndexingMode=VIOLATIONS, 
namedShadowIndexingMode=ON,filter={namedShadowNames=[thing1shadow]}, thingConnectivityIndexingMode=STATUS,
customFields=[{name=attributes.version,type=Number},
{name=shadow.name.thing1shadow.desired.DefaultDesired, type=String}, {name=shadow.desired.power, type=Boolean}, 
{name=deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number, type=Number}]'

Sintaks JSON:

aws iot update-indexing-configuration --cli-input-json \ '{
          "thingIndexingConfiguration": { "thingIndexingMode": "REGISTRY_AND_SHADOW",
          "thingConnectivityIndexingMode": "STATUS", 
          "deviceDefenderIndexingMode": "VIOLATIONS",
          "namedShadowIndexingMode": "ON",
          "filter": { "namedShadowNames": ["thing1shadow"]},
          "customFields": [ { "name": "shadow.desired.power", "type": "Boolean" }, 
          {"name": "attributes.version", "type": "Number"}, 
          {"name": "shadow.name.thing1shadow.desired.DefaultDesired", "type": "String"}, 
          {"name": "deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number", "type": Number} ] } }'

Perintah ini tidak menghasilkan output apa pun.

Untuk memeriksa status indeks benda, jalankan perintah describe-index CLI: 

aws iot describe-index --index-name "AWS_Things"

Output dari describe-index perintah terlihat seperti berikut:

{
    "indexName": "AWS_Things",
    "indexStatus": "ACTIVE",
    "schema": "MULTI_INDEXING_MODE"
}
catatan

Diperlukan waktu sejenak bagi pengindeksan armada untuk memperbarui indeks armada. Kami sarankan menunggu hingga indexStatus acara ACTIVE sebelum menggunakannya. Anda dapat memiliki nilai yang berbeda di bidang skema tergantung pada sumber data apa yang telah Anda konfigurasikan. Untuk informasi selengkapnya, lihat Menjelaskan indeks sesuatu.

Untuk mendapatkan detail konfigurasi pengindeksan hal Anda, jalankan perintah get-indexing-configuration CLI: 

aws iot get-indexing-configuration

Output dari get-indexing-configuration perintah terlihat seperti berikut:

{
    "thingIndexingConfiguration": {
        "thingIndexingMode": "REGISTRY_AND_SHADOW",
        "thingConnectivityIndexingMode": "STATUS",
        "deviceDefenderIndexingMode": "VIOLATIONS",
        "namedShadowIndexingMode": "ON",
        "managedFields": [
            {
                "name": "connectivity.disconnectReason",
                "type": "String"
            },
            {
                "name": "registry.version",
                "type": "Number"
            },
            {
                "name": "thingName",
                "type": "String"
            },
            {
                "name": "deviceDefender.violationCount",
                "type": "Number"
            },
            {
                "name": "shadow.hasDelta",
                "type": "Boolean"
            },
            {
                "name": "shadow.name.*.version",
                "type": "Number"
            },
            {
                "name": "shadow.version",
                "type": "Number"
            },
            {
                "name": "connectivity.version",
                "type": "Number"
            },
            {
                "name": "connectivity.timestamp",
                "type": "Number"
            },
            {
                "name": "shadow.name.*.hasDelta",
                "type": "Boolean"
            },
            {
                "name": "registry.thingTypeName",
                "type": "String"
            },
            {
                "name": "thingId",
                "type": "String"
            },
            {
                "name": "connectivity.connected",
                "type": "Boolean"
            },
            {
                "name": "registry.thingGroupNames",
                "type": "String"
            }
        ],
        "customFields": [
            {
                "name": "shadow.name.thing1shadow.desired.DefaultDesired",
                "type": "String"
            },

            {
                "name": "deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number",
                "type": "Number"
            },
            {
                "name": "shadow.desired.power",
                "type": "Boolean"
            },
            {
                "name": "attributes.version",
                "type": "Number"
            }
        ], 
        "filter": {
              "namedShadowNames": [
                  "thing1shadow"
              ]
          }
      },
    "thingGroupIndexingConfiguration": {
        "thingGroupIndexingMode": "OFF"
    }
}

Untuk memperbarui bidang khusus, Anda dapat menjalankan update-indexing-configuration perintah. Contohnya adalah sebagai berikut:

aws iot update-indexing-configuration --thing-indexing-configuration
          'thingIndexingMode=REGISTRY_AND_SHADOW,customFields=[{name=attributes.version,type=Number},{name=attributes.color,type=String},{name=shadow.desired.power,type=Boolean},{name=shadow.desired.intensity,type=Number}]'

Perintah ini ditambahkan shadow.desired.intensity ke konfigurasi pengindeksan.

catatan

Memperbarui konfigurasi pengindeksan bidang kustom menimpa semua bidang kustom yang ada. Pastikan untuk menentukan semua bidang khusus saat meneleponupdate-indexing-configuration.

Setelah indeks dibangun kembali, Anda dapat menggunakan kueri agregasi pada bidang yang baru ditambahkan, mencari data registri, data bayangan, dan data status konektivitas benda.

Saat mengubah mode pengindeksan, pastikan semua bidang kustom Anda valid dengan menggunakan mode pengindeksan baru. Misalnya, jika Anda mulai menggunakan REGISTRY_AND_SHADOW mode dengan bidang khusus yang disebutshadow.desired.temperature, Anda harus menghapus bidang shadow.desired.temperature khusus sebelum mengubah mode pengindeksan menjadiREGISTRY. Jika konfigurasi pengindeksan Anda berisi bidang khusus yang tidak diindeks oleh mode pengindeksan, pembaruan gagal.

Menggambarkan indeks sesuatu

Perintah berikut menunjukkan cara menggunakan perintah describe-index CLI untuk mengambil status indeks benda saat ini.

aws iot describe-index --index-name "AWS_Things"

Respons perintah dapat terlihat seperti berikut:

{
    "indexName": "AWS_Things", 
    "indexStatus": "BUILDING", 
    "schema": "REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS"
}

Pertama kali Anda mengindeks armada, AWS IoT membangun indeks Anda. indexStatusKapan dalam BUILDING keadaan, Anda tidak dapat menanyakan indeks. Indeks schema for the things menunjukkan jenis data (REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS) yang diindeks.

Mengubah konfigurasi indeks Anda menyebabkan indeks dibangun kembali. Selama proses ini, indexStatus adalahREBUILDING. Anda dapat menjalankan kueri pada data dalam indeks things saat sedang dibangun kembali. Misalnya, jika Anda mengubah konfigurasi indeks dari REGISTRY ke REGISTRY_AND_SHADOW saat indeks sedang dibangun kembali, Anda dapat meminta data registri, termasuk pembaruan terbaru. Namun, Anda tidak dapat menanyakan data bayangan hingga pembangunan kembali selesai. Jumlah waktu yang diperlukan untuk membangun atau membangun kembali indeks tergantung pada jumlah data.

Anda dapat melihat nilai yang berbeda di bidang skema tergantung pada sumber data yang telah Anda konfigurasi. Tabel berikut menunjukkan nilai skema yang berbeda dan deskripsi yang sesuai:

Skema Deskripsi
MATI Tidak ada sumber data yang dikonfigurasi atau diindeks.
REGISTRASI Data registri diindeks.
REGISTRY_AND_SHADOW Data registri dan data bayangan (klasik) yang tidak disebutkan namanya diindeks.
REGISTRY_AND_CONNECTIVITY Data registri dan data konektivitas diindeks.
REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS REGISTRY_SHADOW_STATUS Data registri, data bayangan tanpa nama (klasik), dan data konektivitas diindeks.
MULTI_INDEXING_MODE

Bayangan bernama atau Device Defender data pelanggaran diindeks, selain registri, bayangan tanpa nama (klasik) atau data konektivitas.

Menanyakan indeks sesuatu

Gunakan perintah search-index CLI untuk menanyakan data dalam indeks.

aws iot search-index --index-name "AWS_Things" --query-string
          "thingName:mything*"
{  
    "things":[{  
         "thingName":"mything1",
         "thingGroupNames":[  
            "mygroup1"
         ],
         "thingId":"a4b9f759-b0f2-4857-8a4b-967745ed9f4e",
         "attributes":{  
            "attribute1":"abc"
         },
         "connectivity": { 
            "connected":false,
            "timestamp":1556649874716,
            "disconnectReason": "CONNECTION_LOST"
         }         
    },
    {  
        "thingName":"mything2",
        "thingTypeName":"MyThingType",
        "thingGroupNames":[  
            "mygroup1",
            "mygroup2"
        ],
        "thingId":"01014ef9-e97e-44c6-985a-d0b06924f2af",
        "attributes":{  
            "model":"1.2",
            "country":"usa"
        },
        "shadow":{  
            "desired":{  
                "location":"new york",
                "myvalues":[3, 4, 5]
            },
            "reported":{  
                "location":"new york",
                "myvalues":[1, 2, 3],
                "stats":{  
                    "battery":78
                }
            },
            "metadata":{  
                 "desired":{  
                       "location":{  
                            "timestamp":123456789
                        },
                       "myvalues":{  
                             "timestamp":123456789
                       }
                  },
                  "reported":{  
                        "location":{  
                             "timestamp":34535454
                         },
                        "myvalues":{  
                             "timestamp":34535454
                        },
                        "stats":{  
                             "battery":{  
                                   "timestamp":34535454
                             }
                        }
                 }
            },
            "version":10,
            "timestamp":34535454
        },
        "connectivity": { 
            "connected":true,
            "timestamp":1556649855046
        }        
    }],
    "nextToken":"AQFCuvk7zZ3D9pOYMbFCeHbdZ+h=G"
}

Dalam respons JSON, "connectivity" (sebagaimana diaktifkan oleh thingConnectivityIndexingMode=STATUS pengaturan) memberikan nilai Boolean, stempel waktu, dan DisconnectAson yang menunjukkan apakah perangkat terhubung ke. AWS IoT Core Perangkat "mything1" terputus (false) pada waktu POSIX 1556649874716 karena. CONNECTION_LOST Untuk informasi selengkapnya tentang alasan pemutusan sambungan, lihat Peristiwa siklus hidup. 

"connectivity": { 
    "connected":false,
    "timestamp":1556649874716, 
    "disconnectReason": "CONNECTION_LOST"
}

Perangkat "mything2" terhubung (true) pada waktu 1556649855046 POSIX:

"connectivity": { 
    "connected":true,
    "timestamp":1556649855046
}

Stempel waktu diberikan dalam milidetik sejak zaman, jadi 1556649855046 mewakili 18:44:15.046 pada hari Selasa, 30 April 2019 (UTC).

penting

Jika perangkat telah terputus selama kurang lebih satu jam, "timestamp" nilai dan "disconnectReason" nilai status konektivitas mungkin hilang.

Pembatasan dan batasan

Ini adalah batasan dan batasan untukAWS_Things.

Bidang bayangan dengan tipe kompleks

Bidang bayangan diindeks hanya jika nilai bidang adalah tipe sederhana, seperti objek JSON yang tidak berisi array, atau array yang seluruhnya terdiri dari tipe sederhana. Tipe sederhana berarti string, angka, atau salah satu literal true ataufalse. Misalnya, mengingat status bayangan berikut, nilai bidang "palette" tidak diindeks karena itu adalah array yang berisi item dari tipe kompleks. Nilai bidang "colors" diindeks karena setiap nilai dalam array adalah string. 

{
    "state": {
        "reported": {
            "switched": "ON",
            "colors": [ "RED", "GREEN", "BLUE" ],
            "palette": [
                {
                    "name": "RED", 
                    "intensity": 124
                },
                {
                    "name": "GREEN", 
                    "intensity": 68
                },
                {
                    "name": "BLUE", 
                    "intensity": 201
                }
            ]
        }
    }
}
Nama bidang bayangan bersarang

Nama-nama bidang bayangan bersarang disimpan sebagai string terbatas periode (.). Misalnya, diberikan dokumen bayangan:

{
  "state": {
    "desired": {
      "one": {
        "two": {
          "three": "v2"
        }
      }
    }    
  }
}

Nama bidang three disimpan sebagaidesired.one.two.three. Jika Anda juga memiliki dokumen bayangan, itu disimpan seperti ini:

{
  "state": {
    "desired": {
      "one.two.three": "v2"
    }    
  }
}

Keduanya cocok dengan kueri untukshadow.desired.one.two.three:v2. Sebagai praktik terbaik, jangan gunakan titik dalam nama bidang bayangan.

Metadata bayangan

Bidang di bagian metadata bayangan diindeks, tetapi hanya jika bidang yang sesuai di bagian bayangan diindeks. "state" (Pada contoh sebelumnya, "palette" bidang di bagian metadata bayangan juga tidak diindeks.)

Perangkat yang tidak terdaftar

Pengindeksan armada mengindeks status konektivitas untuk perangkat yang clientId koneksinya sama dengan hal thingName yang terdaftar di Registry.

Bayangan yang tidak terdaftar

Jika Anda menggunakan UpdateThingShadow untuk membuat bayangan menggunakan nama benda yang belum terdaftar di AWS IoT akun Anda, bidang dalam bayangan ini tidak diindeks. Ini berlaku untuk bayangan klasik tanpa nama dan bayangan bernama.

Nilai numerik

Jika ada data registri atau bayangan yang dikenali oleh layanan sebagai nilai numerik, itu diindeks seperti itu. Anda dapat membentuk kueri yang melibatkan rentang dan operator perbandingan pada nilai numerik (misalnya, "attribute.foo<5" atau"shadow.reported.foo:[75 TO 80]"). Untuk dikenali sebagai numerik, nilai data harus berupa nomor JSON tipe literal yang valid. Nilai dapat berupa bilangan bulat dalam rentang -2^53... 2^53-1, floating point presisi ganda dengan notasi eksponensial opsional, atau bagian dari array yang hanya berisi nilai-nilai ini.

Nilai nol

Nilai nol tidak diindeks.

Nilai maksimum

Jumlah maksimum bidang kustom untuk kueri agregasi adalah 5.

Jumlah maksimum persentil yang diminta untuk kueri agregasi adalah 100.

Otorisasi

Anda dapat menentukan indeks things sebagai Amazon Resource Name (ARN) dalam tindakan AWS IoT kebijakan, sebagai berikut.

Tindakan Sumber Daya

iot:SearchIndex

Indeks ARN (misalnya,arn:aws:iot:your-aws-regionyour-aws-account:index/AWS_Things).

iot:DescribeIndex

Indeks ARN (misalnya,arn:aws:iot:your-aws-region:index/AWS_Things).
catatan

Jika Anda memiliki izin untuk menanyakan indeks armada, Anda dapat mengakses data berbagai hal di seluruh armada.