Skema untuk definisi kemampuan - Integrasi terkelola untuk AWS IoT Device Management
$ id (wajib)$ refnama (wajib)titledeskripsiversiExtrinsicVersion (wajib)Extrinsicid (wajib)$ defsExtrinsicPropertiesPropertiTindakanPeristiwa

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

Skema untuk definisi kemampuan

Kemampuan didokumentasikan menggunakan dokumen JSON deklaratif yang memberikan kontrak yang jelas tentang bagaimana kemampuan harus berfungsi dalam sistem.

Untuk kemampuan, elemen wajib adalah$id, nameextrinsicId,, extrinsicVersion dan setidaknya satu elemen dalam setidaknya satu bagian berikut:

  • properties

  • actions

  • events

Elemen opsional dalam suatu kemampuan adalah$ref,title,description,version, $defs danextrinsicProperties. Untuk kemampuan, $ref harus mengacu padaaws.capability.

Bagian berikut merinci skema yang digunakan untuk definisi kemampuan.

$ id (wajib)

Elemen $id mengidentifikasi definisi skema. Itu harus mengikuti struktur ini:

  • Mulai dengan awalan /schema-versions/ URI

  • Sertakan capability jenis skema

  • Gunakan garis miring maju (/) sebagai pemisah jalur URI

  • Sertakan identitas skema, dengan fragmen yang dipisahkan oleh periode () .

  • Gunakan @ karakter untuk memisahkan ID skema dan versi

  • Akhiri dengan versi semver, menggunakan period (.) untuk memisahkan fragmen versi

Identitas skema harus dimulai dengan namespace root yang panjangnya 3-12 karakter, diikuti oleh sub-namespace dan nama opsional.

Versi semver mencakup versi MAJOR (hingga 3 digit), versi MINOR (hingga 3 digit), dan versi PATCH opsional (hingga 4 digit).

catatan

Anda tidak dapat menggunakan ruang nama aws yang dicadangkan atau matter

contoh Contoh $ id
/schema-version/capability/aws.Recording@1.0

$ ref

$refElemen mengacu pada kemampuan yang ada dalam sistem. Ini mengikuti kendala yang sama dengan elemen. $id

catatan

Definisi atau kemampuan tipe harus ada dengan nilai yang disediakan dalam $ref file.

contoh Contoh $ ref
/schema-version/definition/aws.capability@1.0

nama (wajib)

Elemen nama adalah string yang mewakili nama entitas dalam dokumen skema. Ini sering berisi singkatan dan harus mengikuti aturan ini:

  • Hanya berisi karakter alfanumerik, titik (.), garis miring maju (/), tanda hubung (-), dan spasi

  • Mulailah dengan surat

  • Maksimal 64 karakter

Elemen nama digunakan di UI dan dokumentasi konsol Amazon Web Services.

contoh Contoh nama
Door Lock
On/Off
Wi-Fi Network Management
PM2.5 Concentration Measurement
RTCSessionController
Energy EVSE

title

Elemen judul adalah string deskriptif untuk entitas yang diwakili oleh dokumen skema. Ini dapat berisi karakter apa pun dan digunakan dalam dokumentasi. Panjang maksimum untuk judul kemampuan adalah 256 karakter.

contoh Judul contoh
Real-time Communication (RTC) Session Controller
Energy EVSE Capability

deskripsi

descriptionElemen memberikan penjelasan rinci tentang entitas yang diwakili oleh dokumen skema. Ini dapat berisi karakter apa pun dan digunakan dalam dokumentasi. Panjang maksimum untuk deskripsi kemampuan adalah 2048 karakter

contoh Deskripsi contoh
Electric Vehicle Supply Equipment (EVSE) is equipment used to charge an Electric Vehicle (EV) or Plug-In Hybrid Electric Vehicle. 
            This capability provides an interface to the functionality of Electric Vehicle Supply Equipment (EVSE) management.

versi

Elemen version bersifat opsional. Ini adalah string yang mewakili versi dokumen skema. Hal ini memiliki batasan berikut:

  • Menggunakan format semver, dengan fragmen versi berikut dipisahkan oleh . (periode).

    • MAJORversi, maksimal 3 digit

    • MINORversi, maksimal 3 digit

    • PATCHversi (opsional), maksimal 4 digit

  • Panjangnya bisa antara 3 dan 12 karakter.

contoh Contoh versi
1.0
1.12
1.4.1

Bekerja dengan versi kemampuan

Kemampuan adalah entitas berversi yang tidak dapat diubah. Setiap perubahan diharapkan untuk membuat versi baru. Sistem menggunakan versi semantik dengan format MAJOR.MINOR.PATCH, di mana:

  • Versi MAJOR meningkat saat membuat perubahan API yang tidak kompatibel ke belakang

  • Versi MINOR meningkat saat menambahkan fungsionalitas dengan cara yang kompatibel ke belakang

  • Versi PATCH meningkat saat membuat penambahan kecil yang tidak berdampak pada kemampuan.

Kemampuan yang berasal dari cluster Matter didasarkan pada versi 1.4 dan setiap rilis Matter diharapkan akan diimpor ke dalam sistem. Karena versi Matter menggunakan level semver MAJOR dan MINOR, integrasi terkelola hanya dapat menggunakan versi PATCH.

Saat Anda menambahkan versi PATCH untuk Matter, pastikan untuk memperhitungkan bahwa Matter menggunakan revisi berurutan. Semua versi PATCH harus mematuhi revisi yang didokumentasikan dalam spesifikasi Matter dan ini harus kompatibel ke belakang.

Untuk memperbaiki masalah yang tidak kompatibel ke belakang, Anda harus bekerja dengan Connectivity Standards Alliance (CSA) untuk menyelesaikannya dalam spesifikasi dan mendapatkan revisi baru yang dirilis.

AWS Kemampuan -managed dirilis dengan versi awal. 1.0 Dengan ini, ketiga level versi dapat digunakan.

ExtrinsicVersion (wajib)

Ini adalah string yang mewakili versi yang dikelola di luar AWS IoT sistem. Untuk kemampuan Matter, extrinsicVersion petakan ke revision

Ini direpresentasikan sebagai nilai bilangan bulat yang dirangkai, dan panjangnya bisa dari 1 hingga 10 digit numerik.

contoh Contoh versi
7
1567

Extrinsicid (wajib)

extrinsicIdElemen tersebut mewakili pengenal yang dikelola di luar sistem IoT Amazon Web Services. Untuk kemampuan Matter, ia memetakan keclusterId,attributeId,commandId,eventId, ataufieldId, tergantung pada konteksnya.

extrinsicIdDapat berupa bilangan bulat desimal stringifikasi (1-10 digit) atau bilangan bulat heksadesimal stringifikasi (awalan 0x atau 0X, diikuti oleh 1-8 digit heksadesimal).

catatan

Untuk AWS, Vendor ID (VID) adalah 0x1577, dan untuk Matter, itu adalah 0. Sistem memastikan bahwa skema khusus tidak menggunakan ini yang dicadangkan VIDs untuk kemampuan.

contoh Contoh ekstrinsicids
0018
0x001A
0x15771002

$ defs

$defsBagian ini adalah peta sub-skema yang dapat direferensikan dalam dokumen skema sebagaimana diizinkan oleh skema JSON. Dalam peta ini, kuncinya digunakan dalam definisi referensi lokal dan nilainya memberikan skema JSON.

catatan

Sistem hanya memberlakukan peta yang $defs valid dan bahwa setiap sub-skema adalah skema JSON yang valid. Tidak ada aturan tambahan yang diberlakukan.

Ikuti kendala ini saat bekerja dengan definisi:

  • Gunakan hanya karakter ramah URI dalam nama definisi

  • Pastikan setiap nilai adalah sub-skema yang valid

  • Sertakan sejumlah sub-skema yang sesuai dengan batas ukuran dokumen skema

ExtrinsicProperties

extrinsicPropertiesElemen berisi seperangkat properti yang didefinisikan dalam sistem eksternal tetapi dipertahankan dalam model data. Untuk kemampuan Matter, ia memetakan ke berbagai elemen yang tidak dimodelkan atau sebagian dimodelkan dalam cluster, atribut, perintah, atau peristiwa ZCL.

Properti Ekstrinsik harus mengikuti kendala ini:

  • Nama properti harus alfanumerik tanpa spasi atau karakter khusus

  • Nilai properti dapat berupa nilai skema JSON

  • Maksimal 20 properti

Sistem ini mendukung berbagaiextrinsicProperties, termasukaccess,apiMaturity,cli,cliFunctionName, dan lain-lain. Properti ini memfasilitasi ACL untuk AWS (dan sebaliknya) transformasi model data.

catatan

Properti ekstrinsik didukung untukaction,, eventproperty, dan elemen struct bidang kemampuan, tetapi tidak untuk kemampuan atau cluster itu sendiri.

Properti

Properti mewakili status kemampuan yang dikelola perangkat. Setiap negara didefinisikan sebagai pasangan kunci-nilai, di mana kunci menggambarkan nama negara dan nilai menggambarkan definisi negara.

Saat bekerja dengan properti, ikuti batasan ini:

  • Gunakan hanya karakter alfanumerik dalam nama properti, tanpa spasi atau karakter khusus

  • Sertakan sejumlah properti yang sesuai dengan batas ukuran dokumen skema

Bekerja dengan properti

Properti dalam kemampuan adalah elemen mendasar yang mewakili keadaan tertentu dari perangkat yang didukung oleh integrasi terkelola. Ini mewakili kondisi atau konfigurasi perangkat saat ini. Dengan menstandarisasi bagaimana properti ini didefinisikan dan terstruktur, sistem rumah pintar memastikan bahwa perangkat dari produsen yang berbeda dapat berkomunikasi secara efektif, menciptakan pengalaman yang mulus dan dapat dioperasikan.

Untuk properti kemampuan, elemen wajib adalah extrinsicId danvalue. Elemen opsional dalam properti kemampuan adalahdescription,retrievable,mutable, reportable danextrinsicProperties.

Nilai

Struktur tak terbatas yang memungkinkan pembangun untuk menempatkan batasan yang sesuai dengan skema JSON untuk menentukan tipe data properti ini.

Saat mendefinisikan nilai, ikuti batasan ini:

  • Untuk tipe sederhana, gunakan type dan batasan skema JSON asli lainnya seperti atau maxLength maximum

  • Untuk jenis komposit, gunakanoneOf,allOf, atauanyOf. Sistem tidak mendukung not kata kunci

  • Untuk merujuk ke tipe global apa pun, gunakan $ref dengan referensi yang dapat ditemukan yang valid

  • Untuk nullability, ikuti definisi skema tipe OpenAPI dengan menyediakan atribut nullable dengan flag boolean (jika null adalah nilai yang diizinkan) true

Contoh:

{
    "$ref": "/schema-versions/definition/matter.uint16@1.4",
    "nullable": true,
    "maximum": 4096
}

Dapat diambil

Boolean yang menjelaskan apakah status dapat dibaca atau tidak.

Aspek keterbacaan negara ditangguhkan pada implementasi kemampuan perangkat. Perangkat memutuskan apakah status tertentu dapat dibaca atau tidak. Aspek negara ini belum didukung untuk dilaporkan dalam laporan kemampuan dan karenanya tidak ditegakkan dalam sistem.

Contoh: true atau false

bisa berubah

Boolean yang menjelaskan apakah status dapat ditulis atau tidak.

Aspek kemampuan tulis negara ditangguhkan pada implementasi kemampuan perangkat. Perangkat memutuskan apakah status tertentu dapat ditulis atau tidak. Aspek negara ini belum didukung untuk dilaporkan dalam laporan kemampuan dan karenanya tidak ditegakkan dalam sistem.

Contoh: true atau false

Dilapor

Boolean yang menjelaskan jika status dilaporkan oleh perangkat ketika ada perubahan status.

Aspek reportabilitas negara ditangguhkan pada implementasi kemampuan perangkat. Perangkat memutuskan apakah status tertentu dapat dilaporkan atau tidak. Aspek negara ini belum didukung untuk dilaporkan dalam laporan kemampuan dan karenanya tidak ditegakkan dalam sistem.

Contoh: true atau false

Tindakan

Tindakan adalah operasi yang dikelola skema yang mengikuti model permintaan-respons. Setiap tindakan mewakili operasi yang diimplementasikan perangkat.

Ikuti kendala ini saat menerapkan tindakan:

  • Sertakan hanya tindakan unik dalam larik tindakan

  • Sertakan sejumlah tindakan yang sesuai dengan batas ukuran dokumen skema

Bekerja dengan tindakan

Tindakan adalah cara standar untuk berinteraksi dengan dan mengontrol kemampuan perangkat dalam sistem integrasi terkelola. Ini merupakan perintah atau operasi tertentu yang dapat dijalankan pada perangkat, lengkap dengan format terstruktur untuk memodelkan permintaan atau parameter respons yang diperlukan. Tindakan ini berfungsi sebagai jembatan antara niat pengguna dan operasi perangkat, memungkinkan kontrol yang konsisten dan andal di berbagai jenis perangkat pintar.

Untuk suatu tindakan, elemen wajib adalah name danextrinsicId. Elemen opsional adalahdescription,extrinsicProperties, request danresponse.

Deskripsi

Deskripsi memiliki batasan panjang maksimum 1536 karakter.

Permintaan

Bagian permintaan bersifat opsional dan dapat dihilangkan jika tidak ada parameter permintaan. Jika dihilangkan, sistem mendukung pengiriman permintaan tanpa muatan apa pun hanya dengan menggunakan nama. Action Ini digunakan dalam tindakan sederhana, seperti menyalakan atau mematikan lampu.

Tindakan kompleks membutuhkan parameter tambahan. Misalnya, permintaan untuk melakukan streaming rekaman kamera mungkin mencakup parameter tentang protokol streaming yang akan digunakan atau apakah akan mengirim aliran ke perangkat tampilan tertentu.

Untuk permintaan tindakan, elemen wajibnya adalahparameters. Elemen opsional adalahdescription,extrinsicId, danextrinsicProperties.

Minta deskripsi

Deskripsi mengikuti format yang sama dengan bagian 3.5, dengan panjang maksimum 2048 karakter.

Respons

Dalam integrasi terkelola, untuk permintaan tindakan apa pun yang dikirim melalui SendManagedThingCommandAPI, permintaan mencapai perangkat dan mengharapkan respons asinkron kembali. Respons tindakan mendefinisikan struktur respons ini.

Untuk permintaan tindakan, elemen wajibnya adalahparameters. Elemen opsional adalahname,description,extrinsicId,extrinsicProperties, errors danresponseCode.

Deskripsi respons

Deskripsi mengikuti format yang sama dengandeskripsi, dan memiliki panjang maksimum 2048 karakter.

Nama respons

Nama mengikuti format yang sama sepertinama (wajib), dengan rincian tambahan ini:

  • Nama konvensional respons diturunkan dengan Response menambahkan nama tindakan.

  • Jika Anda ingin menggunakan nama yang berbeda, Anda dapat memberikannya dalam name elemen ini. Jika a name diberikan dalam respons, maka nilai ini lebih diutamakan daripada nama konvensional.

Kesalahan

Array pesan unik tak terbatas yang disediakan dalam respons, jika ada kesalahan saat memproses permintaan.

Batasan:

  • Item pesan dideklarasikan sebagai objek JSON dengan bidang berikut:

    • code: String yang berisi karakter alfanumerik dan _ (garis bawah), dengan panjang antara 1 hingga 64 karakter

    • message: Nilai string tak terbatas

contoh Contoh pesan kesalahan
"errors": [
   {  
      "code": "AD_001", 
      "message": "Unable to receive signal from the sensor. Please check connection with the sensor." 
   }
]

Kode respons

Kode integer yang menampilkan bagaimana permintaan ditangani. Sebaiknya kode perangkat mengembalikan kode menggunakan spesifikasi kode status respons server HTTP untuk memungkinkan keseragaman dalam sistem.

Kendala: Nilai integer mulai dari 100 hingga 599.

Parameter permintaan atau respons

Bagian parameter didefinisikan sebagai peta nama dan pasangan sub-skema. Sejumlah parameter dapat didefinisikan dalam parameter permintaan, jika mereka dapat masuk dalam dokumen skema.

Nama parameter hanya dapat berisi karakter alfanumerik. Spasi atau karakter lainnya tidak diperbolehkan.

bidang parameter

Elemen wajib dalam a parameter adalah extrinsicId danvalue. Elemen opsional adalah description danextrinsicProperties.

Elemen deskripsi mengikuti format yang sama dengandeskripsi, dengan panjang maksimum 1024 karakter.

extrinsicIddan extrinsicProperties mengesampingkan

extrinsicIddan extrinsicProperties ikuti format yang sama dengan Extrinsicid (wajib) danExtrinsicProperties, dengan detail tambahan ini:

  • Jika extrinsicId diberikan dalam permintaan atau respons, nilai ini lebih diutamakan daripada nilai yang diberikan pada tingkat tindakan. Sistem harus menggunakan request/response level extrinsicId terlebih dahulu, jika hilang gunakan level tindakan extrinsicId

  • Jika extrinsicProperties disediakan dalam permintaan atau respons, properti ini lebih diutamakan daripada nilai va yang diberikan pada tingkat tindakan. Sistem harus mengambil level tindakan extrinsicProperties dan mengganti pasangan kunci-nilai yang disediakan di level tersebut request/response extrinsicProperties

contoh Contoh penggantian Extrinsicid dan ExtrinsicProperties
{
   "name": "ToggleWithEffect",
   "extrinsicId": "0x0001",
  
   "extrinsicProperties": {
      "apiMaturity": "provisional",
      "introducedIn": "1.2"
   },
   "request": {
      "extrinsicProperties": {
         "apiMaturity": "stable",
         "manufacturerCode": "XYZ"
      },
      "parameters": {
         ...
      }
   },
   "response": {
      "extrinsicProperties": {
         "noDefaultImplementation": true
      },
      "parameters": {
 {
         ...
      }
   }
}

Dalam contoh di atas, nilai efektif untuk permintaan tindakan adalah:

# effective request
"name": "ToggleWithEffect",
"extrinsicId": "0x0001",
"extrinsicProperties": {
   "apiMaturity": "stable",
   "introducedIn": "1.2"
   "manufacturerCode": "XYZ"
},
"parameters": {
   ...
}

# effective response
"name": "ToggleWithEffectResponse",
"extrinsicId": "0x0001",
"extrinsicProperties": {
   "apiMaturity": "provisional",
   "introducedIn": "1.2"
   "noDefaultImplementation": true
},
"parameters": {
   ...
}

Tindakan bawaan

Untuk semua kemampuan, Anda dapat melakukan tindakan khusus menggunakan kata kunci ReadState danUpdateState. Kedua kata kunci tindakan ini akan bertindak berdasarkan properti kemampuan yang didefinisikan dalam model data.

ReadState

Mengirim perintah ke managedThing untuk membaca nilai-nilai properti statusnya. Gunakan ReadState sebagai cara untuk memaksa status perangkat diperbarui.

UpdateState

Mengirim perintah untuk memperbarui beberapa properti.

Memaksa sinkronisasi status perangkat mungkin berguna dalam skenario berikut:

  1. Perangkat itu offline untuk jangka waktu tertentu dan tidak memancarkan peristiwa.

  2. Perangkat baru saja disediakan dan belum memiliki status apa pun yang dipertahankan di cloud.

  3. Status perangkat tidak sinkron dengan keadaan perangkat yang sebenarnya.

ReadState contoh

Periksa apakah lampu menyala atau mati menggunakan SendManagedThingCommandAPI:

{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "aws.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "ReadState",
              "parameters": {
                "propertiesToRead": [ "OnOff" ]
              }
            }
          ]
        }
      ]
    }
  ]
}

Baca semua properti status untuk matter.OnOff kemampuan:

{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "aws.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "ReadState",
              "parameters": {
                "propertiesToRead": [ "*" ] 
                // Use the wildcard operator to read ALL state properties for a capability
              }
            }
          ]
        }
      ]
    }
  ]
}

UpdateState contoh

Ubah lampu OnTime untuk menggunakan SendManagedThingCommandAPI:

{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "matter.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "UpdateState",
              "parameters": {
                "OnTime": 5
              }
            }
          ]
        }
      ]
    }
  ]
}

Peristiwa

Peristiwa adalah sinyal searah yang dikelola skema yang diimplementasikan oleh perangkat.

Menerapkan acara sesuai dengan kendala ini:

  • Sertakan hanya acara unik dalam array acara

  • Sertakan sejumlah peristiwa yang sesuai dengan batas ukuran dokumen skema