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`, `name``extrinsicId`,, `extrinsicVersion` dan setidaknya satu elemen dalam setidaknya satu bagian berikut:
+ `properties`
+ `actions`
+ `events`
Elemen opsional dalam suatu kemampuan adalah`$ref`,`title`,`description`,`version`, `$defs` dan`extrinsicProperties`. Untuk kemampuan, `$ref` harus mengacu pada`aws.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 dipesan atau `matter`
**Example Contoh $ id**
```
/schema-version/capability/aws.Recording@1.0
```
## $ ref
`$ref`Elemen 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.
**Example 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.
**Example 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.
**Example Judul contoh**
```
Real-time Communication (RTC) Session Controller
Energy EVSE Capability
```
## deskripsi
`description`Elemen 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
**Example 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).
+ `MAJOR`versi, maksimal 3 digit
+ `MINOR`versi, maksimal 3 digit
+ `PATCH`versi (opsional), maksimal 4 digit
+ Panjangnya bisa antara 3 dan 12 karakter.
**Example 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 MAJOR.MINOR.PATCH format, 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.
**Example Contoh versi**
```
7
```
```
1567
```
## Extrinsicid (wajib)
`extrinsicId`Elemen tersebut mewakili pengenal yang dikelola di luar sistem IoT Amazon Web Services. Untuk kemampuan Matter, ia memetakan ke`clusterId`,`attributeId`,`commandId`,`eventId`, atau`fieldId`, tergantung pada konteksnya.
`extrinsicId`Dapat berupa bilangan bulat desimal dirangkai (1-10 digit) atau bilangan bulat heksadesimal dirangkai (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 VID yang dicadangkan ini untuk kemampuan.
**Example Contoh Extrinsicids**
```
0018
0x001A
0x15771002
```
## $ defs
`$defs`Bagian 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 URI-friendly karakter dalam nama definisi
+ Pastikan setiap nilai adalah sub-skema yang valid
+ Sertakan sejumlah sub-skema yang sesuai dengan batas ukuran dokumen skema
## ExtrinsicProperties
`extrinsicProperties`Elemen 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 berbagai`extrinsicProperties`, termasuk`access`,`apiMaturity`,`cli`,`cliFunctionName`, dan lain-lain. Properti ini memfasilitasi ACL untuk AWS (dan sebaliknya) transformasi model data.
**catatan**
Properti ekstrinsik didukung untuk`action`,, `event``property`, dan elemen `struct` bidang kemampuan, tetapi tidak untuk kemampuan atau cluster itu sendiri.
## Sifat-sifat
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 kendala 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` dan`value`. Elemen opsional dalam properti kemampuan adalah`description`,`retrievable`,`mutable`, `reportable` dan`extrinsicProperties`.
#### Nilai
Struktur tak terbatas yang memungkinkan pembangun untuk menempatkan batasan yang JSON-schema sesuai untuk menentukan tipe data properti ini.
Saat mendefinisikan nilai, ikuti batasan ini:
+ Untuk tipe sederhana, gunakan `type` dan JSON-schema kendala asli lainnya seperti atau `maxLength` `maximum`
+ Untuk jenis komposit, gunakan`oneOf`,`allOf`, atau`anyOf`. 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` dan`extrinsicId`. Elemen opsional adalah`description`,`extrinsicProperties`, `request` dan`response`.
### 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 adalah`parameters`. Elemen opsional adalah`description`,`extrinsicId`, dan`extrinsicProperties`.
#### 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 [SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API, permintaan mencapai perangkat dan mengharapkan respons asinkron kembali. Respons tindakan mendefinisikan struktur respons ini.
Untuk permintaan tindakan, elemen wajibnya adalah`parameters`. Elemen opsional adalah`name`,`description`,`extrinsicId`,`extrinsicProperties`, `errors` dan`responseCode`.
#### Deskripsi respons
Deskripsi mengikuti format yang sama dengan[deskripsi](#capability-schema-description), dan memiliki panjang maksimum 2048 karakter.
#### Nama respons
Nama mengikuti format yang sama seperti[nama (wajib)](#capability-schema-name), 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.
Batas:
+ 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
**Example 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` dan`value`. Elemen opsional adalah `description` dan`extrinsicProperties`.
Elemen deskripsi mengikuti format yang sama dengan[deskripsi](#capability-schema-description), dengan panjang maksimum 1024 karakter.
### `penggantian Extrinsicid` `dan ExtrinsicProperties`
`extrinsicId`dan `extrinsicProperties` ikuti format yang sama dengan [Extrinsicid (wajib)](#capability-schema-extrinsicId) dan[ExtrinsicProperties](#capability-schema-extrinsicProperties), 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`
**Example 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": {
...
}
```
### Built-in tindakan
Untuk semua kemampuan, Anda dapat melakukan tindakan khusus menggunakan kata kunci `ReadState` dan`UpdateState`. 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.
1. Perangkat itu baru saja disediakan dan belum memiliki status apa pun yang dipertahankan di cloud.
1. Status perangkat tidak sinkron dengan keadaan perangkat yang sebenarnya.
#### ReadState contoh
Periksa apakah lampu menyala atau mati menggunakan [SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API:
```
{
"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 [SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API:
```
{
"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