条件性认知技能Conditional cognitive skill

条件技能可以实现需要使用布尔运算来确定要分配到输出的数据的 Azure 认知搜索方案。 The Conditional skill enables Azure Cognitive Search scenarios that require a Boolean operation to determine the data to assign to an output. 这些方案包括基于条件进行筛选、分配默认值以及合并数据。These scenarios include filtering, assigning a default value, and merging data based on a condition.

以下伪代码演示条件技能可以实现的功能:The following pseudocode demonstrates what the conditional skill accomplishes:

if (condition) 
    { output = whenTrue } 
else 
    { output = whenFalse } 

备注

此技能未绑定到 Azure 认知服务 API,使用它无需付费。This skill isn't bound to an Azure Cognitive Services API, and you aren't charged for using it. 但是,仍需附加认知服务资源,以替代局限于每日只能进行少量扩充的“免费”资源选项。However, you should still attach a Cognitive Services resource to override the "Free" resource option that limits you to a small number of enrichments per day.

@odata.type

Microsoft.Skills.Util.ConditionalSkillMicrosoft.Skills.Util.ConditionalSkill

求值的字段Evaluated fields

此技能非常特别,因为它的输入是求值的字段。This skill is special because its inputs are evaluated fields.

以下各项是表达式的有效值:The following items are valid values of an expression:

  • 批注路径(表达式中的路径必须以“$(”和“)”分隔)Annotation paths (paths in expressions must be delimited by "$(" and ")")
    示例:Examples:

        "= $(/document)"
        "= $(/document/content)"
    
  • 文本(字符串、数字、true、false、null)Literals (strings, numbers, true, false, null)
    示例:Examples:

       "= 'this is a string'"   // string (note the single quotation marks)
       "= 34"                   // number
       "= true"                 // Boolean
       "= null"                 // null value
    
  • 使用比较运算符(==、!=、>=、>、<=、<)的表达式Expressions that use comparison operators (==, !=, >=, >, <=, <)
    示例:Examples:

        "= $(/document/language) == 'en'"
        "= $(/document/sentiment) >= 0.5"
    
  • 使用布尔运算符(&&、||、!、^)的表达式Expressions that use Boolean operators (&&, ||, !, ^)
    示例:Examples:

        "= $(/document/language) == 'en' && $(/document/sentiment) > 0.5"
        "= !true"
    
  • 使用数字运算符(+、-、*、/、%)的表达式Expressions that use numeric operators (+, -, *, /, %)
    示例:Examples:

        "= $(/document/sentiment) + 0.5"         // addition
        "= $(/document/totalValue) * 1.10"       // multiplication
        "= $(/document/lengthInMeters) / 0.3049" // division
    

由于条件技能支持求值,因此可以在次要转换方案中使用它。Because the conditional skill supports evaluation, you can use it in minor-transformation scenarios. 有关示例,请参阅技能定义 4For example, see skill definition 4.

技能输入Skill inputs

输入区分大小写。Inputs are case-sensitive.

输入Input 说明Description
conditioncondition 此输入是一个求值字段,表示要求值的条件。This input is an evaluated field that represents the condition to evaluate. 此条件应求值为布尔值(truefalse)。This condition should evaluate to a Boolean value (true or false).
示例:Examples:
"= true""= true"
"= $(/document/language) =='fr'""= $(/document/language) =='fr'"
"= $(/document/pages/*/language) == $(/document/expectedLanguage)""= $(/document/pages/*/language) == $(/document/expectedLanguage)"
whenTruewhenTrue 此输入是一个求值字段,表示当条件求值为 true 时要返回的值。This input is an evaluated field that represents the value to return if the condition is evaluated to true. 常量字符串应括在单引号(' 和 ')中返回。Constants strings should be returned in single quotation marks (' and ').
示例值:Sample values:
"= 'contract'""= 'contract'"
"= $(/document/contractType)""= $(/document/contractType)"
"= $(/document/entities/*)""= $(/document/entities/*)"
whenFalsewhenFalse 此输入是一个求值字段,表示当条件求值为 false 时要返回的值。This input is an evaluated field that represents the value to return if the condition is evaluated to false.
示例值:Sample values:
"= 'contract'""= 'contract'"
"= $(/document/contractType)""= $(/document/contractType)"
"= $(/document/entities/*)""= $(/document/entities/*)"

技能输出Skill outputs

有一个简称为“输出”的输出。There's a single output that's simply called "output." 如果条件为 false,它会返回值 whenFalse;如果条件为 true,它会返回值 whenTrueIt returns the value whenFalse if the condition is false or whenTrue if the condition is true.

示例Examples

示例技能定义 1:筛选文档,以仅返回法语文档Sample skill definition 1: Filter documents to return only French documents

如果文档的语言为法语,则以下输出将返回句子数组 ("/document/frenchSentences")。The following output returns an array of sentences ("/document/frenchSentences") if the language of the document is French. 如果语言不是法语,值将设置为 nullIf the language isn't French, the value is set to null.

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == 'fr'" },
        { "name": "whenTrue", "source": "/document/sentences" },
        { "name": "whenFalse", "source": "= null" }
    ],
    "outputs": [ { "name": "output", "targetName": "frenchSentences" } ]
}

如果将“/document/frenchSentences”用作另一技能的上下文,仅当“/document/frenchSentences”未设置为 null 时,才运行该技能。 If "/document/frenchSentences" is used as the context of another skill, that skill only runs if "/document/frenchSentences" isn't set to null.

示例技能定义 2:为不存在的值设置默认值Sample skill definition 2: Set a default value for a value that doesn't exist

以下输出创建批注 ("/document/languageWithDefault"),该批注设置为文档的语言,如果未设置该语言,则该批注将设置为“es”。The following output creates an annotation ("/document/languageWithDefault") that's set to the language of the document or to "es" if the language isn't set.

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == null" },
        { "name": "whenTrue", "source": "= 'es'" },
        { "name": "whenFalse", "source": "= $(/document/language)" }
    ],
    "outputs": [ { "name": "output", "targetName": "languageWithDefault" } ]
}

示例技能定义 3:将两个字段中的值合并为一个Sample skill definition 3: Merge values from two fields into one

在此示例中,某些句子包含 frenchSentiment 属性。In this example, some sentences have a frenchSentiment property. 每当 frenchSentiment 属性为 null 时,我们就要使用 englishSentiment 值。Whenever the frenchSentiment property is null, we want to use the englishSentiment value. 将输出分配到名为 sentiment 的成员 ("/document/sentiment/*/sentiment")。We assign the output to a member that's called sentiment ("/document/sentiment/*/sentiment").

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document/sentences/*",
    "inputs": [
        { "name": "condition", "source": "= $(/document/sentences/*/frenchSentiment) == null" },
        { "name": "whenTrue", "source": "/document/sentences/*/englishSentiment" },
        { "name": "whenFalse", "source": "/document/sentences/*/frenchSentiment" }
    ],
    "outputs": [ { "name": "output", "targetName": "sentiment" } ]
}

转换示例Transformation example

示例技能定义 4:基于单个字段进行数据转换Sample skill definition 4: Data transformation on a single field

在此示例中,我们将收到介于 0 和 1 之间的情绪。 In this example, we receive a sentiment that's between 0 and 1. 我们希望将此值转换为 -1 到 1。We want to transform it to be between -1 and 1. 可以使用条件技能来实现这种次要转换。We can use the conditional skill to do this minor transformation.

在此示例中,我们未使用技能的条件性,因为该条件始终为 trueIn this example, we don't use the conditional aspect of the skill because the condition is always true.

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document/sentences/*",
    "inputs": [
        { "name": "condition", "source": "= true" },
        { "name": "whenTrue", "source": "= $(/document/sentences/*/sentiment) * 2 - 1" },
        { "name": "whenFalse", "source": "= 0" }
    ],
    "outputs": [ { "name": "output", "targetName": "normalizedSentiment" } ]
}

特殊注意事项Special considerations

某些参数将会求值,因此需要特别谨慎地遵循阐述的模式。Some parameters are evaluated, so you need to be especially careful to follow the documented pattern. 表达式必须以等号开头。Expressions must start with an equals sign. 路径必须以“$(”和“)”分隔。A path must be delimited by "$(" and ")". 请务必将字符串放在单引号中。Make sure to put strings in single quotation marks. 这有助于求值程序区分字符串与实际的路径和运算符。That helps the evaluator distinguish between strings and actual paths and operators. 此外,请务必在运算符的两侧添加空格(例如,在路径中使用 "*" 表示不是乘号)。Also, make sure to put white space around operators (for instance, a "*" in a path means something different than multiply).

后续步骤Next steps