언어 기본사항

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의 하위 요소임을 나타내기 위해 들여쓰기 (공백 2개)되어 있습니다.

YAML에서는 들여쓰기가 엄격합니다. 하위 구조는 상위 구조보다 들여쓰기가 더 깊어야 하며 동일한 수준의 키-값 쌍은 들여쓰기가 동일해야 합니다.

metadata:
  name:
    en: TV on lights off
  description:
    en: Turn off lights when TV turns on

여러 개의 값

지정된 키에 값이 여러 개 있는 경우 각 값은 새 줄에 나열되며 각 줄은 대시와 공백으로 시작됩니다. 다음 예에는 두 개의 목록이 있습니다.

1. 자동화에는 starters가 여러 개 있을 수 있으므로 첫 번째 시작 조건은 대시와 공백으로 시작합니다.
2. 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.

자동화 스크립트

자동화 스크립트 문법 사양을 스키마라고 합니다.

자동화 스키마는 다음과 같은 몇 가지 데이터 구조를 정의합니다.

• 단일 키-값 쌍을 필드라고 합니다.
• 스키마에 의해 정의된 필드 모음을 구조체라고 합니다.

구조체

자동화 스크립트 언어는 구조체라고 하는 여러 표준 '블록' 또는 데이터 구조를 정의합니다.

네 개의 필드를 정의하는 automation 구조체를 살펴보세요.

참조 섹션에서는 사용 가능한 모든 구조체의 스키마 정의를 제공합니다.

키 이름은 지정된 구조체 내에서 고유하며 대소문자를 구분합니다.

가능한 값 유형은 다음과 같습니다.

• 기본 유형: bool, number, string, time 등
• 구조체 유형: 필드 모음입니다.
• 데이터 유형의 배열입니다. 배열은 []로 표시됩니다. 예를 들어 [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은 time.schedule 또는 device.state.OnOff과 같은 type 필드의 다른 하위 구조체에 의해 확장되어 다양한 기능을 제공하는 유형이 지정된 구조체입니다. 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

기본 역할

자동화 스크립트 스키마에서 지원되는 원시 데이터 유형은 다음과 같습니다.

색상

색상은 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