配置云同步时,可以指定的属性映射类型之一是表达式映射。

通过表达式映射,可以使用类似于脚本的表达式来自定义属性。 这样,便可以将本地数据转换为新的或不同的值。 例如,你可能需要将两个属性合并成单个属性,因为某个云应用程序需使用此单个属性。

以下文档介绍了用于转换数据的类似于脚本的表达式。 这仅仅是转换过程的一部分。 接下来,需要使用此表达式并将其放入对租户发出的 Web 请求中。 有关详细信息,请参阅 转换

属性映射的表达式语法让人联想到 Visual Basic for Applications (VBA) 函数。

  • 必须定义整个表达式的函数,函数中的名称后跟带括号的参数:
    FunctionName( <<argument 1>> , <<argument N>> )

  • 函数之间可以相互嵌套。 例如:
    FunctionOne(FunctionTwo( <<argument1>> ))

  • 可以将三种不同类型的参数传递给函数:

  • 属性,必须括在方括号中。 例如:[attributeName]
  • 字符串常量必须括在双引号内。 例如:"美国"
  • 其他函数。 例如:FunctionOne( <<argument1>> , FunctionTwo( <<argument2>> ))
  • 对于字符串常量,如果字符串中需要反斜杠 ( \ ) 或引号 ( " ),则必须使用反斜杠 ( \ ) 符号进行转义。 例如:"Company name: \"Contoso\""

    SingleAppRoleAssignment 对于给定的应用程序,从向一个用户分配的所有 appRoleAssignments 列表中返回单个 appRoleAssignment。 使用指定的分隔符字符,将字符串拆分为多值数组。 StringFromSID StringFromSid 函数包含安全标识符的字节数组转换为字符串。 StripSpaces 从源字符串中删除所有空格 (" ") 字符。 Switch source 值与一个 key 匹配时,返回该 key 所对应的 value ToLower 采用源 字符串值并用指定的区域性规则将其转换为小写。 ToUpper 采用源 字符串值并用指定的区域性规则将其转换为大写。 Trim 函数从字符串中删除前导空格和尾随空格。 基于描述要使用的分隔符与要返回的单词数的参数,Word 函数返回字符串中包含的单词。

    换而言之,除了当两个参数的相应位均为 1 时之外,所有情况下均返回 0。

    BitAnd(&HF, &HF7) 返回 7,因为十六进制 "F" AND "F7" 的计算结果为此值。

    CBool

    CBool 函数基于计算的表达式返回布尔值

    bool CBool(exp Expression)

    如果表达式的计算结果为非零值,则 CBool 返回 True,否则返回 False。

    CBool([attrib1] = [attrib2])

    如果两个属性具有相同的值,则返回 True。

    ConvertFromBase64

    ConvertFromBase64 函数将指定的 base64 编码值转换为规则的字符串。

    str ConvertFromBase64(str source) - 假设采用 Unicode 编码
    str ConvertFromBase64(str source, enum Encoding)

  • source:Base64 编码的字符串
  • Encoding:Unicode、ASCII、UTF8
  • ConvertFromBase64("SABlAGwAbABvACAAdwBvAHIAbABkACEA")
    ConvertFromBase64("SGVsbG8gd29ybGQh", UTF8)

    这两个示例均返回 " Hello world! "

    ConvertToBase64

    ConvertToBase64 函数将字符串转换为 Unicode base64 字符串。
    将整数数组的值转换为其等效字符串表示形式,该表示形式使用 base 64 数字编码。

    str ConvertToBase64(str source)

    ConvertToBase64("Hello world!")
    返回 "SABlAGwAbABvACAAdwBvAHIAbABkACEA"

    ConvertToUTF8Hex

    ConvertToUTF8Hex 函数将字符串转换为 UTF8 Hex 编码的值。

    str ConvertToUTF8Hex(str source)

    Microsoft Entra ID 将此函数的输出格式用作 DN 属性格式。

    ConvertToUTF8Hex("Hello world!")
    返回 48656C6C6F20776F726C6421

    Count 函数返回多值属性中的元素数量

    num Count(mvstr attribute)

    CStr 函数转换为字符串数据类型。

    str CStr(num value)
    str CStr(ref value)
    str CStr(bool value)

  • value:可以是数字值、引用属性或布尔值。
  • CStr([dn])
    可能返回 "cn=Joe,dc=contoso,dc=com"

    DateFromNum

    DateFromNum 函数将 AD 的日期格式的值转换为 DateTime 类型。

    dt DateFromNum(num value)

    DateFromNum([lastLogonTimestamp])
    DateFromNum(129699324000000000)
    返回表示 2012-01-01 23:00:00 的 DateTime

    DNComponent

    DNComponent 函数返回从左边起的指定 DN 组件的值。

    str DNComponent(ref dn, num ComponentNumber)

  • dn:要解释的引用属性
  • ComponentNumber:要返回的 DN 中的组件
  • DNComponent(CRef([dn]),1)
    如果 dn 为 "cn=Joe,ou=…,",则返回 Joe

    Error 函数用于返回自定义错误。

    void Error(str ErrorMessage)

    IIF(IsPresent([accountName]),[accountName],Error("AccountName is required"))
    如果属性 accountName 不存在,则对象上引发错误。

    FormatDateTime

    FormatDateTime(source, inputFormat, outputFormat)

    从一种格式获取日期字符串并将其转换为不同的格式。

    必选/重复 String 源值的预期格式。 有关支持的格式,请参阅 /dotnet/standard/base-types/custom-date-and-time-format-strings outputFormat String 输出日期的格式。 var IIF(exp condition, var valueIfTrue, var valueIfFalse)

  • condition:计算结果可能为 true 或 false 的任何值或表达式。
  • valueIfTrue:如果条件计算结果为 true,则为返回值。
  • valueIfFalse:如果条件计算结果为 false,则为返回值。
  • IIF([employeeType]="Intern","t-" & [alias],[alias])
    如果用户是实习生,则返回用户的别名,同时将 "t-" 添加到其开头,否则按原样返回用户的别名。

    InStr

    InStr 函数查找字符串中第一次出现的子字符串

    num InStr(str stringcheck, str stringmatch)
    num InStr(str stringcheck, str stringmatch, num start)
    num InStr(str stringcheck, str stringmatch, num start, enum compare)

  • stringcheck:要搜索的字符串
  • stringmatch:要查找的字符串
  • start:查找子字符串的起始位置
  • compare:vbTextCompare 或 vbBinaryCompare
  • 返回其中已找到子字符串的位置,如果未找到,则返回 0。

    InStr("The quick brown fox","quick")
    计算结果为 5

    InStr("repEated","e",3,vbBinaryCompare)
    计算结果为 7

    IsNull

    如果表达式的计算结果为 Null,则 IsNull 函数返回 true。

    bool IsNull(var Expression)

    对于属性,Null 表示缺少属性。

    IsNull([displayName])
    如果属性没有在 CS 或 MV 中出现,则返回 True。

    IsNullOrEmpty

    如果表达式为 null 或空字符串,则 IsNullOrEmpty 函数返回 true。

    bool IsNullOrEmpty(var Expression)

    对于属性,如果属性不存在,或存在但为空字符串,此语法计算结果则为 True。
    此函数的逆函数命名为 IsPresent。

    IsNullOrEmpty([displayName])
    如果属性在 CS 或 MV 中没有出现或为空字符串,则返回 True。

    IsPresent

    如果表达式的计算结果为字符串,该字符串不是 Null 且不为空,则 IsPresent 函数返回 true。

    bool IsPresent(var expression)

    此函数的逆函数被命名为 IsNullOrEmpty。

    Switch(IsPresent([directManager]),[directManager], IsPresent([skiplevelManager]),[skiplevelManager], IsPresent([director]),[director])

    Item 函数返回多值字符串/属性中的一个项。

    var Item(mvstr attribute, num index)

  • attribute:多值属性
  • index:对多值字符串中某个项的索引。
  • Item 函数与 Contains 函数一起使用很有利,因为后一函数返回对多值属性中某个项的索引。

    如果索引超出界限,则引发错误。

    Mid(Item([proxyAddresses],Contains([proxyAddresses], "SMTP:")),6)
    返回主电子邮件地址。

    IsString

    如果表达式可以计算为字符串类型,则 IsString 函数计算结果为 True。

    bool IsString(var expression)

    用来确定 CStr() 是否能成功分析表达式。

    Join(separator, source1, source2, …)

    Join() 类似于 Append(),不同的是,它可以将多个 source 字符串值组合成单个字符串,每个值将由 separator 字符串分隔。

    如果其中一个源值是多值属性,那么该属性中的每个值都将联接在一起,由分隔符值分隔。

    必选/重复 NormalizeDiacritics(source)

    需要一个字符串参数。 返回字符串,但将任何标注字符替换为等效的非标注字符。 通常用于将包含标注字符(重音符号)的名字和姓氏转换为可用于各种用户标识符(例如用户主体名称、SAM 帐户名称和电子邮件地址)的合法值。

    必选/重复

    Replace

    Replace(source, oldValue, regexPattern, regexGroupName, replacementValue, replacementAttributeName, template)

    替换字符串中的值。 其工作方式取决于提供的参数:

  • 当提供了 oldValue replacementValue 时:

  • 将 source 中出现的所有 oldValue 替换为 replacementValue
  • 当提供了 oldValue template 时:

  • template 中出现的所有 oldValue 替换为 source
  • 如果已提供 regexPattern replacementValue

  • 函数将 regexPattern 应用到 source 字符串,你可以使用 regex 组名称来构造 replacementValue 的字符串。
  • 当提供 regexPattern regexGroupName replacementValue 时:

  • 函数将 regexPattern 应用到 source 字符串,并将与 regexGroupName 匹配的所有值替换为 replacementValue
  • 如果已提供 regexPattern regexGroupName replacementAttributeName

  • 如果 source 没有值,则返回 source
  • 如果 source 具有值,则函数会将 regexPattern 应用到 source 字符串,并将与 regexGroupName 匹配的所有值替换为与 replacementAttributeName 关联的值
  • 必选/重复 source 中要替换的值的正则表达式模式。 或者,当使用 replacementPropertyName 时,从 replacementPropertyName 中提取值的模式。 regexGroupName regexPattern 中的组名称。 仅当使用 replacementPropertyName 时,才会从 replacementPropertyName 中以 replacementValue 的形式提取此组的值。 replacementValue 用于替换旧值的新值。 replacementAttributeName 用于替换值的属性的名称 template 当提供 template 值时,会在模板中查找 oldValue 并将其替换为 source 值。

    SelectUniqueValue

    SelectUniqueValue(uniqueValueRule1, uniqueValueRule2, uniqueValueRule3, …)

    需要至少两个参数,这些参数是使用表达式定义的唯一值生成规则。 此函数会评估每个规则,然后在目标应用/目录中检查生成的值的唯一性。 将返回找到的第一个唯一值。 如果所有值都已存在于目标中,则会托管该条目并在审核日志中记录原因。 可以提供的参数数目没有上限。

  • 这是一个顶级函数,不能嵌套。
  • 此函数不能应用到具有匹配优先级的属性。
  • 此函数仅供用于创建条目。 将其与属性一起使用时,请将“应用映射” 属性设置为“仅在创建对象期间”。
  • 该函数当前仅支持用于“Workday 和 SuccessFactors 到 Active Directory 用户预配”。 此函数不可用于其他预配应用程序。
  • 必选/重复 SingleAppRoleAssignment([appRoleAssignments])

    对于给定的应用程序,从向一个用户分配的所有 appRoleAssignments 列表中返回单个 appRoleAssignment。 需要此函数才能将 appRoleAssignments 对象转换为单个角色名称字符串。 请注意,最佳做法是确保每次只向一个用户分配一个 appRoleAssignment,如果分配了多个角色,则返回的角色字符串可能是不可预测的。

    必选/重复 Switch(source, defaultValue, key1, value1, key2, value2, …)

    source 值与一个 key 匹配时,返回该 key 所对应的 value 。 当 source 值未与任何 key 匹配时,则返回 defaultValue Key value 参数必须始终成对出现。 该函数始终需要偶数个参数。

    必选/重复 基于描述要使用的分隔符与要返回的单词数的参数,Word 函数返回字符串中包含的单词。

    str Word(str string, num WordNumber, str delimiters)

  • string:从中返回单词的字符串。
  • WordNumber:标识应返回单词数的数字。
  • delimiter:表示应该用于标识单词的分隔符的字符串
  • 字符串中的字符由分隔符中其中一个字符分隔的每个字符串被标识为单词:

  • 如果数字 < 1,则返回空字符串。
  • 如果字符串为 null,则返回空字符串。
  • 如果字符串包含的单词少于应返回数字或字符串不包含由分隔符标识的任何单词,则返回空字符串。

    Word("The quick brown fox",3," ")
    返回 "brown"

    Word("This,string!has&many separators",3,",!&#")
    返回 "has"

    删除已知域名

    需要从用户的电子邮件中删除已知域名,以便获取用户名。
    例如,如果域为“contoso.com”,则可以使用以下表达式:

    Replace([mail], "@contoso.com", , ,"", ,)

    示例输入/输出:

  • 输入 (mail):“john.doe@contoso.com”
  • 输出:“john.doe”
  • 将常量后缀附加到用户名

    如果使用 Salesforce 沙箱,则可能需要在进行同步之前向所有用户名附加额外后缀。

    Append([userPrincipalName], ".test")

    示例输入/输出:

  • 输入 :(userPrincipalName):“John.Doe@contoso.com”
  • 输出 :“John.Doe@contoso.com.test”
  • 通过连接名字和姓氏部分来生成用户别名

    需要使用用户名字的前 3 个字母和用户姓氏的前 5 个字母来生成用户别名。

    Append(Mid([givenName], 1, 3), Mid([surname], 1, 5))

    示例输入/输出:

  • 输入 (givenName):“John”
  • 输入 (surname):“Doe”
  • 输出:“JohDoe”
  • 从字符串中删除音调符号

    需要将包含重音符号的字符替换为不包含重音符号的等效字符。

    NormalizeDiacritics([givenName])

    示例输入/输出:

  • 输入 (givenName):“Zoë”
  • 输出:“Zoe”
  • 将字符串拆分为多值数组

    你需要获取一个以逗号分隔的字符串列表,将它们拆分为一个数组,可以将该数组插入到多值属性中,例如 Salesforce 的 PermissionSets 属性。 在此示例中,Microsoft Entra ID 的 extensionAttribute5 中填充了一个权限集列表。

    Split([extensionAttribute5], ",")

    示例输入/输出:

  • 输入 (extensionAttribute5):"PermissionSetOne, PermissionSetTwo"
  • 输出:["PermissionSetOne", "PermissionSetTwo"]
  • 输出日期是一种特定格式的字符串

    需要以某种格式将日期发送到 SaaS 应用程序。
    例如,需要为 ServiceNow 设置日期格式。

    FormatDateTime([extensionAttribute1], "yyyyMMddHHmmss.fZ", "yyyy-MM-dd")

    示例输入/输出:

  • 输入 (extensionAttribute1):“20150123105347.1Z”
  • 输出:“2015-01-23”
  • 根据预定义的选项集替换值

    需要根据存储在 Microsoft Entra ID 中的状态代码来定义用户的时区。
    如果状态代码与任何预定义选项都不匹配,则使用默认值“澳大利亚/悉尼”。

    Switch([state], "Australia/Sydney", "NSW", "Australia/Sydney","QLD", "Australia/Brisbane", "SA", "Australia/Adelaide")

    示例输入/输出:

  • 输入 (state):“QLD”
  • 输出 :“澳大利亚/布里斯班”
  • 使用正则表达式替换字符

    你需要查找与正则表达式匹配的值并将其删除。

    Replace([mailNickname], , "[a-zA-Z_]*", , "", , )

    示例输入/输出:

  • INPUT (mailNickname: "john_doe72"
  • 输出 :"72"
  • 将生成的 userPrincipalName (UPN) 值转换为小写

    在下面的示例中,通过串联 PreferredFirstName 和 PreferredLastName 源字段生成 UPN 值,ToLower 函数对生成的字符串进行运算,将所有字符都转换为小写形式。

    ToLower(Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName], [PreferredLastName]))), "contoso.com"))

    示例输入/输出:

  • 输入 (PreferredFirstName):"John"
  • 输入 (PreferredLastName):"Smith"
  • 输出 :“john.smith@contoso.com”
  • 为 userPrincipalName (UPN) 属性生成唯一值

    你需要根据用户的名字、中间名和姓氏为 UPN 属性生成值,并在将该值分配给 UPN 属性之前在目标 AD 目录中检查其唯一性。

        SelectUniqueValue( 
            Join("@", NormalizeDiacritics(StripSpaces(Join(".",  [PreferredFirstName], [PreferredLastName]))), "contoso.com"), 
            Join("@", NormalizeDiacritics(StripSpaces(Join(".",  Mid([PreferredFirstName], 1, 1), [PreferredLastName]))), "contoso.com"),
            Join("@", NormalizeDiacritics(StripSpaces(Join(".",  Mid([PreferredFirstName], 1, 2), [PreferredLastName]))), "contoso.com")
    

    示例输入/输出:

  • 输入 (PreferredFirstName):"John"
  • 输入 (PreferredLastName):"Smith"
  • 输出:"John.Smith@contoso.com",如果 UPN 值 John.Smith@contoso.com 尚未存在于目录中
  • 输出:"J.Smith@contoso.com",如果 UPN 值 John.Smith@contoso.com 已存在于目录中
  • 输出:"Jo.Smith@contoso.com",如果上面的两个值已存在于目录中
  • 什么是预配?
  • 什么是 Microsoft Entra 云同步?
  •