DSC 設定ドキュメント関数リファレンス

概要

ランタイム処理のために設定ドキュメント内で使用可能な関数。

説明

DSC 構成ドキュメントでは、DSC が実行時に処理してドキュメントの値を決定する関数の使用がサポートされています。これらの関数を使用すると、値を再利用し、保守が容易な構成を定義できます。

DSC で関数を認識するには、文字列内の角かっこで囲む必要があります。 DSC 設定ドキュメント関数では、次の構文を使用します。

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

YAML で関数を使用する場合は、二重引用符で囲まれた文字列値を使用するか、折りたたまれたブロック構文またはリテラルブロック構文を使用して関数を指定する必要があります。折り畳みブロック構文またはリテラルブロック構文を使用する場合は、常にブロックチョンピングインジケーター (-) を使用して、後続の改行と空行をトリミングします。

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

ネストされた関数の出力を外部関数のパラメータ値として使用して、関数をネストできます。 DSC は、ネストされた関数を最も内側の関数から最も外側の関数に処理します。

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

長い関数は、特に深くネストされている場合、読み取るのが難しい場合があります。改行を使用すると、長い関数を folded または literal ブロック構文で読みやすい形式に分割できます。

# 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>)
    )
  )]

関数の出力が配列またはオブジェクトの場合、配列内のオブジェクトまたは項目のプロパティにアクセスできます。

出力オブジェクトのプロパティにアクセスするには、関数の閉じ括弧の後にピリオド (.) を付け、その後にアクセスするプロパティの名前を付けます。ネストされたオブジェクトと配列のプロパティにアクセスすることもできます。

# 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>]"

配列出力の特定の項目にアクセスするには、関数の閉じ括弧の後に開き角括弧 ([)、次にアクセスする項目の整数インデックス、次に閉じ角括弧 (]) を付けます。ネストされた配列の項目にアクセスすることもできます。

# 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]]"

例示

例 1 - 有効な構文を持つ関数を使用する

次の設定ドキュメントは、設定ドキュメントで関数を指定するための 3 つの有効な構文を示しています。各リソースインスタンスでは、 text プロパティは 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

例 2 - 2 つの文字列を連結する

次の設定ドキュメントでは、リソースインスタンスの text プロパティを concat() 関数の出力に設定し、文字列 a の a と b を 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

例 3 - ネストされた関数の使用

次の設定ドキュメントは、関数をネストする方法を示しています。最初の 2 つのリソースインスタンスは、 concat() 関数の出力を base64() 関数への入力として使用します。 3 番目のリソースインスタンスは、最初の 2 つのインスタンスからのネストされた関数の出力を concat() 関数への入力として使用します。最後のリソースインスタンスは、3 番目のインスタンスに示されている深くネストされた関数の出力を 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

例 4 - オブジェクトのプロパティと配列項目にアクセスする

次の設定ドキュメントは、配列内のオブジェクトと項目のプロパティにアクセスする方法を示しています。この例では、共有パラメーター定義ファイルを使用して、各構成ドキュメントで 1 つのデータソースを簡単に参照できるようにします。

パラメータファイルでは、次の 2 つのパラメータが定義されています。

data パラメーターは複雑なオブジェクトです。 message プロパティはネストされたオブジェクトです。 services プロパティは入れ子になった配列です。
list パラメーターは複素配列です。配列の 3 番目の項目はオブジェクトです。配列の 4 番目の項目は、ネストされた配列です。

# 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

最初の設定ドキュメントは、 Microsoft.DSC.Debug/Echo リソースのインスタンスを定義して、設定ドキュメント内のオブジェクトのプロパティにアクセスする方法を示します。

# 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

次の設定ドキュメントでは、ネストされたオブジェクトのプロパティにアクセスする方法を示します。

# 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

次の設定ドキュメントは、配列内の項目にアクセスする方法を示しています。

# 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

次の設定ドキュメントは、ネストされた配列内の項目にアクセスする方法を示しています。

# 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

最後の設定ドキュメントでは、プロパティとアイテムのアクセス構文を一緒に使用して、複雑なオブジェクトの値にアクセスする方法を示します。

# 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

次のセクションでは、目的と入力の種類別に使用できる DSC 構成関数について説明します。

配列関数

次の関数のリストは、配列を操作します。

concat() - 複数の文字列の配列を 1 つの文字列の配列に結合します。
createArray() - 同じ型の 0 個以上の値から、指定された型の配列を作成します。
min() - 整数の配列から最小の整数値を返します。
max() - 整数の配列から最大の整数値を返します。

データ関数

次の関数の一覧は、リソースインスタンスの外部にあるデータに対して動作します。

envvar() - 指定された環境変数の値を返します。
parameters() - 指定された設定パラメータの値を返します。
variables() - 指定された設定変数の値を返します。

数学関数

次の関数の一覧は、整数値または整数値の配列を操作します。

add() - 2 つの整数の合計を返します。
div() - 2 つの整数の被除数を整数として返し、結果の残りの部分がある場合は削除します。
int() - 小数部を持つ文字列または数値を整数に変換します。
max() - 整数の配列から最大値を返します。
min() - 整数の配列から最小値を返します。
mod() - 2 つの整数の除算から余りを返します。
mul() - 2つの整数を乗算して積を返します。
sub() - ある整数から別の整数を減算した差を返します。

リソース関数

次の関数のリストは、リソースインスタンスで動作します。

reference() - 別のリソースインスタンスの結果データを返します。
resourceId() - 参照または依存する別のリソースインスタンスの ID を返します。

文字列関数

次の関数のリストは、文字列を操作するためのものです。

base64() - 文字列の base64 表現を返します。
concat() - 入力文字列が指定された順序で連結される結合文字列を返します。

型関数

次の関数のリストは、特定のタイプの値を作成または変換します。

createArray() - 同じ型の 0 個以上の値から、指定された型の配列を作成します。
int() - 小数部を持つ文字列または数値を整数に変換します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-07-10