在 Microsoft Entra ID 中编写属性映射的表达式

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

表达式映射允许使用类似脚本的表达式自定义属性。 这样，就可以将本地数据转换为新的或不同的值。 例如，你可能希望将两个属性合并为一个属性，因为此单一属性由其中一个云应用程序使用。

以下文档将介绍用于转换数据的类似脚本的表达式。 这只是过程的一部分。 接下来，你将需要使用此表达式并将其置于租户的 Web 请求中。 有关该转换的详细信息，请参阅 转换

语法概述

属性映射表达式的语法让人想起 Visual Basic for Applications （VBA） 函数。

• 必须在函数方面定义整个表达式，该函数由名称后跟括号中的参数组成：
  FunctionName（<<argument 1>>，<<argument N>>）

• 可以相互嵌套函数。 例如：
  FunctionOne（FunctionTwo（<<argument1>>））

• 可以将三种不同类型的参数传递到函数中：

  1. 必须括在方括号中的属性。 例如：[attributeName]
  2. 字符串常量，必须用双引号引起来。 例如：“美国”
  3. 其他函数。 例如：FunctionOne（<<argument1>>、FunctionTwo（<<argument2>>））

• 对于字符串常量，如果需要字符串中的反斜杠（\）或引号（“”），则必须使用反斜杠 （\） 符号进行转义。 例如：“公司名称：\”Contoso\“”

函数列表

追加

功能：
Append（源、后缀）

描述：
获取源字符串值，并将后缀追加到它的末尾。

参数：

BitAnd

描述：
BitAnd 函数设置值的指定位。

语法：
num BitAnd(num value1, num value2)

• value1、value2：应该使用 AND 联接在一起的数字值

备注：
此函数将两个参数转换为二进制表示形式，并将位设置为：

• 0 - 如果 value1 和 value2 中的一个或两个相应位为 0
• 1 - 如果两个相应位均为 1。

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

示例：

BitAnd(&HF, &HF7)
返回 7，因为十六进制“F”和“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

描述：
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）

描述：
采用一种格式中的日期字符串，并将其转换为其他格式。

参数：

Guid

描述：
函数 GUID 生成新的随机 GUID

语法：
str Guid()

IIF

描述：
IIF 函数基于指定的条件返回一组可能值中的其中一个值。

语法：
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（分隔符、source1、source2、...）

描述：
Join（） 类似于 Append（），不同之处在于它可以将多个 源 字符串值合并为单个字符串，并且每个值将由 分隔符 字符串分隔。

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

参数：

左边

描述：
Left 函数从字符串左侧起返回指定的字符数。

语法：
str Left(str string, num NumChars)

• string：从中返回字符的字符串
• NumChar：标识从字符串开头（左侧）起返回的字符数的数字

备注：
包含字符串中第一个 numChars 字符的字符串：

• 如果 numChar = 0，则返回空字符串。
• 如果 numChars < 0，则返回输入字符串。
• 如果字符串为 null，则返回空字符串。

如果字符串包含的字符数比 numChars 中指定的数量少，则返回与该字符串相同的字符串（即，包含参数 1 中的所有字符）。

示例：
Left("John Doe", 3)
返回 Joh。

中间

功能：
中（源，开始，长度）

描述：
返回源值的子字符串。 子字符串是一个字符串，仅包含源字符串中的某些字符。

参数：

NormalizeDiacritics

功能：
NormalizeDiacritics（source）

描述：
需要一个字符串参数。 返回字符串，但使用任何音调字符替换为等效的非音调字符。 通常用于将包含音调字符（重音标记）的名字和姓氏转换为法律值，这些值可用于各种用户标识符，例如用户主体名称、SAM 帐户名称和电子邮件地址。

参数：

不

功能：
Not（source）

描述：
翻转 源的布尔值。 如果 源 值为“True”，则返回“False”。 否则，返回“True”。

参数：

RemoveDuplicates

描述：
RemoveDuplicates 函数使用多值字符串，并确保每个值都是唯一值。

语法：
mvstr RemoveDuplicates(mvstr attribute)

示例：
RemoveDuplicates([proxyAddresses])
返回净化的 proxyAddress 属性，其中所有重复值已被删除。

将

功能：
Replace（source， oldValue， regexPattern， regexGroupName， replacementValue， replacementAttributeName， template）

描述：
替换字符串中的值。 它的工作方式不同，具体取决于提供的参数：

• 提供 oldValue 和 replacementValue 时：

  • 将源中 oldValue 的所有匹配项替换为 replacementValue

• 提供 oldValue 和 模板 时：

  • 将模板中 oldValue 的所有匹配项替换为源值

• 提供 regexPattern 和 replacementValue 时：

  • 该函数将 regexPattern 应用于源字符串，可以使用正则表达式组名称构造 replacementValue 的字符串

• 如果 regexPattern、 regexGroupName、 replacementValue 提供：

  • 该函数将 regexPattern 应用于 源 字符串，并将匹配 regexGroupName 的所有值替换为 replacementValue

• 当 提供 regexPattern、 regexGroupName、 replacementAttributeName 时：

  • 如果源没有值，则返回源
  • 如果源具有值，该函数会将 regexPattern 应用于源字符串，并将匹配 regexGroupName 的所有值替换为与 replacementAttributeName 关联的值

参数：

SelectUniqueValue

功能：
SelectUniqueValue（uniqueValueRule1， uniqueValueRule2， uniqueValueRule3， ...）

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

参数：

SingleAppRoleAssignment

功能：
SingleAppRoleAssignment（[appRoleAssignments]）

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

参数：

Split

功能：
Split（源、分隔符）

描述：
使用指定的分隔符字符将字符串拆分为多值数组。

参数：

StringFromSid

描述：
StringFromSid 函数包含安全标识符的字节数组转换为字符串。

语法：
str StringFromSid(bin ObjectSID)

StripSpaces

功能：
StripSpaces（source）

描述：
从源字符串中删除所有空格（“ ”） 字符。

参数：

开关

功能：
Switch（source， defaultValue， key1， value1， key2， value2， ...）

描述：
当源值与键匹配时，返回该键的值。 如果 源 值与任何键不匹配，则返回 defaultValue。 键 和 值 参数必须始终成对。 函数始终需要偶数个参数。

参数：

ToLower

功能：
ToLower（源、区域性）

描述：
获取 源 字符串值，并使用指定的区域性规则将其转换为小写。 如果没有指定 区域性 信息，则它将使用固定区域性。

参数：

ToUpper

功能：
ToUpper（源、区域性）

描述：
获取 源 字符串值，并使用指定的区域性规则将其转换为大写。 如果没有指定 区域性 信息，则它将使用固定区域性。

参数：

修剪

描述：
Trim 函数从字符串中删除前导空格和尾随空格。

语法：
str Trim(str value)

示例：
Trim(" Test ")
返回 "test"。

Trim([proxyAddresses])
删除 proxyAddress 属性中每个值的前导空格和尾随空格。

字

描述：
基于描述要使用的分隔符与要返回的单词数的参数，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", , ,"", ,)

示例输入/输出：

• 输入 （邮件）：“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))

示例输入/输出：

• INPUT （givenName）： “John”
• INPUT （姓氏）： “Doe”
• 输出：“JohDoe”

从字符串中删除音调符号

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

表达式：
NormalizeDiacritics（[givenName]）

示例输入/输出：

• INPUT （givenName）： “Zoë”
• 输出：“Zoe”

将字符串拆分为多值数组

需要获取以逗号分隔的字符串列表，并将其拆分为可插入多值属性（如 Salesforce 的 PermissionSets 属性）的数组。 在此示例中，Microsoft Entra ID 中的 extensionAttribute5 中填充了权限集列表。

表达式：
Split（[extensionAttribute5]， “，”）

示例输入/输出：

• INPUT （extensionAttribute5）：“PermissionSetOne， PermissionSetTwo”
• 输出：[“PermissionSetOne”、“PermissionSetTwo”]

以特定格式将日期输出为字符串

你想要以特定格式将日期发送到 SaaS 应用程序。
例如，要设置 ServiceNow 的日期格式。

表达式：

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

示例输入/输出：

• INPUT （extensionAttribute1）：“20150123105347.1Z”
• 输出：“2015-01-23”

根据预定义的选项集替换值

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

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

示例输入/输出：

• 输入 （状态）：“QLD”
• 输出：“澳大利亚/布里斯班”

使用正则表达式替换字符

需要查找与正则表达式值匹配的字符并删除它们。

表达式：

Replace（[mailNickname]， ， “[a-zA-Z_]*”， ， “”， ， ）

示例输入/输出：

• INPUT （mailNickname： “john_doe72”
• 输出：“72”

将生成的 userPrincipalName （UPN） 值转换为小写

在下面的示例中，UPN 值是通过连接 PreferredFirstName 和 PreferredLastName 源字段生成的，ToLower 函数对生成的字符串执行作，以将所有字符转换为小写。

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

示例输入/输出：

• INPUT （PreferredFirstName）： “John”
• INPUT （PreferredLastName）： “Smith”
• 输出：“john.smith@contoso.com”

为 userPrincipalName （UPN） 属性生成唯一值

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

表达式：

    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")
    )

示例输入/输出：

• INPUT （PreferredFirstName）： “John”
• INPUT （PreferredLastName）： “Smith”
• 输出：“John.Smith@contoso.com”如果目录中尚不存在 UPN 值John.Smith@contoso.com
• 输出：“J.Smith@contoso.com”如果目录中已存在 UPN 值John.Smith@contoso.com
• 输出：“Jo.Smith@contoso.com”如果目录中已存在上述两个 UPN 值

后续步骤

• 什么是预配？
• 什么是 Microsoft Entra Cloud Sync？