Referenční informace k funkcím konfiguračního dokumentu DSC

Přehled

Funkce dostupné v konfiguračním dokumentu pro zpracování za běhu.

Popis

Konfigurační dokumenty DSC podporují použití funkcí, které DSC zpracovává za běhu k určení hodnot dokumentu. Tyto funkce umožňují definovat konfigurace, které opakovaně používají hodnoty a snadněji se udržují.

Aby DSC rozpoznal funkci, musí být umístěna v hranatých závorkách v řetězci. Funkce konfiguračního dokumentu DSC používají následující syntaxi:

[<function-name>(<function-parameters>...)]

Při používání funkcí v YAML musíte funkci zadat s řetězcovou hodnotou, která je zabalena do dvojitých uvozovek nebo používá syntaxi přeloženého bloku nebo bloku literálů . Při použití syntaxe přeloženého nebo literálového bloku vždy používejte indikátor rozdělení bloku (-) k oříznutí koncových zalomení řádků a prázdných řádků.

# Double quoted syntax
<keyword>: "[<function-name>(<function-parameters>...)]"
# Folded block syntax
<keyword>: >-
  [<function-name>(<function-parameters>...)]
# Literal block syntax
<keyword>: |-
  [<function-name>(<function-parameters>...)]

Funkce můžete vnořit pomocí výstupu vnořené funkce jako hodnoty parametru pro vnější funkci. DSC zpracovává vnořené funkce od nejvnitřnější funkce po nejvzdálenější funkci.

[<outer-function-name>(<nested-function-name>(<nested-function-parameters>))]

Čtení dlouhých funkcí může být obtížné, zejména pokud jsou hluboce vnořené. Nové řádky můžete použít k rozdělení dlouhých funkcí do čitelnějšího formátu se syntaxí přeloženého nebo literálového bloku.

# Multi-line folded block syntax
<keyword>: >-
  [<outer-function-name>(
    <nested-function-name>(
      <deeply-nested-function-name>(<deeply-nested-function-parameters>)
    )
  )]
# Multi-line literal block syntax
<keyword>: |-
  [<outer-function-name>(
    <nested-function-name>(
      <deeply-nested-function-name>(<deeply-nested-function-parameters>)
    )
  )]

Pokud je výstupem funkce pole nebo objekt, můžete získat přístup k vlastnostem objektu nebo položek v poli.

Chcete-li získat přístup k vlastnosti výstupního objektu, postupujte podle pravé závorky funkce s tečkou (.) a poté za název vlastnosti, ke které chcete získat přístup. Můžete také přistupovat k vlastnostem vnořených objektů a polí.

# Accessing a top-level property syntax
<keyword>: "[<function-name>(<function-parameters>...).<property-name>]"
# Accessing a property nested in another object syntax
<keyword>: "[<function-name>(<function-parameters>...).<property-name>.<nested-property-name>]"
# Accessing a property nested in an array item syntax
<keyword>: "[<function-name>(<function-parameters>...)[<index>].<nested-property-name>]"

Chcete-li získat přístup k určité položce ve výstupu pole, postupujte podle pravé závorky funkce s levou hranatou závorkou ([), poté celočíselným indexem položky, ke které chcete přistupovat, a nakonec pravou hranatou závorkou (]). Můžete také přistupovat k položkám ve vnořených polích.

# Accessing a top-level array item syntax
<keyword>: "[<function-name>(<function-parameters>...)[<index>]]"
# Accessing an array item nested in a property syntax
<keyword>: "[<function-name>(<function-parameters>...).<property-name>[<nested-array-index>]]"
# Accessing an array item nested in another array syntax
<keyword>: "[<function-name>(<function-parameters>...)[<index>][nested-array-index]]"

Příklady

Příklad 1 – Použití funkce s platnou syntaxí

Následující konfigurační dokument ukazuje tři platné syntaxe pro specifikaci funkce v konfiguračním dokumentu. V každé instanci text prostředku je vlastnost nastavena na výstup funkce base64().

# overview.example.1.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Double quoted syntax
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: "[base64('ab')]"
  - name: Folded block syntax
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: >-
        [base64('ab')]
  - name: Literal block syntax
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: |-
        [base64('ab')]

dsc config get --file overview.example.1.dsc.config.yaml

results:
- name: Double quoted syntax
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: YWI=
- name: Folded block syntax
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: YWI=
- name: Literal block syntax
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: YWI=
messages: []
hadErrors: false

Příklad 2 – Zřetězení dvou řetězců

Následující konfigurační dokument nastaví text vlastnost instance prostředku na výstup funkce concat(), která kombinuje řetězce a a b do ab.

# overview.example.2.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Echo the concatenated strings 'a' and 'b'
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: "[concat('a', 'b')]"

dsc config get --file overview.example.2.dsc.config.yaml

results:
- name: Echo the concatenated strings 'a' and 'b'
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: ab
messages: []
hadErrors: false

Příklad 3 – Použití vnořených funkcí

Následující konfigurační dokument ukazuje, jak můžete funkce vnořit. První dvě instance prostředků používají výstup funkce concat() jako vstup funkce base64(). Třetí instance prostředku používá výstup vnořených funkcí z prvních dvou instancí jako vstup do concat() funkce. Poslední instance prostředku převede výstup hluboce vnořených funkcí zobrazených ve třetí instanci na base64.

# overview.example.3.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Echo the concatenated strings 'a' and 'b' as base64
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: "[base64(concat('a', 'b'))]"
  - name: Echo the concatenated strings 'c' and 'd' as base64
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: "[base64(concat('c', 'd'))]"
  - name: Echo the concatenated base64 of strings 'ab' and 'cd'
    type: Microsoft.DSC.Debug/Echo
    properties:
      text: "[concat(base64(concat('a', 'b')), base64(concat('c', 'd')))]"
  - name: Echo the concatenated base64 of strings 'ab' and 'cd' as base64
    type: Microsoft.DSC.Debug/Echo
    properties:
      # text: "[base64(concat(base64(concat('a', 'b')), base64(concat('c', 'd'))))]"
      text: >-
        [base64(
          concat(
            base64(concat('a', 'b')),
            base64(concat('c', 'd'))
          )
        )]

dsc config get --file overview.example.3.dsc.config.yaml

results:
- name: Echo the concatenated strings 'a' and 'b' as base64
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: YWI=
- name: Echo the concatenated strings 'c' and 'd' as base64
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: Y2Q=
- name: Echo the concatenated base64 of strings 'ab' and 'cd'
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: YWI=Y2Q=
- name: Echo the concatenated base64 of strings 'ab' and 'cd' as base64
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      text: WVdJPVkyUT0=
messages: []
hadErrors: false

Příklad 4 – Vlastnosti objektu Access a položky pole

Následující konfigurační dokumenty ukazují, jak lze přistupovat k vlastnostem objektů a položek v polích. V příkladu je použit definiční soubor sdílených parametrů, který usnadňuje odkazování na jeden zdroj dat v každém konfiguračním dokumentu.

Soubor parametrů definuje dva parametry:

Parametr data je složitý objekt. Vlastnost message je vnořený objekt. Vlastnost services je vnořené pole.
Parametr list je komplexní pole. Třetí položkou v poli je objekt. Čtvrtá položka v poli je vnořené pole.

# overview.example.4.dsc.parameters.yaml
parameters:
  # Object parameter
  data:
    # Object property as string
    name:  Example 4
    # Object property as integer
    count: 1
    # Object property as nested object
    message:
      text:  Default message
      level: info
      context:
        location: DC01
    # Object property as array
    services:
      - web
      - database
      - application
  # Array parameter
  list:
    # Array item as string
    - first
    # Array item as integer
    - 2
    # array item as object
    - name:  third
      value: 3
    # Array item as nested array
    -
      - Nested first
      - Nested second
      - name: Nested third

První konfigurační dokument definuje instanci Microsoft.DSC.Debug/Echo prostředku, která ukazuje, jak můžete získat přístup k vlastnostem objektu v konfiguračním dokumentu.

# overview.example.4.properties.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access the properties of an object
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        # Accessing output object
        data: "[parameters('data')]"
        # Accessing properties
        data.name:     "[parameters('data').name]"     # string
        data.count:    "[parameters('data').count]"    # integer
        data.message:  "[parameters('data').message]"  # nested object
        data.services: "[parameters('data').services]" # array

$params=overview.example.4.dsc.parameters.yaml
$config=overview.example.4.properties.dsc.config.yaml
dsc config --parameters-file $params get --file $config

results:
- metadata:
    Microsoft.DSC:
      duration: PT0.133791S
  name: Access the properties of an object
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      output:
        data:
          count: 1
          name: Example 4
          message:
            text: Default message
            level: info
            context:
              location: DC01
          services:
          - web
          - database
          - application
        data.name: Example 4
        data.count: 1
        data.message:
          text: Default message
          level: info
          context:
            location: DC01
        data.services:
        - web
        - database
        - application

V dalším konfiguračním dokumentu je ukázáno, jak lze získat přístup k vlastnostem vnořených objektů.

# overview.example.4.nested.properties.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access the properties of a nested object
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        data.message.text:             "[parameters('data').message.text]"
        data.message.level:            "[parameters('data').message.level]"
        data.message.context:          "[parameters('data').message.context]"
        data.message.context.location: "[parameters('data').message.context.location]"

$params=overview.example.4.dsc.parameters.yaml
$config=overview.example.4.nested.properties.dsc.config.yaml
dsc config --parameters-file $params get --file $config

results:
- metadata:
    Microsoft.DSC:
      duration: PT0.0760186S
  name: Access the properties of an object
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      output:
        data.message.text: Default message
        data.message.level: info
        data.message.context:
          location: DC01
        data.message.context.location: DC01

Následující konfigurační dokument ukazuje, jak lze přistupovat k položkám v poli.

# overview.example.4.items.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access items in an array
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        # Accessing output array
        list: "[parameters('list')]"
        # Accessing array items
        list[0]: "[parameters('list')[0]]" # string
        list[1]: "[parameters('list')[1]]" # integer
        list[2]: "[parameters('list')[2]]" # object
        list[3]: "[parameters('list')[3]]" # nested array

$params=overview.example.4.dsc.parameters.yaml
$config=overview.example.4.items.dsc.config.yaml
dsc config --parameters-file $params get --path $config

results:
- metadata:
    Microsoft.DSC:
      duration: PT0.0750682S
  name: Access items in an array
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      output:
        list:
        - first
        - 2
        - name: third
          value: 3
        - - Nested first
          - Nested second
          - name: Nested third
        list[0]: first
        list[1]: 2
        list[2]:
          name: third
          value: 3
        list[3]:
        - Nested first
        - Nested second
        - name: Nested third

Následující konfigurační dokument ukazuje, jak lze přistupovat k položkám ve vnořeném poli.

# overview.example.4.nested.items.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access items in a nested array
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        list[3][0]: "[parameters('list')[3][0]]"
        list[3][1]: "[parameters('list')[3][1]]"
        list[3][2]: "[parameters('list')[3][2]]"

$params=overview.example.4.dsc.parameters.yaml
$config=overview.example.4.nested.items.dsc.config.yaml
dsc config --parameters-file $params get --file $config

results:
- metadata:
    Microsoft.DSC:
      duration: PT0.1349442S
  name: Access items in a nested array
  type: Microsoft.DSC.Debug/Echo
  result:
    actualState:
      output:
        list[3][0]: Nested first
        list[3][1]: Nested second
        list[3][2]:
          name: Nested third

Poslední konfigurační dokument ukazuje, jak můžete použít syntaxi přístupu k vlastnostem a položkám společně pro přístup k hodnotám ve složitých objektech.

# overview.example.4.mixed.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access values in complex objects and arrays
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        # Accessing array items of an object property
        data.services[0]: "[parameters('data').services[0]]"
        data.services[1]: "[parameters('data').services[1]]"
        data.services[2]: "[parameters('data').services[2]]"
        # Accessing properties of an object in an array
        list[2].name:  "[parameters('list')[2].name]"
        list[2].value: "[parameters('list')[2].value]"
        # Accessing the property of an object in a nested array
        list[3][2].name: "[parameters('list')[3][2].name]"

$params=overview.example.4.dsc.parameters.yaml
$config=overview.example.4.mixed.dsc.config.yaml
dsc config --parameters-file $params get --file $config

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
# Minimal definition of the parameters
parameters:
  data: { type: object }
  list: { type: array }

resources:
  - name: Access values in complex objects and arrays
    type: Microsoft.DSC.Debug/Echo
    properties:
      output:
        # Accessing array items of an object property
        data.services[0]: "[parameters('data').services[0]]"
        data.services[1]: "[parameters('data').services[1]]"
        data.services[2]: "[parameters('data').services[2]]"
        # Accessing properties of an object in an array
        list[2].name:  "[parameters('list')[2].name]"
        list[2].value: "[parameters('list')[2].value]"
        # Accessing the property of an object in a nested array
        list[3][2].name: "[parameters('list')[3][2].name]"

Functions

Následující části obsahují dostupné konfigurační funkce DSC podle účelu a typu vstupu.

Funkce polí

Následující seznam funkcí pracuje s poli:

concat() - Kombinuje více polí řetězců do jednoho pole řetězců.
createArray() - Vytvoří pole daného typu z nuly nebo více hodnot stejného typu.
min() - Vrací nejmenší celočíselnou hodnotu z pole celých čísel.
max() - Vrací největší celočíselnou hodnotu z pole celých čísel.

Datové funkce

Následující seznam funkcí pracuje s daty mimo instanci prostředku:

envvar() - Vrací hodnotu zadané proměnné prostředí.
parameters() – Vrací hodnotu zadaného konfiguračního parametru.
variables() - Vrací hodnotu zadané konfigurační proměnné.

Matematické funkce

Následující seznam funkcí pracuje s celočíselnými hodnotami nebo poli celočíselných hodnot:

add() - Vrací součet dvou celých čísel.
div() - Vrátí dělenec dvou celých čísel jako celé číslo, přičemž zahodí zbytek výsledku, pokud existuje.
int() - Převede řetězec nebo číslo s desetinnou částí na celé číslo.
max() - Vrací největší hodnotu z pole celých čísel.
min() - Vrací nejmenší hodnotu z pole celých čísel.
mod() - Vrací zbytek z dělení dvou celých čísel.
mul() - Vrátí součin z vynásobení dvou celých čísel.
sub() - Vrátí rozdíl od odečtení jednoho celého čísla od druhého.

Funkce zdrojů

Následující seznam funkcí pracuje s instancemi prostředků:

reference() – Vrátí výsledná data pro jinou instanci zdroje.
resourceId() – Vrací ID jiné instance zdroje, na kterou se má odkazovat nebo na které závisí.

Řetězcové funkce

Následující seznam funkcí slouží pro manipulaci s řetězci:

base64() – Vrátí reprezentaci řetězce base64.
concat() - Vrací kombinovaný řetězec, kde jsou vstupní řetězce zřetězeny v pořadí, ve kterém jsou určeny.

Typové funkce

Následující seznam funkcí vytváří nebo převádí hodnoty daného typu:

createArray() - Vytvoří pole daného typu z nuly nebo více hodnot stejného typu.
int() - Převede řetězec nebo číslo s desetinnou částí na celé číslo.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-07-10