YAML 이해
YAML은 소프트웨어 구성을 지정하는 데 널리 사용되는 언어입니다. 구조화된 정보를 명확하고 사람이 읽을 수 있는 방식으로 나타낼 수 있습니다. 다음은 첫 번째 자동화 스크립트를 만들기 전에 YAML에 대해 알아야 할 몇 가지 기본 사항입니다. YAML에 대한 일반적인 내용은 버전 1.1 사양을 참조하세요.
키-값 쌍
YAML 문서는 기본적으로 키-값 쌍의 모음입니다. 다음 예에서 키는 name이고 값은 TV on lights off입니다. 키와 값은 콜론으로 구분되고 그 뒤에 공백이 옵니다. 두 문자 모두 올바른 형식의 YAML에 필요합니다.
name: TV on lights off
값
키와 연결된 값은 문자열, 숫자, 날짜와 같은 기본 형식일 수도 있고 키-값 쌍의 다른 컬렉션처럼 복잡할 수도 있습니다.
문자열
문자열 값이 [, {, ", ', # 중 하나로 시작하거나 문자열에 : (콜론 뒤에 공백이 나타남)를 포함할 경우 따옴표로 묶어야 합니다.
작은따옴표와 큰따옴표 모두 허용되지만 닫는 따옴표는 여는 따옴표와 일치해야 합니다.
올바른 인용 사용:
name: 'TV on lights off'
name: "TV on lights off"
잘못된 인용문 (따옴표 불일치):
name: 'TV on lights off"
따옴표는 다른 모든 유형의 문자열에서 선택사항입니다.
여러 줄 문자열이 필요한 경우 여러 줄 스칼라에 대한 YAML 사양 섹션을 참조하세요.
name: "[1] TV"
name: '{1} TV'
name: '#TV'
name: '"1" TV'
name: "'1' TV"
name: "\"1\" TV"
name: "TV: bedroom"
중첩된 키-값 쌍
여기서 metadata 키 값은 두 개의 키-값 쌍 (name 및 description) 목록입니다.
metadata:
name: TV on lights off
description: Turn off lights when TV turns on
들여쓰기
YAML은 들여쓰기를 사용하여 구조를 나타냅니다. 앞의 예에서 name와 description는 두 개의 공백으로 들여쓰기되어 metadata 키의 하위 요소임을 나타냅니다.
YAML에서는 들여쓰기가 엄격합니다. 하위 구조는 상위 구조보다 더 깊은 들여쓰기를 해야 하고, 같은 수준의 키-값 쌍은 동일한 들여쓰기를 가져야 합니다.
metadata:
name:
en: TV on lights off
description:
en: Turn off lights when TV turns on
여러 값
지정된 키에 여러 값이 있으면 각 값이 새 줄에 나열되며 각 줄은 대시와 공백이 옵니다. 다음 예에는 두 개의 목록이 있습니다.
- 자동화에는 여러
starters가 있을 수 있으므로 첫 번째 시작 조건은 대시와 공백으로 시작합니다. weekday는 여러 값을 가질 수 있으므로 각 값은 더 들여쓰기되며 대시와 공백으로 시작됩니다.
starters:
- type: time.schedule
at: SUNSET
weekday:
- MONDAY
- THURSDAY
state: on
설명
# 다음에 오는 텍스트는 주석으로 간주되며 자동화 엔진에서 무시됩니다.
#로 시작하는 줄이 주석입니다.
주석은 스크립트 콘텐츠와 같은 줄에 나타날 수 있지만 # 앞에 공백이 있어야 합니다.
# This is a comment. It will be ignored.
name: chromecast #This is a TV.
자동화 스크립트
자동화 스크립트 구문의 사양을 스키마라고 합니다.
자동화 스키마는 몇 가지 데이터 구조를 정의합니다.
- 단일 키-값 쌍을 필드라고 합니다.
- 스키마로 정의된 필드 모음을 구조체라고 합니다.
구조체
자동화 스크립팅 언어는 구조체라고 하는 여러 표준 '블록' 또는 데이터 구조를 정의합니다.
4개의 필드를 정의하는 automation 구조체를 살펴보세요.
| 키 | 유형 | 설명 |
|---|---|---|
|
|
선택사항입니다. 자동화의 이름입니다. 이 정보는 개발자에게 표시되지 않으며 개발자 참고용입니다. |
|
|
|
[시작 조건] |
필수 항목입니다. 시작 조건 목록입니다. |
|
|
선택사항입니다. 조건 |
|
|
|
[작업] |
필수 항목입니다. 작업 목록입니다. |
참조 섹션에서는 사용 가능한 모든 Structs의 스키마 정의를 제공합니다.
키 이름은 특정 Struct 내에서 고유하며 대소문자를 구분합니다.
가능한 값 유형은 다음과 같습니다.
- 기본 유형: 부울, 숫자, 문자열, 시간 등
- 구조체 유형: 필드 모음입니다.
- 데이터 유형의 배열입니다. 배열은
[]로 표시됩니다. 예를 들어[string]는 문자열 배열이고[Starter]는 시작 구조체의 배열입니다. - 기타 특수 유형: Entity, FieldPath
각 필드의 설명에는 다음과 같은 중요한 정보가 포함되어 있습니다.
- 필수 또는 선택사항으로, 필드가 필수인지 또는 건너뛸 수 있는지 여부를 나타냅니다.
- 필드 종속 항목 선택적 필드에만 종속 항목이 있습니다. 여기에서는 필드 A가 설정된 경우에만 필드 B를 사용합니다 또는 필드 A를 사용할 때 필드 B나 필드 C를 설정하지 마세요와 같이 이 필드를 사용할 때의 추가 검사를 설명합니다.
- 가능한 값입니다. 예를 들어 문자열 유형의 열거형 필드의 제한된 값 집합 또는 숫자 유형의 필드에 사용할 수 있는 숫자 범위가 있습니다.
유형이 있는 구조체
일부 구조체는 시간 일정 또는 기기 상태 변경을 기반으로 시작 조건을 나타낼 수 있습니다. 각 starter 유형은 고유한 필드 집합을 제공해야 합니다.
# A time schedule starter.
starter:
type: time.schedule
at: 10:00
# A device state change starter.
starter:
type: device.state.OnOff
device: TV - Living Room
state: on
is: true
starter는 유형이 있는 구조체로, time.schedule 또는 device.state.OnOff와 같은 type 필드의 다른 하위 구조체에 의해 확장되어 다양한 함수를 제공합니다. condition 및 action 구조체도 유형이 지정됩니다.
Struct의 추가 필드는 하위 Struct (type) 사양을 따라야 합니다. 예를 들어 device.state.OnOff를 type로 사용할 경우유형에 지정된 필드
만 starter 구조체에 유효합니다.
배열
YAML에서 값 배열은 - (대시 다음에 공백이 붙음)로 시작합니다. 배열은 여러 Struct 값 또는 여러 Primitive 값을 보유할 수 있습니다. 그러나 배열의 값은 동일한 유형이어야 합니다.
배열에 단일 항목이 포함된 경우 대시와 공백을 생략할 수 있습니다.
# The starters field accepts an array of Starter Structs.
# This is the standard format.
starters:
- type: time.schedule
at: sunset
- type: time.schedule
at: sunrise
# The dash can be omitted if the array only has one item.
# This is also valid.
starters:
type: time.schedule
at: sunset
다차원 배열(예: [[1, 2], [3, 4]])은 자동화 스크립팅에서 지원되지 않습니다. 언어 파서는 다차원 배열을 1차원 배열(이 경우 [1, 2, 3, 4])로 자동 평면화합니다.
# INVALID: multi-dimensional array
- - 1
- 2
- - 3
- 4
기본 역할
다음 기본 데이터 유형은 자동화 스크립트 스키마에서 지원됩니다.
|
부울 |
|
|
숫자 |
정수 또는 십진수 |
|
문자열 |
일반 텍스트 특정 사례를 제외하고는 문자열을 따옴표로 묶지 않아도 됩니다. |
|
날짜 |
월과 일입니다. 형식은 MM-DD 또는 MM/DD입니다.
|
|
시간 |
시간 시계 시간 또는 태양 시간일 수 있습니다.
시계 시간의 경우 AM/PM 형식 또는 24H 형식을 사용할 수 있습니다. 초는 선택사항입니다.
태양 시간의 경우
|
|
DateTime |
연도, 월, 일, 시간입니다. 날짜 부분과 시간 부분 사이에는 공백이 필요합니다. 날짜 형식은 YYYY-MM-DD 또는 YYYY/MM/DD입니다. 시간 형식은 [시간](#time)과 동일합니다. 지원되지 않는 시간대입니다.
|
|
요일 |
|
|
시간 |
일정 기간입니다.
|
| ColorHex |
색상을 나타내는 6자리 16진수 코드입니다. 맨 앞에
|
| 온도 | 정상 온도 데이터입니다. 항상
|
| ColorTemperature |
색상 온도이며 단위는 켈빈(K)입니다.
|
색상
색상은 ColorHex 또는 ColorTemperature 기본 유형을 사용하거나 복합 유형 SpectrumHSV를 사용하여 세 가지 방법 중 하나로 지정할 수 있습니다.
SpectrumHSV
SpectrumHSV 유형은 세 개의 숫자 입력란을 사용하여 색상을 지정합니다.
- 색조는 색상 파장에 해당합니다.
- 채도는 색상의 강도를 나타냅니다.
- 값은 색상의 상대적 밝기 또는 어둡게를 나타냅니다.
동적
키의 데이터 유형이 고정되어 있지 않은 경우도 있습니다. 다른 필드의 값에 따라 기본 유형 중 하나일 수 있습니다.
동적 데이터 유형 입력란의 예는 is입니다. 실제 유형은 type 및 state 필드의 값에 따라 결정됩니다.
# The 'is' field accepts a number type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1
# The 'is' field accepts a boolean type.
type: device.state.OnOff
device: My TV - Living Room
state: on
is: false
항목
기기 또는 방과 같은 사용자 소유 항목을 고유하게 식별하는 특수 문자열 형식입니다.
기기는 자동화에 가장 일반적으로 사용되는 항목입니다. 항목 문자열 형식은 device name - room name입니다.
# The device field accepts a Device Entity type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1
FieldPath
데이터 페이로드에서 데이터 조각을 찾는 데 사용되는 특수 문자열 형식입니다. 다음 예에서 currentVolume는 state 필드의 FieldPath입니다.
# The state field accepts a FieldPath type.
starters:
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 5
다른 FieldPath의 경우 필수 항목에 도달하기 위해 여러 수준이 필요할 수 있으며 형식은 시작 조건과 작업마다 다릅니다.
시작 조건에서는 전체 경로가 같은 필드에 있는 점 표기법을 사용합니다. 이 작업은 주로 시작 로직에서 비교 목적으로 실행됩니다. 예를 들어 색온도를 시작 조건으로 사용하려면 상태에 color.colorTemperature를 사용하면 됩니다.
starters:
- type: device.state.ColorSetting
device: My Device - Room Name
state: color.colorTemperature
is: 2000K
하지만 작업은 중첩된 필드를 사용합니다. 전구의 색상을 color.name 및 is: blue 대신 파란색으로 변경하려면 다음을 실행해야 합니다.
actions:
- type: device.command.ColorAbsolute
devices: My Device - Room Name
color:
name: blue