言語の基礎

YAML について

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

Key-Value ペア

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

name: TV on lights off

値

キーに関連付ける値は、文字列、数値、日付などの基本的な値にすることも、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 ではインデントが厳密です。子構造は親よりもインデントを深くする必要があります。同じレベルのキー値ペアは同じインデントを設定する必要があります。

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

複数の値

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

  1. 自動化には複数の starters を指定できます。最初の開始条件の先頭にはダッシュ 1 個とスペース 1 個を追加します。
  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 スキーマでは、次の 2 つのデータ構造が定義されています。

  • 1 つの Key-Value ペアをフィールドと呼びます。
  • スキーマで定義されたフィールドのコレクションを構造体と呼びます。

構造体

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

automation 構造体を見てみましょう。この構造体には 4 つのフィールドが定義されています。

キー タイプ 説明

name

String

省略可。

自動化の名前。

これはユーザーには表示されず、デベロッパーの参照専用です。

starters

[開始]

必須。

開始条件のリスト。

condition

条件

省略可。

状態。

actions

[アクション]

必須。

アクションのリスト。

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

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

使用できる値の型は次のとおりです。

  • プリミティブ型: bool、number、string、time など。
  • 構造体型: フィールドの集合。
  • データ型の配列。配列は [] で表されます。たとえば、[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 は型付き構造体で、type フィールド内の他の子構造体（time.schedule や device.state.OnOff など）によって拡張され、さまざまな機能を提供します。condition 構造体と action 構造体も型指定されています。

構造体の追加フィールドは、子構造体（type）の仕様に従っている必要があります。たとえば、type として device.state.OnOff を使用する場合、その starter 構造体で有効なのは、その型に指定されたフィールド のみです。

配列

YAML では、値の配列は -（ダッシュとスペース）で始まります。配列には、複数の構造体値または複数のプリミティブ値を格納できます。ただし、配列内の値は同じ型にする必要があります。

配列に 1 つのアイテムが含まれている場合は、ダッシュとスペースを省略できます。

# 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

基本ロール

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

Bool
  • true
  • false

数値

整数または 10 進数

文字列

書式なしテキスト

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

日付

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

  • 09/01
  • 09-01

時間

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

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

DateTime

年、月、日、時刻。日付の部分と時刻の部分の間には空白文字が必要です。日付の形式は、YYYY-MM-DD または YYYY/MM/DD です。 時刻の形式は [時刻](#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
温度

正常な温度データ。温度測定を表すには、必ず値に 'C' または 'F' を追加します。

  • 20.5C
  • 90F
ColorTemperature

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

  • 5000K

色

色は、ColorHex または ColorTemperature プリミティブ タイプ、または複合型 SpectrumHSV のいずれかの方法で指定できます。

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