भाषा की बुनियादी बातें

YAML के बारे में जानकारी

YAML एक लोकप्रिय भाषा है, जिसका इस्तेमाल सॉफ़्टवेयर कॉन्फ़िगरेशन के बारे में बताने के लिए किया जाता है. यह व्यवस्थित जानकारी को साफ़ तौर पर दिखाने का ऐसा तरीका मुहैया कराता है जिसे कोई भी व्यक्ति आसानी से पढ़ सकता है. स्क्रिप्ट किया हुआ अपना पहला ऑटोमेशन बनाने से पहले, आपको YAML के बारे में समझने की ज़रूरत है. यहां कुछ बुनियादी चीज़ों के बारे में बताया गया है. YAML के बारे में ज़्यादा जानने के लिए, वर्शन 1.1 की जानकारी देखें.

की-वैल्यू पेयर

YAML दस्तावेज़, की-वैल्यू पेयर का कलेक्शन होते हैं. यहां दिए गए उदाहरण में, कुंजी name है और वैल्यू TV on lights off है. कुंजी और वैल्यू को कोलन और उसके बाद स्पेस से अलग किया जाता है. सही तरीके से बनाए गए YAML के लिए दोनों वर्ण ज़रूरी हैं.

name: TV on lights off

वैल्यू

किसी कुंजी से जुड़ी वैल्यू, किसी स्ट्रिंग, संख्या या तारीख की तरह ही बुनियादी हो सकती है या की-वैल्यू पेयर के दूसरे कलेक्शन जितनी ही जटिल हो सकती है.

स्ट्रिंग

अगर स्ट्रिंग की वैल्यू इनमें से किसी एक वर्ण से शुरू होती है: [, {, ", ' या # या स्ट्रिंग में : (कोलन के बाद स्पेस होता है) है, तो इसे कोट किया जाना चाहिए.

सिंगल- और डबल-कोट, दोनों स्वीकार किए जाते हैं, लेकिन क्लोज़िंग कोट शुरुआती कोट से मेल खाना चाहिए.

सही उद्धरण देना:

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"

नेस्ट किए गए की-वैल्यू पेयर

यहां कुंजी metadata की वैल्यू, दो की-वैल्यू पेयर (name और description) की सूची के तौर पर दी गई है:

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

इंडेंट करना

YAML स्ट्रक्चर को दिखाने के लिए, इंडेंट का इस्तेमाल करता है. ऊपर दिए गए उदाहरण में, name और description को इंडेंट (दो स्पेस से) किया गया है, ताकि यह पता चल सके कि ये metadata की के चाइल्ड हैं.

YAML में इंडेंट सख्त है. चाइल्ड संरचना का इंडेंट उसके पैरंट से ज़्यादा होना चाहिए. साथ ही, एक जैसे लेवल के कुंजी-वैल्यू पेयर में एक जैसा इंडेंट होना चाहिए.

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

कई वैल्यू

अगर किसी कुंजी में एक से ज़्यादा वैल्यू हैं, तो हर वैल्यू को नई लाइन में डाला जाएगा और हर लाइन के बाद डैश और स्पेस होगा. यहां दिए गए उदाहरण में, दो सूचियां हैं:

1. किसी ऑटोमेशन में कई starters हो सकते हैं, इसलिए पहला स्टार्टर डैश और स्पेस से शुरू होता है.
2. 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.

ऑटोमेशन स्क्रिप्ट

ऑटोमेशन स्क्रिप्ट सिंटैक्स के स्पेसिफ़िकेशन को स्कीमा कहा जाता है.

ऑटोमेशन स्कीमा में कुछ डेटा स्ट्रक्चर के बारे में बताया गया है:

• किसी एक की-वैल्यू पेयर को फ़ील्ड कहा जाता है.
• स्कीमा के ज़रिए तय किए गए फ़ील्ड के कलेक्शन को Struct कहा जाता है.

स्ट्रक्चर

ऑटोमेशन स्क्रिप्टिंग लैंग्वेज, कई स्टैंडर्ड 'ब्लॉक' या डेटा स्ट्रक्चर के बारे में बताता है. इन्हें स्ट्रक्चर कहा जाता है.

automation Struct पर एक नज़र डालें, जो चार फ़ील्ड के बारे में बताता है:

कुंजी	स्ट्रीम किस तरह की है	जानकारी
name	स्ट्रिंग	ज़रूरी नहीं. ऑटोमेशन का नाम. यह लोगों को नहीं दिखाया जाता. यह सिर्फ़ डेवलपर के लिए है.
starters	[स्टार्टर]	ज़रूरी है. स्टार्टर की सूची.
condition	स्थिति	ज़रूरी नहीं. शर्त.
actions	[कार्रवाई]	ज़रूरी है. कार्रवाइयों की सूची.

रेफ़रंस सेक्शन में, सभी उपलब्ध स्ट्रक्चर के लिए स्कीमा की परिभाषाएं दी गई हैं.

दिए गए Struct में, मुख्य नाम यूनीक होते हैं और केस-सेंसिटिव (बड़े और छोटे अक्षरों में अंतर) होते हैं.

संभावित वैल्यू टाइप ये हैं:

• एक प्रिमिटिव टाइप: बूल, नंबर, स्ट्रिंग, समय वगैरह.
• स्ट्रक्चर्ड टाइप: फ़ील्ड का कलेक्शन.
• डेटा टाइप की कैटगरी. श्रेणी को [] से दिखाया जाता है. उदाहरण के लिए, [string] स्ट्रिंग का कलेक्शन है और [Starter] स्टार्टर स्ट्रक्ट का कलेक्शन है.
• अन्य खास टाइप: Entity, FieldPath.

हर फ़ील्ड के ब्यौरे में ज़रूरी जानकारी होती है, जिसमें ये शामिल हैं:

• 'ज़रूरी' बनाम 'ज़रूरी नहीं' से पता चलता है कि यह फ़ील्ड ज़रूरी है या नहीं. इसके अलावा, इससे पता चलता है कि इसे स्किप किया जा सकता है या नहीं.
• फ़ील्ड डिपेंडेंसी. सिर्फ़ वैकल्पिक फ़ील्ड में डिपेंडेंसी होती है. इससे यह पता चलता है कि इस फ़ील्ड का इस्तेमाल करते समय, फ़ील्ड B का इस्तेमाल करना बहुत ज़रूरी है. जैसे, फ़ील्ड A सेट होने पर ही फ़ील्ड B का इस्तेमाल करें या फ़ील्ड A का इस्तेमाल करने पर, फ़ील्ड B या फ़ील्ड C को सेट न करें.
• संभावित वैल्यू. उदाहरण के लिए, Enum फ़ील्ड टाइप वाली स्ट्रिंग का सीमित वैल्यू सेट या संख्याओं की वह रेंज जिसे टाइप नंबर वाले फ़ील्ड में इस्तेमाल किया जा सकता है.

टाइप किया गया स्ट्रक्चर

कुछ स्ट्रक्चर्ड, समय या डिवाइस की स्थिति में होने वाले बदलाव के आधार पर, स्टार्टर को दिखा सकते हैं. हर टाइप के 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 स्ट्रक्चर भी टाइप किए गए हैं.

Struct में मौजूद अन्य फ़ील्ड, चाइल्ड Struct (type) के स्पेसिफ़िकेशन के मुताबिक होने चाहिए. उदाहरण के लिए, type के तौर पर device.state.OnOff का इस्तेमाल करने पर, सिर्फ़ इस टाइप के लिए दिए गए फ़ील्ड उस starter स्ट्रक्चर में मान्य होंगे.

Array

YAML में, वैल्यू का कलेक्शन - से शुरू होता है. इसमें डैश के बाद स्पेस होता है. कलेक्शन में कई Struct वैल्यू या एक से ज़्यादा प्रिमिटिव वैल्यू हो सकती हैं. हालांकि, अरे में वैल्यू एक ही तरह के होने चाहिए.

जब कलेक्शन में एक आइटम होता है, तो डैश और स्पेस को छोड़ा जा सकता है:

# 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

प्रिमिटिव

नीचे दिए गए शुरुआती डेटा टाइप, ऑटोमेशन स्क्रिप्ट स्कीमा के साथ काम करते हैं:

बूल	true false
नंबर	पूर्णांक या दशमलव संख्या
स्ट्रिंग	सादा लेख स्ट्रिंग को कोट करने की ज़रूरत नहीं होती. हालांकि, कुछ चुनिंदा मामलों के लिए ही स्ट्रिंग इस्तेमाल की जा सकती है.
तारीख	महीना और दिन. फ़ॉर्मैट MM-DD या MM/DD है. 09/01 09-01
समय	दिन का समय. यह घड़ी का समय या सौर समय हो सकता है. घड़ी के समय के लिए, यह AM/PM फ़ॉर्मैट या 24H फ़ॉर्मैट का इस्तेमाल कर सकता है. सेकंड वैकल्पिक होते हैं. सोलर टाइम के लिए, 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	कोई रंग दिखाने वाला छह अंकों का हेक्साडेसिमल कोड. # से आगे कोई नहीं है. FFFFFF B5D2A1 DFA100
तापमान	सामान्य तापमान का डेटा. तापमान की माप दिखाने के लिए, वैल्यू में हमेशा 'C' या 'F' जोड़ें. 20.5C 90F
ColorTemperature	केल्विन में कलर टेंपरेचर. 5000K

रंग

कलर इन तीन में से किसी एक तरीके से तय किए जा सकते हैं - ColorHex या ColorTemperature प्रिमिटिव टाइप या कंपाउंड टाइप SpectrumHSV का इस्तेमाल.

SpectrumHSV

SpectrumHSV का टाइप, तीन संख्या वाले फ़ील्ड का इस्तेमाल करके किसी रंग के बारे में बताता है:

• ह्यू, कलर वेवलेंथ से जुड़ा होता है.
• संतृप्तता रंग की तीव्रता के बारे में बताती है.
• वैल्यू, रंग की चमक या अंधेरे के बारे में बताती है.

डाइनैमिक

कभी-कभी, कुंजी का डेटा टाइप तय नहीं हो पाता. दूसरे फ़ील्ड की वैल्यू के आधार पर, यह एक शुरुआती टाइप हो सकता है.

डाइनैमिक डेटा टाइप फ़ील्ड का एक उदाहरण 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

यह एक खास स्ट्रिंग फ़ॉर्मैट है, जिसका इस्तेमाल डेटा पेलोड में डेटा का पता लगाने के लिए किया जाता है. नीचे दिए गए उदाहरण में, state फ़ील्ड के लिए currentVolume फ़ील्डपाथ है.

# The state field accepts a FieldPath type.
starters:
  type: device.state.Volume
  device: My TV - Living Room
  state: currentVolume
  is: 5

अन्य फ़ील्ड पाथ में, ज़रूरी आइटम पाने के लिए कई लेवल हो सकते हैं. साथ ही, स्टार्टर और कार्रवाई के फ़ॉर्मैट में इसका फ़ॉर्मैट अलग-अलग होता है.

स्टार्टर के लिए बिंदु नोटेशन का इस्तेमाल किया जाता है, जिसमें पूरा पाथ एक ही फ़ील्ड में होता है. ऐसा मुख्य तौर पर, स्टार्टर लॉजिक में तुलना करने के लिए किया जाता है. उदाहरण के लिए, रंग के तापमान को स्टार्टर के तौर पर इस्तेमाल करने के लिए, आपको राज्य के लिए 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