.lg ファイル形式.lg file format

適用対象: SDK v4APPLIES TO: SDK v4

Lg ファイルは、エンティティ参照とその構成を含む言語生成テンプレートについて説明します。The .lg file describes language generation templates with entity references and their composition. この記事では、lg ファイル形式で表現されるさまざまな概念について説明します。This article covers the various concepts expressed with the .lg file format.

特殊文字Special Characters


> を使用してコメントを作成します。Use > to create a comment. このプレフィックスが付いたすべての行は、パーサーでスキップされます。All lines that have this prefix will be skipped by the parser.

> This is a comment.

エスケープ文字Escape character

\ をエスケープ文字として使用します。Use \ as an escape character.

# TemplateName
- You can say cheese and tomato \[toppings are optional\]

配列とオブジェクトArrays and objects

配列を作成するCreate an array

配列を作成するには、 $ {[object1, object2,...]} 構文を使用します。To create an array, use the ${[object1, object2, ...]} syntax. たとえば、次の式を使用します。For example, this expression:

${['a', 'b', 'c']}

配列を返し ['a', 'b', 'c'] ます。Returns the array ['a', 'b', 'c'].

オブジェクトの作成Create an object

オブジェクトを作成するには、 $ {{key1: value1, key2: value2,...}} を使用します。To create an object, use the ${{key1:value1, key2:value2, ...}} 構文。syntax. たとえば、次の式を使用します。For example, this expression:

${{user: {name: "Wilson", age: 27}}}

次の JSON オブジェクトを返します。Returns the following JSON object:

  "user": {
    "name": "Wilson",
    "age": 27


テンプレート は、言語生成システムの中核的な概念です。Templates are the core concept of the language generation system. 各テンプレートに名前が付いていて、以下のいずれかが含まれています。Each template has a name and one of the following:

  • one-of バリエーションのテキスト値のリストa list of one-of variation text values
  • 構造化されたコンテンツ定義a structured content definition
  • 条件のコレクション。それぞれに以下が含まれています。a collection of conditions, each with:

テンプレート名Template names

テンプレート名は大文字と小文字が区別され、文字、アンダースコア、および数字のみを含めることができます。Template names are case-sensitive and can only contain letters, underscores, and numbers. という名前のテンプレートの例を次に示し TemplateName ます。The following is an example of a template named TemplateName.

# TemplateName

テンプレートの先頭に数字を使用することはできません。また、テンプレート名の一部をで分割することもできません Templates cannot start with a number, and any part of a template name split by . 先頭を数字にすることはできません。cannot start with a number.

テンプレート応答のバリエーションTemplate response variations

バリエーションは、Markdown リストとして表現されます。Variations are expressed as a Markdown list. 各バリエーションには、 -' 、または + 文字を使用してプレフィックスを付けることができます。You can prefix each variation using the -, ', or + character.

# Template1
- text variation 1
- text variation 2
- one
- two

# Template2
* text variation 1
* text variation 2

# Template3
+ one
+ two

単純な応答テンプレートSimple response template

単純な応答テンプレートには、合成と展開に使用されるテキストのバリエーションが 1 つ以上含まれています。A simple response template includes one or more variations of text that are used for composition and expansion. 提供されているバリエーションの 1 つが、LG ライブラリによってランダムに選択されます。One of the variations provided will be selected at random by the LG library.

次に、2 つのバリエーションが含まれる単純なテンプレートの例を示します。Here is an example of a simple template that includes two variations.

> Greeting template with two variations.
# GreetingPrefix
- Hi
- Hello

条件付き応答テンプレートConditional response template

条件付き応答テンプレートでは、条件に基づいて選択されるコンテンツを作成できます。Conditional response templates let you author content that's selected based on a condition. すべての条件は、アダプティブ式を使用して表します。All conditions are expressed using adaptive expressions.


1 つの条件付き応答テンプレートの中で、条件付きテンプレートを入れ子にすることはできません。Conditional templates cannot be nested in a single conditional response template. 構造化された応答テンプレートで合成を使用して、条件を入れ子にします。Use composition in a structured response template to nest conditionals.

if-else テンプレートIf-else template

if-else テンプレートでは、連鎖している条件の順序に基づいてコレクションを選択するテンプレートを作成できます。The if-else template lets you build a template that picks a collection based on a cascading order of conditions. 評価は、上から実行され、条件が true に評価されたとき、または ELSE ブロックにヒットしたときに停止します。Evaluation is top-down and stops when a condition evaluates to true or the ELSE block is hit.

条件付きの式は中かっこの ${} で囲みます。Conditional expressions are enclosed in braces ${}. 次の例は、単純な IF ELSE 条件付き応答テンプレート定義を示しています。Here's an example that shows a simple IF ELSE conditional response template definition.

> time of day greeting reply template with conditions.
# timeOfDayGreeting
- IF: ${timeOfDay == 'morning'}
    - good morning
    - good evening

次の別の例は、if-else 条件付き応答テンプレート定義を示していす。Here's another example that shows an if-else conditional response template definition. どの条件のバリエーションにも、その他の単純な応答テンプレートや条件付き応答テンプレートへの参照を含められることに注意してください。Note that you can include references to other simple or conditional response templates in the variation for any of the conditions.

# timeOfDayGreeting
- IF: ${timeOfDay == 'morning'}
    - ${morningTemplate()}
- ELSEIF: ${timeOfDay == 'afternoon'}
    - ${afternoonTemplate()}
    - I love the evenings! Just saying. ${eveningTemplate()}

switch テンプレートSwitch template

switch テンプレートでは、式の値を CASE 句に一致させるテンプレートを設計し、その場合に基づいた出力を生成できます。The switch template lets you design a template that matches an expression's value to a CASE clause and produces output based on that case. 条件式は中かっこの ${} で囲みます。Condition expressions are enclosed in braces ${}.

次に、LG 内に SWITCH CASE DEFAULT ブロックを指定できる方法を示します。Here's how you can specify a SWITCH CASE DEFAULT block in LG.

# TestTemplate
- SWITCH: ${condition}
- CASE: ${case-expression-1}
    - output1
- CASE: ${case-expression-2}
    - output2
   - final output

次に、より複雑な SWITCH CASE DEFAULT の例を示します。Here's a more complicated SWITCH CASE DEFAULT example:

> Note: Any of the cases can include reference to one or more templates.
# greetInAWeek
- SWITCH: ${dayOfWeek(utcNow())}
- CASE: ${0}
    - Happy Sunday!
-CASE: ${6}
    - Happy Saturday!
    - ${apology-phrase()}, ${defaultResponseTemplate()}


条件付きテンプレートと同様に、スイッチテンプレートを入れ子にすることはできません。Like conditional templates, switch templates cannot be nested.

構造化された応答テンプレートStructured response template

構造化された応答テンプレートでは、テンプレート作成や合成などの主な LG 機能をサポートする複雑な構造を定義できます。その一方で、構造化された応答の解釈は LG ライブラリの呼び出し元に任せます。Structured response templates let you define a complex structure that supports major LG functionality, like templating, composition, and substitution, while leaving the interpretation of the structured response up to the caller of the LG library.

ボット アプリケーションの場合、以下がネイティブでサポートされています。For bot applications, we natively support:

  • アクティビティ定義activity definition
  • カード定義card definition

詳細については、応答テンプレートの構造化に関するページを参照してください。Read about structure response templates for more information.

テンプレートの合成と展開Template composition and expansion

テンプレートへの参照References to templates

バリエーション テキストには、洗練された応答の合成と解決を助けるため、別の名前付きテンプレートへの参照を含めることができます。Variation text can include references to another named template to aid with composition and resolution of sophisticated responses. その他の名前付きテンプレートへの参照は、 ${<TemplateName>()} などの中かっこを使用して示されます。References to other named templates are denoted using braces, such as ${<TemplateName>()}.

> Example of a template that includes composition reference to another template.
# GreetingReply
- ${GreetingPrefix()}, ${timeOfDayGreeting()}

# GreetingPrefix
- Hi
- Hello

# timeOfDayGreeting
- IF: ${timeOfDay == 'morning'}
    - good morning
- ELSEIF: ${timeOfDay == 'afternoon'}
    - good afternoon
    - good evening

GreetingReply テンプレートを呼び出すと、次のいずれかの展開による解決となる可能性があります。Calling the GreetingReply template can result in one of the following expansion resolutions:

Hi, good morning
Hi, good afternoon
Hi, good evening
Hello, good morning
Hello, good afternoon
Hello, good evening


one-of バリエーション テキスト内で直接使用する場合、エンティティ参照は、$ {entityName} のように中かっこで囲むことによって示されます。パラメーターとして使用する場合は中かっこを使用しません。When used directly within a one-of variation text, entity references are denoted by enclosing them in braces, such as ${entityName}, or without braces when used as a parameter.

エンティティは、パラメーターとして使用できます。Entities can be used as a parameter:

バリエーションでの事前構築済み関数の使用Using prebuilt functions in variations

アダプティブ式でサポートされている事前構築済み関数は、one-of バリエーション テキスト内でインラインで使用し、さらに強力なテキスト合成を実現することもできます。Prebuilt functions supported by adaptive expressions can also be used inline in a one-of variation text to achieve even more powerful text composition. 式をインラインで使用するには、単にそれを中かっこで囲みます。To use an expression inline, simply wrap it in braces.

# RecentTasks
- IF: ${count(recentTasks) == 1}
    - Your most recent task is ${recentTasks[0]}. You can let me know if you want to add or complete a task.
- ELSEIF: ${count(recentTasks) == 2}
    - Your most recent tasks are ${join(recentTasks, ', ', ' and ')}. You can let me know if you want to add or complete a task.
- ELSEIF: ${count(recentTasks) > 2}
    - Your most recent ${count(recentTasks)} tasks are ${join(recentTasks, ', ', ' and ')}. You can let me know if you want to add or complete a task.
    - You don't have any tasks.

上の例では、recentTasks コレクション内のすべての値を一覧表示するために、join 事前構築済み関数を使用しています。The example above uses the join prebuilt function to list all values in the recentTasks collection.

テンプレートと事前定義済み関数が同じ呼び出しシグネチャを共有しているとすると、テンプレートの名前を、事前定義済み関数の名前と同じにすることはできません。Given templates and prebuilt functions share the same invocation signature, a template name cannot be the same as a prebuilt function name.

テンプレート名は、事前構築済み関数名と一致してはいけません。A template name should not match a prebuilt function name. 事前構築済み関数が優先されます。The prebuilt function takes precedence. このような競合を回避するには、テンプレート名を参照するときに、lg. を前に付加します。To avoid such conflicts, you can prepend lg. when referencing your template name. 次に例を示します。For example:

> Custom length function with one parameter.
# length(a)
- This is use's customized length function

# myfunc1
> will call prebuilt function length, and return 2
- ${length('hi')}

# mufunc2
> this calls the lg template and output 'This is use's customized length function'
- ${lg.length('hi')}

バリエーション内の複数行テキストMultiline text in variations

各 one-of バリエーションには、3 つの引用符で囲んだ複数行テキストを含めることができます。Each one-of variation can include multiline text enclosed in triple quotes.

# MultiLineExample
    - ```This is a multiline list
        - one
        - two
    - ```This is a multiline variation
        - three
        - four

複数行のバリエーションでは、要求された操作を中かっこ ${} で囲むことによって、テンプレートの展開とエンティティの置換を要求できます。Multiline variation can request template expansion and entity substitution by enclosing the requested operation in braces, ${}.

# MultiLineExample
    - ```
        Here is what I have for the order
        - Title: ${reservation.title}
        - Location: ${reservation.location}
        - Date/ time: ${reservation.dateTimeReadBack}

複数行のサポートにより、言語生成サブシステムで複雑な JSON や XML (ボットの音声応答を制御するための、SSML でラップされたテキストなど) を完全に解決できます。With multiline support, you can have the Language Generation sub-system fully resolve a complex JSON or XML (like SSML wrapped text to control bot's spoken reply).

テンプレートのパラメーター化Parametrization of templates

コンテキストの再利用性を促進するために、テンプレートをパラメーター化できます。To aid with contextual reusability, templates can be parametrized. テンプレートに対するさまざまな呼び出し元は、展開解決で使用するさまざまな値を渡すことができます。Different callers to the template can pass in different values for use in expansion resolution.

# timeOfDayGreetingTemplate (param1)
- IF: ${param1 == 'morning'}
    - good morning
- ELSEIF: ${param1 == 'afternoon'}
    - good afternoon
    - good evening

# morningGreeting
- ${timeOfDayGreetingTemplate('morning')}

# timeOfDayGreeting
- ${timeOfDayGreetingTemplate(timeOfDay)}

外部参照のインポートImporting external references

言語生成テンプレートを個々のファイルに分割し、1 つのファイルから別のファイルのテンプレートを参照することができます。You can split your language generation templates into separate files and reference a template from one file in another. Markdown スタイルのリンクを使用して、別のファイルで定義されているテンプレートをインポートできます。You can use Markdown-style links to import templates defined in another file.

[Link description](filePathOrUri)

ターゲット ファイルで定義されているすべてのテンプレートが取り込まれます。All templates defined in the target file will be pulled in. 取り込まれるファイルにわたってテンプレート名が一意である (または # \<namespace>.\<templatename> を使用して名前空間が指定されている) ようにします。Ensure that your template names are unique (or namespaced with # \<namespace>.\<templatename>) across files being pulled in.


LG によって挿入される関数Functions injected by LG

アダプティブ式には、関数のカスタム セットを挿入する機能が用意されています。Adaptive expressions provide the ability to inject a custom set of functions. 詳細については、LG ライブラリから挿入される関数に関するページを参照してください。Read functions injected from the LG library for more information.


開発者は、パーサーオプションを設定して、入力の評価方法をさらにカスタマイズすることができます。Developers can set parser options to further customize how input is evaluated. > !# 表記を使用してパーサー オプションを設定します。Use the > !# notation to set parser options.


ファイルで見つかった最後の設定が、同じドキュメントで前に見つかったすべての設定よりも優先されます。The last setting found in the file trumps any prior setting found in the same document.

strict オプションStrict option

開発者は、null の評価結果に対して null の結果を許容しない場合、strict オプションを実装できます。Developers who do not want to allow a null result for a null evaluated result can implement the strict option. 次に、strict オプションの簡単な例を示します。Below is an example of a simple strict option:

> !# @strict = true
# template
- hi

strict オプションがオンの場合、null エラーはわかりやすいメッセージをスローします。If the strict option is on, null errors will throw a friendly message.

# welcome
- hi ${name}

name が null の場合、診断は、" 'name' evaluated to null. [welcome] Error occurred when evaluating '- hi ${name}'. ('name' が null に評価されました。[welcome] '- hi $ {name} ' の評価中にエラーが発生しました。) " になります。If name is null, the diagnostic would be 'name' evaluated to null. [welcome] Error occurred when evaluating '- hi ${name}'.. strict が false に設定されていか、設定されていない場合、互換性のある結果が得られます。If strict is set to false or not set, a compatible result will be given. 上のサンプルでは、hi null が生成されます。The above sample would produce hi null.

replaceNull オプションreplaceNull option

開発者は、 replaceNull オプションを使用して、評価された式の null 値を置き換えるデリゲートを作成できます。Developers can create delegates to replace null values in evaluated expressions by using the replaceNull option:

> !# @replaceNull = ${path} is undefined

上の例では、path 変数の null 入力は、 ${path} is undefined (${path} は未定義です) に置き換えられます。In the above example, the null input in the path variable would be replaced with ${path} is undefined. 次の入力で、user.name が null である場合は、The following input, where user.name is null: :

hi ${user.name}

hi user.name is undefined (やあ、user.name は未定義です) になります。Would result in hi user.name is undefined.

lineBreakStyle オプションlineBreakStyle option

開発者は lineBreakStyle オプションを使用して、LG システムで改行をレンダリングする方法のオプションを設定できます。Developers can set options for how the LG system renders line breaks using the lineBreakStyle option. 現在、次の 2 つのモードがサポートされています。Two modes are currently supported:

  • default: 複数行テキスト内の改行は、通常の改行になります。default: line breaks in multiline text create normal line breaks.
  • markdown: 複数行テキスト内の改行は、改行を作成するために自動的に 2 行に変換されますmarkdown: line breaks in multiline text will be automatically converted to two lines to create a newline

次の例は、lineBreakStyle オプションを markdown に設定する方法を示しています。The example below shows how to set the lineBreakStyle option to markdown:

> !# @lineBreakStyle = markdown

Namespace オプションNamespace option

エクスポートする LG テンプレートの名前空間を登録できます。You can register a namespace for the LG templates you want to export. 名前空間が指定されていない場合、名前空間は拡張子のないファイル名に設定されます。If there is no namespace specified, the namespace will be set to the filename without an extension.

次の例は、namespace オプションを foo に設定する方法を示しています。The example below shows how to set the namespace option to foo:

> !# @Namespace = foo

Exports オプションExports option

エクスポートする LG テンプレートの一覧を指定できます。You can specify a list of LG templates to export. エクスポートされたテンプレートは、事前に構築された関数と同様に呼び出すことができます。The exported templates can be called like prebuilt functions.

次の例は、exports オプションを template1, template2 に設定する方法を示しています。The example below shows how to set the exports option to template1, template2:

> !# @Namespace = foo
> !# @Exports = template1, template2

# template1(a, b)
- ${a + b}

# template2(a, b)
- ${join(a, b)}

これらのエクスポートされたテンプレートを呼び出すには、foo.template1(1,2), foo.template2(['a', 'b', 'c'], ',') を使用します。Use foo.template1(1,2), foo.template2(['a', 'b', 'c'], ',') to call these exported templates.

その他のリソースAdditional Resources