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는 2개의 공백으로 들여쓰기되어 키 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 구조체를 살펴보세요.
| 키 | 유형 | 설명 |
|---|---|---|
|
|
선택사항입니다. 자동화 이름입니다. 이는 사용자에게 표시되지 않으며 개발자 참조용입니다. |
|
|
|
[시작] |
필수 항목입니다. 시작 조건 목록입니다. |
|
|
선택사항입니다. 조건 |
|
|
|
[작업] |
필수 항목입니다. 작업 목록입니다. |
참조 섹션에서는 사용 가능한 모든 구조체의 스키마 정의를 제공합니다.
키 이름은 지정된 구조체 내에서 고유하며 대소문자를 구분합니다.
가능한 값 유형은 다음과 같습니다.
- 기본 유형: 불리언, 숫자, 문자열, 시간 등
- 구조체 유형: 필드 모음입니다.
- 데이터 유형의 배열입니다. 배열은
[]로 표시됩니다. 예를 들어[string]는 문자열 배열이고[Starter]는 시작 구조체 배열입니다. - 기타 특수 유형: Entity, FieldPath
각 필드의 설명에는 다음과 같은 중요한 정보가 포함되어 있습니다.
- 필수 여부: 필수 입력란인지 아니면 건너뛸 수 있는 입력란인지를 나타냅니다.
- 필드 종속 항목 선택 필드에만 종속 항목이 있습니다. 여기에는 필드 A가 설정된 경우에만 필드 B 사용 또는 필드 A가 사용될 때 필드 B 또는 필드 C를 설정하지 않음과 같이 이 필드를 사용할 때의 추가 검사가 설명됩니다.
- 가능한 값 예를 들어 문자열 유형의 Enum 필드의 제한된 값 집합이나 숫자 유형의 필드에 사용할 수 있는 숫자 범위가 여기에 해당합니다.
유형이 지정된 구조체
일부 구조체는 시간 일정 또는 기기 상태 변경에 따라 시작 조건을 나타낼 수 있습니다. 각 유형의 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은 type 필드의 다른 하위 구조체(예: time.schedule 또는 device.state.OnOff)에 의해 확장되어 다양한 함수를 제공하는 유형 지정된 구조체입니다. condition 및 action 구조체도 유형이 지정됩니다.
구조체의 추가 필드는 하위 구조체 (type) 사양을 따라야 합니다. 예를 들어 device.state.OnOff를 type로 사용하는 경우해당 유형에 지정된 필드
만 해당 starter 구조체에서 유효합니다.
배열
YAML에서 값 배열은 - (대시 뒤에 공백)로 시작합니다. 배열은 여러 개의 구조체 값 또는 여러 개의 기본 값을 보유할 수 있습니다. 하지만 배열의 값은 동일한 유형이어야 합니다.
배열에 항목이 하나만 포함된 경우 대시와 공백을 생략할 수 있습니다.
# 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, 2, 3, 4])로 자동으로 평면화합니다.
# INVALID: multi-dimensional array
- - 1
- 2
- - 3
- 4
기본 역할
자동화 스크립트 스키마에서 지원되는 원시 데이터 유형은 다음과 같습니다.
|
부울 |
|
|
숫자 |
정수 또는 소수입니다. |
|
문자열 |
일반 텍스트 특정 사례를 제외하고 문자열은 따옴표로 묶을 필요가 없습니다. |
|
날짜 |
월 및 일입니다. 형식은 MM-DD 또는 MM/DD입니다.
|
|
시간 |
시간입니다. 시계 시간 또는 일광 절약 시간일 수 있습니다.
시계 시간의 경우 AM/PM 형식 또는 24H 형식 중 하나를 사용할 수 있습니다. 초는 선택사항입니다.
일광 절약 시간의 경우
|
|
일시 |
연도, 월, 일, 시간입니다. 날짜 부분과 시간 부분 사이에는 공백이 있어야 합니다. 날짜 형식은 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
다른 FieldPaths의 경우 필수 항목에 도달하기 위해 여러 수준이 필요할 수 있으며, 시작 조건과 작업 간에 형식이 다릅니다.
시작 조건은 점 표기법을 사용하며 전체 경로가 동일한 필드에 있습니다. 이는 주로 시작 로직에서 비교 목적으로 수행됩니다. 예를 들어 색온도를 시작 조건으로 사용하려면 상태에 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