言語の基礎

YAML を理解する

YAML は、ソフトウェア構成の指定に使用される一般的な言語です。構造化された情報を、人が読める形式でわかりやすく表現します。ここでは、スクリプトによる自動化を初めて作成する前に、YAML について理解しておく必要がある基本的な事項について説明します。YAML 全般の詳細については、バージョン 1.1 の仕様をご覧ください。

Key-Value ペア

YAML ドキュメントは基本的に Key-Value ペアのコレクションです。次の例では、キーは name、値は TV on lights off です。キーと値は、コロンの後にスペースで区切ります。正しい形式の YAML には両方の文字が必要です。

name: TV on lights off

Values

キーに関連付ける値は、文字列、数値、日付など基本的なものから、別の Key-Value ペアのコレクションのような複雑なものまで、さまざまです。

文字列

文字列値が [、{、"、'、# のいずれかで始まる場合、または文字列に :（コロンの後にスペースが続く）が含まれている場合は、引用符で囲む必要があります。

一重引用符と二重引用符の両方を使用できますが、終了引用符は開始引用符と一致する必要があります。

正しい引用:

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"

ネストされた Key-Value ペア

ここで、キー metadata の値は、2 つの Key-Value ペア（name と description）からなるリストです。

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

インデント

YAML ではインデントを使用して構造を示します。上記の例では、name と description が（2 つのスペースで）インデントされて、これらがキー metadata の子であることを示します。

YAML のインデントは厳格です。子構造体のインデントは親よりも深くする必要があります。また、同じレベルの Key-Value ペアのインデントも同じにする必要があります。

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

複数の値

特定のキーに複数の値がある場合、各値は新しい行にリストされ、各行の先頭にダッシュ 1 個とスペース 1 個が付きます。次の例では 2 つのリストがあります。

  1. 自動化には複数の starters を含めることができるため、最初の開始条件はダッシュとスペースで始まります。
  2. weekday には複数の値を指定できます。各値をさらにインデントし、先頭にダッシュ 1 個とスペース 1 個を追加します。
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.

自動化スクリプト

Automations スクリプト構文の仕様は、スキーマと呼ばれます。

Automations スキーマは、2 つのデータ構造を定義します。

  • 1 つの Key-Value ペアをフィールドと呼びます。
  • スキーマによって定義されるフィールドの集合は構造体と呼ばれます。

構造体

自動化スクリプト言語では、構造体と呼ばれる標準の「ブロック」またはデータ構造がいくつか定義されます。

4 つのフィールドを定義する automation 構造体を見てみましょう。

キー タイプ 説明

name

文字列

省略可。

自動化の名前。

これはユーザーには表示されません。デベロッパーの参照用です。

starters

[開始条件]

必須。

開始条件のリスト。

condition

条件

省略可。

状態。

actions

[アクション]

必須。

アクションのリスト。

リファレンス セクションには、使用可能なすべての構造体のスキーマ定義が記載されています。

キー名は特定の構造体内で一意であり、大文字と小文字が区別されます。

有効な値の型は次のとおりです。

  • プリミティブ型: bool、number、string、time など。
  • 構造体型: フィールドのコレクション。
  • データ型の配列。配列は [] で表されます。たとえば、[string] は文字列の配列で、[Starter] は Starter 構造体の配列です。
  • その他の特殊なタイプ: Entity、FieldPath

各フィールドの説明には、次のような重要な情報が含まれています。

  • 必須と省略可。フィールドが必須かスキップ可能かを示します。
  • フィールドの依存関係。オプションのフィールドにのみ依存関係があります。ここでは、「フィールド A が設定されている場合にのみフィールド B を使用する」や「フィールド A を使用する場合は、フィールド B やフィールド C を設定しない」など、このフィールドを使用する際の追加チェックについて説明します。
  • 有効な値。たとえば、string 型の列挙型フィールドの制限値セットや、number 型の Field で使用できる数値の範囲などです。

型付き構造体

一部の構造体は、タイム スケジュールやデバイスの状態の変化に基づいて開始条件を表すことができます。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 では、値の配列は -（ダッシュの後にスペースが続く）で始まります。配列は複数の 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, 2, 3, 4]）にフラット化します。

# INVALID: multi-dimensional array
- - 1
  - 2
- - 3
  - 4

基本ロール

Automations スクリプト スキーマでは、次のプリミティブ データ型がサポートされています。

Bool
  • true
  • false

Number

整数または 10 進数

文字列

書式なしテキスト

特定のケースを除き、文字列を引用符で囲む必要はありません。

日付

月と日。形式は MM-DD または MM/DD です。

  • 09/01
  • 09-01

時間

時間帯。時刻または太陽時刻のいずれかを指定できます。 時刻には、AM/PM 形式または 24 時間形式のいずれかを使用できます。秒は省略可能です。太陽光の場合は、sunrise と sunset がキーワードで、その後にオフセットが続く場合があります（期間単位）。

  • 12:30 am
  • 13:00:01
  • sunrise / sunset
  • sunset+30min / sunset-1hour

DateTime

年、月、日、時刻。日付部分と時刻部分の間には空白が必要です。日付の形式は YYYY-MM-DD または YYYY/MM/DD です。時刻の形式は [Time](#time) と同じです。タイムゾーンはサポートされていません。

  • 2022/01/01 14:00
  • 2022-12-31 sunrise+30min

曜日

  • MONDAY（または MON）
  • TUESDAY（または TUE）
  • WEDNESDAY（または WED）
  • THURSDAY（または THU）
  • FRIDAY（または FRI）
  • SATURDAY（または SAT）
  • SUNDAY（または SUN）

所要時間

一定の期間。

  • 30min
  • 1hour
  • 20sec
  • 1hour10min20sec
ColorHex

色を表す 6 桁の 16 進数コード。

先頭に # はありません。

  • FFFFFF
  • B5D2A1
  • DFA100
Temperature

通常の体温データ。温度測定を示す場合は、必ず値に 'C' または 'F' を追加します。

  • 20.5C
  • 90F
ColorTemperature

色温度（ケルビン単位）。

  • 5000K

色

色は、ColorHex または ColorTemperature プリミティブ型か、複合型 SpectrumHSV のいずれかを使用して、3 つの方法のいずれかで指定できます。

SpectrumHSV

SpectrumHSV 型は、次の 3 つの数値フィールドを使用して色を指定します。

  • Hue は色の波長に対応します。
  • 彩度は、色の強さを示します。
  • 値は、色の相対的な明度または暗さを示します。

ダイナミック

鍵のデータ型が固定されていない場合があります。他のフィールドの値に基づくプリミティブ型のいずれかになります。

動的データ型フィールドの例は 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