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

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 कहा जाता है.

Struct

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

automation Struct पर एक नज़र डालें, जिसमें चार फ़ील्ड के बारे में जानकारी दी गई है:

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

दिए गए Struct में मुख्य नाम यूनीक होते हैं और केस-सेंसिटिव होते हैं.

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

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

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

• 'ज़रूरी' बनाम 'ज़रूरी नहीं'. इससे पता चलता है कि फ़ील्ड ज़रूरी है या नहीं को छोड़ा जा सकता है.
• फ़ील्ड डिपेंडेंसी. सिर्फ़ वैकल्पिक फ़ील्ड पर निर्भर करता है. यह इस फ़ील्ड का इस्तेमाल करते समय अतिरिक्त जांच करें, जैसे फ़ील्ड B का इस्तेमाल सिर्फ़ तब करें, जब फ़ील्ड A सेट है या फ़ील्ड 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 Struct.

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

प्रिमिटिव

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

रंग

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

SpectrumHSV

स्पेक्ट्रम एचएसवी टाइप तीन न्यूमेरिक फ़ील्ड का इस्तेमाल करके कलर तय करता है:

• रंग, रंग की तरंगदैर्ध्य रंग से मेल खाता है.
• Saturation से रंग की तीव्रता का पता चलता है.
• वैल्यू से पता चलता है कि रंग कितना हल्का या गहरा है.

डाइनैमिक

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

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

अन्य 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