기능 정의 스키마 - 에 대한 관리형 통합 AWS IoT Device Management
$id(필수)$ref이름(필수)제목설명versionextrinsicVersion(필수)extrinsicId(필수)$defsextrinsicProperties속성작업이벤트

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

기능 정의 스키마

기능은 시스템 내에서 기능이 작동하는 방식에 대한 명확한 계약을 제공하는 선언적 JSON 문서를 사용하여 문서화됩니다.

기능의 경우 필수 요소는 $id, nameextrinsicId, extrinsicVersion 및 다음 섹션 중 하나 이상에 있는 하나 이상의 요소입니다.

  • properties

  • actions

  • events

기능의 선택적 요소는 $ref, title, description, 및 version $defs 입니다extrinsicProperties. 기능의 경우는를 참조$ref해야 합니다aws.capability.

다음 섹션에서는 기능 정의에 사용되는 스키마를 자세히 설명합니다.

$id(필수)

$id 요소는 스키마 정의를 식별합니다. 다음 구조를 따라야 합니다.

  • /schema-versions/ URI 접두사로 시작

  • capability 스키마 유형 포함

  • URI 경로 구분자로 슬래시(/) 사용

  • 조각을 마침표로 구분하여 스키마 자격 증명 포함(.)

  • @ 문자를 사용하여 스키마 ID와 버전을 구분합니다.

  • 마침표(.)를 사용하여 버전 조각을 분리하는 셈버 버전으로 끝납니다.

스키마 자격 증명은 3~12자 길이의 루트 네임스페이스로 시작한 다음 선택적 하위 네임스페이스와 이름으로 시작해야 합니다.

셈버 버전에는 메이저 버전(최대 3자리), 마이너 버전(최대 3자리) 및 선택적 패치 버전(최대 4자리)이 포함됩니다.

참고

예약된 네임스페이스 aws 또는를 사용할 수 없습니다. matter

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

$ref

$ref 요소는 시스템 내의 기존 기능을 참조합니다. $id 요소와 동일한 제약 조건을 따릅니다.

참고

형식 정의 또는 기능은 $ref 파일에 제공된 값과 함께 존재해야 합니다.

예제 $ref
/schema-version/definition/aws.capability@1.0

이름(필수)

이름 요소는 스키마 문서의 엔터티 이름을 나타내는 문자열입니다. 종종 약어가 포함되어 있으며 다음 규칙을 따라야 합니다.

  • 영숫자, 마침표(.), 슬래시(/), 하이픈(-) 및 공백만 포함

  • 문자로 시작

  • 최대 64자

이름 요소는 Amazon Web Services 콘솔 UI 및 설명서에 사용됩니다.

예제 이름
Door Lock
On/Off
Wi-Fi Network Management
PM2.5 Concentration Measurement
RTCSessionController
Energy EVSE

제목

제목 요소는 스키마 문서로 표시되는 개체에 대한 설명 문자열입니다. 모든 문자를 포함할 수 있으며 설명서에 사용됩니다. 기능 제목의 최대 길이는 256자입니다.

예 제목 예
Real-time Communication (RTC) Session Controller
Energy EVSE Capability

설명

description 요소는 스키마 문서로 표시되는 개체에 대한 자세한 설명을 제공합니다. 모든 문자를 포함할 수 있으며 설명서에 사용됩니다. 기능 설명의 최대 길이는 2048자입니다.

예제 설명
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.

version

version 요소는 옵션입니다. 스키마 문서의 버전을 나타내는 문자열입니다. 다음과 같은 제약이 있습니다.

  • 다음 버전 조각을 . (마침표)로 구분하여 semver 형식을 사용합니다.

    • MAJOR 버전, 최대 3자리

    • MINOR 버전, 최대 3자리

    • PATCH 버전(선택 사항), 최대 4자리

  • 길이는 3~12자입니다.

예제 버전
1.0
1.12
1.4.1

기능 버전 작업

기능은 변경 불가능한 버전이 지정된 엔터티입니다. 모든 변경 사항은 새 버전을 생성해야 합니다. 시스템은 다음과 같은 MAJOR.MINOR.PATCH 형식의 의미 체계 버전 관리를 사용합니다.

  • 이전 버전과 호환되지 않는 API 변경 시 메이저 버전 증가

  • 이전 버전과 호환되는 방식으로 기능을 추가할 때 마이너 버전이 증가합니다.

  • 기능에 영향을 주지 않는 사소한 추가를 수행하면 패치 버전이 증가합니다.

Matter 클러스터에서 파생된 기능은 버전 1.4에서 기준이 지정되며 각 Matter 릴리스는 시스템으로 가져올 것으로 예상됩니다. Matter 버전은 메이저 및 마이너 수준의 셈버를 모두 사용하므로 관리형 통합은 패치 버전만 사용할 수 있습니다.

Matter에 대한 패치 버전을 추가할 때는 해당 Matter가 순차 개정을 사용한다는 점을 고려해야 합니다. 모든 PATCH 버전은 Matter 사양에 설명된 개정을 준수해야 하며 이전 버전과 호환되어야 합니다.

이전 버전과 호환되지 않는 문제를 해결하려면 Connectivity Standards Alliance(CSA)와 협력하여 사양의 문제를 해결하고 새 개정을 릴리스해야 합니다.

AWS관리형 기능은의 초기 버전과 함께 릴리스되었습니다1.0. 이를 통해 세 가지 수준의 버전을 모두 사용할 수 있습니다.

extrinsicVersion(필수)

시스템 외부에서 관리되는 버전을 나타내는 문자열입니다 AWS IoT . Matter 기능의 경우는에 extrinsicVersion 매핑됩니다. revision

문자열화된 정수 값으로 표시되며 길이는 1~10자리 숫자일 수 있습니다.

예제 버전
7
1567

extrinsicId(필수)

extrinsicId 요소는 Amazon Web Services IoT 시스템 외부에서 관리되는 식별자를 나타냅니다. Matter 기능의 경우 컨텍스트에 따라 clusterId, fieldId, attributeIdcommandIdeventId, 또는에 매핑됩니다.

는 문자열화된 10진수 정수(1~10자리) 또는 문자열화된 16진수 정수(0x 또는 0X 접두사 뒤에 1~8자리 16진수)일 extrinsicId 수 있습니다.

참고

AWS의 경우 공급업체 ID(VID)는 0x1577이고 Matter의 경우 0입니다. 시스템은 사용자 지정 스키마가 이러한 예약된 VIDs 기능에 사용하지 않도록 합니다.

예 extrinsicIds 예제
0018
0x001A
0x15771002

$defs

$defs 섹션은 JSON 스키마에서 허용하는 스키마 문서 내에서 참조할 수 있는 하위 스키마의 맵입니다. 이 맵에서 키는 로컬 참조 정의에 사용되며 값은 JSON 스키마를 제공합니다.

참고

시스템은 $defs 유효한 맵이고 각 하위 스키마가 유효한 JSON 스키마인 만 적용합니다. 추가 규칙은 적용되지 않습니다.

정의 작업 시 다음 제약 조건을 따릅니다.

  • 정의 이름에 URI 친화적 문자만 사용

  • 각 값이 유효한 하위 스키마인지 확인

  • 스키마 문서 크기 제한에 맞는 하위 스키마 수를 포함합니다.

extrinsicProperties

extrinsicProperties 요소에는 외부 시스템에 정의되어 있지만 데이터 모델 내에서 유지되는 속성 세트가 포함되어 있습니다. Matter 기능의 경우 ZCL 클러스터, 속성, 명령 또는 이벤트 내에서 모델링되지 않았거나 부분적으로 모델링된 다양한 요소에 매핑됩니다.

외부 속성은 다음 제약 조건을 따라야 합니다.

  • 속성 이름은 공백이나 특수 문자 없이 영숫자여야 합니다.

  • 속성 값은 모든 JSON 스키마 값일 수 있습니다.

  • 최대 20개의 속성

시스템은 extrinsicProperties, , access, 등 다양한 apiMaturityclicliFunctionName를 지원합니다. 이러한 속성은 ACL에서 데이터 모델로의 변환 AWS (및 그 반대)을 용이하게 합니다.

참고

외부 속성은 기능의 action, eventproperty, 및 struct 필드 요소에 대해 지원되지만 기능 또는 클러스터 자체에는 지원되지 않습니다.

속성

속성은 디바이스 관리형 기능 상태를 나타냅니다. 각 상태는 키-값 페어로 정의되며, 여기서 키는 상태 이름을 설명하고 값은 상태 정의를 설명합니다.

속성을 사용할 때는 다음 제약 조건을 따르세요.

  • 속성 이름에는 공백이나 특수 문자 없이 영숫자만 사용

  • 스키마 문서 크기 제한에 맞는 모든 수의 속성을 포함합니다.

속성 작업

기능 내의 속성은 관리형 통합으로 구동되는 디바이스의 특정 상태를 나타내는 기본 요소입니다. 디바이스의 현재 조건 또는 구성을 나타냅니다. 스마트 홈 시스템은 이러한 속성이 정의되고 구조화되는 방식을 표준화하여 다양한 제조업체의 디바이스가 효과적으로 통신할 수 있도록 하여 원활하고 상호 운용 가능한 경험을 제공합니다.

기능 속성의 경우 필수 요소는 extrinsicId 및 입니다value. 기능 속성의 선택적 요소는 description, retrievable, 및 mutable reportable 입니다extrinsicProperties.

값

빌더가 JSON 스키마 준수 제약 조건을 적용하여이 속성의 데이터 유형을 정의할 수 있는 무제한 구조입니다.

값을 정의할 때 다음 제약 조건을 따릅니다.

  • 간단한 유형의 경우 type 및 maxLength 또는와 같은 기타 기본 JSON 스키마 제약 조건을 사용합니다. maximum

  • 복합 유형의 경우 , 또는 oneOfallOf를 사용합니다anyOf. 시스템에서 not 키워드를 지원하지 않습니다.

  • 모든 글로벌 유형을 참조하려면 유효한 검색 가능한 참조와 $ref 함께를 사용하세요.

  • null 가능성의 경우 부울 플래그와 함께 null 가능한 속성을 제공하여 OpenAPI 유형 스키마 정의를 따릅니다(truenull이 허용되는 값인 경우).

예시

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

검색 가능

상태를 읽을 수 있는지 여부를 설명하는 부울입니다.

상태의 가독성 측면은 디바이스의 기능 구현으로 연기됩니다. 디바이스는 지정된 상태를 읽을 수 있는지 여부를 결정합니다. 상태의이 측면은 아직 기능 보고서에서 보고하도록 지원되지 않으므로 시스템 내에서 적용되지 않습니다.

예: true 또는 false

Mutable

상태가 쓰기 가능한지 여부를 설명하는 부울입니다.

상태의 쓰기 가능성 측면은 디바이스의 기능 구현으로 연기됩니다. 디바이스는 지정된 상태가 쓰기 가능한지 여부를 결정합니다. 상태의이 측면은 아직 기능 보고서에서 보고하도록 지원되지 않으므로 시스템 내에서 적용되지 않습니다.

예: true 또는 false

보고 가능

상태가 변경될 때 디바이스에서 상태를 보고하는지 여부를 설명하는 부울입니다.

상태의 보고 가능성 측면은 디바이스의 기능 구현으로 연기됩니다. 디바이스는 지정된 상태가 보고 가능한지 여부를 결정합니다. 상태의이 측면은 아직 기능 보고서에서 보고하도록 지원되지 않으므로 시스템 내에서 적용되지 않습니다.

예: true 또는 false

작업

작업은 요청-응답 모델을 따르는 스키마 관리형 작업입니다. 각 작업은 디바이스 구현 작업을 나타냅니다.

작업을 구현할 때 다음 제약 조건을 따릅니다.

  • 작업 배열에 고유한 작업만 포함

  • 스키마 문서 크기 제한에 맞는 모든 수의 작업을 포함합니다.

작업

작업은 관리형 통합 시스템에서 디바이스 기능과 상호 작용하고 제어하기 위한 표준화된 방법입니다. 필요한 요청 또는 응답 파라미터를 모델링하기 위해 구조화된 형식으로 완성된 디바이스에서 실행할 수 있는 특정 명령 또는 작업을 나타냅니다. 이러한 작업은 사용자 의도와 디바이스 작업 간의 연결 역할을 하여 다양한 유형의 스마트 디바이스에서 일관되고 신뢰할 수 있는 제어를 가능하게 합니다.

작업의 경우 필수 요소는 name 및 입니다extrinsicId. 선택적 요소는 description, extrinsicProperties request 및 입니다response.

설명

설명의 최대 길이 제약 조건은 1536자입니다.

요청

요청 섹션은 선택 사항이며 요청 파라미터가 없는 경우 생략할 수 있습니다. 생략하면의 이름만 사용하여 페이로드 없이 요청을 보낼 수 있습니다Action. 이는 조명 켜기 또는 끄기와 같은 간단한 작업에 사용됩니다.

복잡한 작업에는 추가 파라미터가 필요합니다. 예를 들어 카메라 영상 스트리밍 요청에는 사용할 스트리밍 프로토콜 또는 스트림을 특정 디스플레이 디바이스로 전송할지 여부에 대한 파라미터가 포함될 수 있습니다.

작업 요청의 경우 필수 요소는 입니다parameters. 선택적 요소는 description, extrinsicId및 입니다extrinsicProperties.

요청 설명

설명은 섹션 3.5와 동일한 형식을 따르며 최대 길이는 2,048자입니다.

응답

관리형 통합에서는 SendManagedThingCommand API를 통해 전송된 모든 작업 요청에 대해 요청이 디바이스에 도달하고 비동기 응답이 다시 발생할 것으로 예상합니다. 작업 응답은이 응답의 구조를 정의합니다.

작업 요청의 경우 필수 요소는 입니다parameters. 선택적 요소는 name, description, extrinsicId, 및 extrinsicProperties errors 입니다responseCode.

응답 설명

설명은와 동일한 형식을 따르며 최대 길이는 2설명,048자입니다.

응답 이름

이름은 다음과 같은 추가 세부 정보와 이름(필수)함께와 동일한 형식을 따릅니다.

  • 응답의 기존 이름은 작업 이름Response에를 추가하여 파생됩니다.

  • 다른 이름을 사용하려면이 name 요소에 제공할 수 있습니다. 응답에 name이 제공된 경우이 값은 기존 이름보다 우선합니다.

오류

요청을 처리하는 동안 오류가 있는 경우 응답에 제공된 고유한 메시지의 무한 배열입니다.

제약 조건:

  • 메시지 항목은 다음 필드가 있는 JSON 객체로 선언됩니다.

    • code: 1~64자 길이의 영숫자 및 _ (밑줄)을 포함하는 문자열

    • message: 무한 문자열 값

예 오류 메시지 예제
"errors": [
   {  
      "code": "AD_001", 
      "message": "Unable to receive signal from the sensor. Please check connection with the sensor." 
   }
]

응답 코드

요청이 처리된 방식을 보여주는 정수 코드입니다. 시스템 내에서 균일성을 허용하려면 디바이스 코드가 HTTP 서버 응답 상태 코드 사양을 사용하여 코드를 반환하는 것이 좋습니다.

제약 조건: 100~599 범위의 정수 값입니다.

요청 또는 응답 파라미터

파라미터 섹션은 이름 및 하위 스키마 페어의 맵으로 정의됩니다. 스키마 문서에 적합할 수 있는 경우 요청 파라미터 내에 원하는 수의 파라미터를 정의할 수 있습니다.

파라미터 이름에는 영숫자만 사용할 수 있습니다. 공백 또는 기타 문자는 허용되지 않습니다.

파라미터 필드

의 필수 요소는 extrinsicId 및 parameter입니다value. 선택적 요소는 description 및 입니다extrinsicProperties.

설명 요소는와 동일한 형식을 따르며 최대 길이는 1설명,024자입니다.

extrinsicId 및 extrinsicProperties 재정의

extrinsicId 및는 이러한 추가 세부 정보와 함께 extrinsicId(필수) 및 extrinsicProperties와 동일한 형식을 extrinsicProperties 따릅니다.

  • 요청 또는 응답에 extrinsicId이 제공된 경우이 값은 작업 수준에서 제공된 값보다 우선합니다. 시스템은 extrinsicId 먼저 요청/응답 수준을 사용해야 하며, 누락된 경우 작업 수준을 사용해야 합니다. extrinsicId

  • 요청 또는 응답에 extrinsicProperties가 제공된 경우 이러한 속성은 작업 수준에서 제공된 va 값보다 우선합니다. 시스템은 작업 수준을 extrinsicProperties 취하고 요청/응답 수준에서 제공된 키-값 페어를 교체해야 합니다. extrinsicProperties

예 extrinsicId 및 extrinsicProperties 재정의 예제
{
   "name": "ToggleWithEffect",
   "extrinsicId": "0x0001",
  
   "extrinsicProperties": {
      "apiMaturity": "provisional",
      "introducedIn": "1.2"
   },
   "request": {
      "extrinsicProperties": {
         "apiMaturity": "stable",
         "manufacturerCode": "XYZ"
      },
      "parameters": {
         ...
      }
   },
   "response": {
      "extrinsicProperties": {
         "noDefaultImplementation": true
      },
      "parameters": {
 {
         ...
      }
   }
}

위 예제에서 작업 요청의 유효 값은 다음과 같습니다.

# 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": {
   ...
}

기본 제공 작업

모든 기능에 대해 키워드 ReadState 및를 사용하여 사용자 지정 작업을 수행할 수 있습니다UpdateState. 이 두 작업 키워드는 데이터 모델에 정의된 기능의 속성에 따라 작동합니다.

ReadState

에 명령을 전송managedThing하여 상태 속성의 값을 읽습니다. 디바이스 상태를 강제ReadState로 업데이트하는 방법으로를 사용합니다.

UpdateState

일부 속성을 업데이트하는 명령을 보냅니다.

디바이스 상태 동기화를 강제 적용하면 다음 시나리오에서 유용할 수 있습니다.

  1. 디바이스가 일정 기간 오프라인 상태였고 이벤트를 내보내지 않았습니다.

  2. 디바이스가 방금 프로비저닝되었으며 아직 클라우드에서 유지 관리되는 상태가 없습니다.

  3. 디바이스 상태가 디바이스의 실제 상태와 동기화되지 않았습니다.

ReadState 예제

SendManagedThingCommand API를 사용하여 조명이 켜져 있는지 또는 꺼져 있는지 확인합니다.

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

matter.OnOff 기능에 대한 모든 상태 속성을 읽습니다.

{
  "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 예제

SendManagedThingCommand APIOnTime를 사용하여 조명의를 변경합니다.

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

이벤트

이벤트는 디바이스에서 구현한 스키마 관리형 단방향 신호입니다.

다음 제약 조건에 따라 이벤트를 구현합니다.

  • 이벤트 배열에 고유한 이벤트만 포함

  • 스키마 문서 크기 제한에 맞는 이벤트 수를 포함합니다.