言語の基礎

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

複数の値

あるキーが複数の値を持つ場合、各値は新しい行にリストされ、各行の先頭にはダッシュ 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.

自動化スクリプト

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

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

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

構造体

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

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

リファレンス セクションでは、使用可能なすべての Struct のスキーマ定義を提供します。

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

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

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

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

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

型付き構造体

一部の Struct は、時間スケジュールまたはデバイスの状態の変化に基づく開始条件を表すことができます。starter の各タイプは、個別の Field のセットを提供する必要があります。

# 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 構造体も型指定されています。

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

配列

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

配列に 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