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
複数の値
特定のキーが複数の値を持つ場合、各値は新しい行にリストされ、各行の先頭にはダッシュとスペースが続きます。次の例では、2 つのリストがあります。
- 自動化は複数の
starters
を持つことができるため、最初の開始条件はダッシュとスペースで始めます。 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.
自動化スクリプト
自動化スクリプトの構文の仕様はスキーマと呼ばれます。
自動化スキーマは、いくつかのデータ構造を定義します。
- 1 つの Key-Value ペアは Field と呼ばれます。
- スキーマによって定義されるフィールドの集合は構造体と呼ばれます。
構造体
自動化スクリプト言語は、構造体と呼ばれるいくつかの標準的な「ブロック」、つまりデータ構造を定義します。
次の 4 つのフィールドを定義する automation
構造体をご覧ください。
キー | タイプ | 説明 |
---|---|---|
|
省略可。 自動化の名前。 この情報はユーザーには表示されません。デベロッパーによる参照のみを目的としています。 |
|
|
[開始条件] |
必須。 開始条件のリスト。 |
|
省略可。 条件。 |
|
|
[アクション] |
必須。 アクションのリスト。 |
リファレンス セクションには、使用可能なすべての構造体のスキーマ定義が記載されています。
キー名は特定の構造体内で一意であり、大文字と小文字が区別されます。
有効な値の型は次のとおりです。
- プリミティブ型: 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
は型指定された構造体であり、time.schedule
や device.state.OnOff
など、type
フィールドの他の子構造体によって拡張され、さまざまな関数を提供します。condition
構造体と action
構造体も型指定されています。
構造体の追加フィールドは、子構造体(type
)の仕様に従う必要があります。たとえば、device.state.OnOff
を type
として使用する場合、その 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 |
|
数値 |
整数または 10 進数 |
文字列 |
書式なしテキスト 特定の場合を除いて、文字列を引用符で囲む必要はありません。 |
日付 |
月と日。形式は MM-DD または MM/DD です。
|
時間 |
時刻。時刻またはソーラー時刻を指定できます。
時刻については、AM/PM 形式または 24 時間形式のいずれかを使用できます。秒は省略可能です。太陽光時間の場合、
|
DateTime |
年、月、日、時刻。日付部分と時刻部分の間には空白文字が必要です。日付の形式は、YYYY-MM-DD または YYYY/MM/DD です。時刻の形式は [Time](#time) と同じです。タイムゾーンはサポートされていません。
|
曜日 |
|
所要時間 |
一定の期間。
|
ColorHex |
色を表す 6 桁の 16 進数コード。 先頭に
|
Temperature | 正常な体温データです。温度測定値を示すために、必ず値に
|
ColorTemperature |
色温度(ケルビン単位)。
|
色
色は、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