言語の基礎

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 ではインデントが厳密に適用されます。子構造は親よりもインデントを深くする必要があり、同じレベルの Key-Value ペアは同じインデントにする必要があります。

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

複数の値

あるキーが複数の値を持つ場合、各値は新しい行にリストされ、各行の先頭にはダッシュ 1 個とスペース 1 個が付きます。次の例では、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.

自動化スクリプト

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

自動化スキーマは、いくつかのデータ構造を定義します。

• 1 つの Key-Value ペアはフィールドと呼ばれます。
• スキーマで定義されたフィールドのコレクションは、Struct と呼ばれます。

構造体

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

automation 構造体を確認します。この構造体は、次の 4 つのフィールドを定義します。

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

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

指定できる値の型は次のとおりです。

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

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

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

型付き構造体

一部の Struct は、スケジュールやデバイスの状態の変化に基づいて開始条件を表すことができます。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 は Typed Struct であり、type フィールドの他の子 Struct（time.schedule や device.state.OnOff など）によって拡張され、さまざまな機能を提供します。condition 構造体と action 構造体も型指定されています。

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

配列

YAML では、値の配列は -（ダッシュの後にスペース）で始まります。配列には、複数の Struct 値または複数の Primitive 値を保持できます。ただし、配列内の値は同じ型である必要があります。

配列に 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 次元配列（この場合は [1, 2, 3, 4]）に自動的にフラット化します。

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

基本ロール

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

色

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

SpectrumHSV

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

• 色相は色の波長に対応します。
• 彩度は色の鮮やかさを示します。
• 明度は、色の相対的な明るさまたは暗さを示します。

動的

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

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