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

• 对于字符串常量，如果字符串中需要反斜杠 ( \ ) 或引号 ( " )，则必须使用反斜杠 ( \ ) 符号进行转义。 例如 "Company name: \"Contoso\""

函数列表

追加

函数：
Append（源、后缀）

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

参数：

BitAnd

Description:
BitAnd 函数设置值上的指定位。

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

• value1， value2： numeric values that be and'ed together

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

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

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

Example:

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

CBool

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

语法：
bool CBool(exp Expression)

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

Example:
CBool([attrib1] = [attrib2])

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

ConvertFromBase64

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

语法：
str ConvertFromBase64(str source) - 假定 Unicode 用于编码
str ConvertFromBase64(str source, enum Encoding)

• 源：Base64 编码字符串
• 编码：Unicode、ASCII、UTF8

示例
ConvertFromBase64("SABlAGwAbABvACAAdwBvAHIAbABkACEA")
ConvertFromBase64("SGVsbG8gd29ybGQh", UTF8)

这两个示例都返回“Hello world！”

ConvertToBase64

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

语法：
str ConvertToBase64(str source)

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

ConvertToUTF8Hex

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

语法：
str ConvertToUTF8Hex(str source)

备注：
此函数的输出格式由 Microsoft Entra ID 用作 DN 属性格式。

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

计数

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

语法：
num Count(mvstr attribute)

CStr

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

语法：
str CStr(num value)
str CStr(ref value)
str CStr(bool value)

• value：可以是数值、引用属性或布尔值。

Example:
CStr([dn])
可能会返回“cn=Joe，dc=contoso，dc=com”

DateFromNum

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

语法：
dt DateFromNum(num value)

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

DNComponent

Description:
DNComponent 函数返回从左侧返回的指定 DN 组件的值。

语法：
str DNComponent(ref dn, num ComponentNumber)

• dn：要解释的引用属性
• ComponentNumber：要返回的 DN 中的组件

Example:
DNComponent(CRef([dn]),1)
如果 dn 为“cn=Joe，ou=...”，则返回 Joe

Error

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

语法：
void Error(str ErrorMessage)

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

FormatDateTime

函数：
FormatDateTime（source， inputFormat， outputFormat）

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

参数：

Guid

Description:
函数 Guid 生成新的随机 GUID

语法：
str Guid()

IIF

Description:
IIF 函数根据指定的条件返回一组可能的值之一。

语法：
var IIF(exp condition, var valueIfTrue, var valueIfFalse)

• 条件：可计算为 true 或 false 的任何值或表达式。
• valueIfTrue：如果条件的计算结果为 true，则返回的值。
• valueIfFalse：如果条件的计算结果为 false，则返回的值。

Example:
IIF([employeeType]="Intern","t-" & [alias],[alias])
如果用户是实习生，则返回添加到其开头的“t-”的用户的别名，否则返回用户的别名，如下所示。

InStr

Description:
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。

Example:
InStr("The quick brown fox","quick")
求值为 5

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

IsNull

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

语法：
bool IsNull(var Expression)

备注：
对于属性，Null 表示缺少属性。

Example:
IsNull([displayName])
如果 CS 或 MV 中不存在该属性，则返回 True。

IsNullOrEmpty

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

语法：
bool IsNullOrEmpty(var Expression)

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

Example:
IsNullOrEmpty([displayName])
如果属性不存在或 CS 或 MV 中为空字符串，则返回 True。

IsPresent

Description:
如果表达式的计算结果为非 Null 且不为空的字符串，则 IsPresent 函数返回 true。

语法：
bool IsPresent(var expression)

备注：
此函数的逆函数被命名为 IsNullOrEmpty。

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

物品

Description:
Item 函数从多值字符串/属性返回一项。

语法：
var Item(mvstr attribute, num index)

• attribute：多值属性
• index：索引到多值字符串中的项。

备注：
Item 函数与 Contains 函数一起很有用，因为后一个函数将索引返回到多值属性中的项。

如果索引超出边界，则引发错误。

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

IsString

Description:
如果表达式的计算结果为字符串类型，则 IsString 函数的计算结果为 True。

语法：
bool IsString(var expression)

备注：
用于确定 CStr（） 是否可以成功分析表达式。

加入

函数：
Join（分隔符、source1、source2、...）

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

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

参数：

左边

Description:
Left 函数从字符串左侧返回指定的字符数。

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

• string：要从中返回字符的字符串
• NumChars：一个数字，用于标识要从字符串开头（左）返回的字符数

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

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

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

Example:
Left("John Doe", 3)
返回 Joh。

中间

函数：
中（源，开始，长度）

Description:
返回源值的子字符串。 子字符串是一个只包含源字符串中某些字符的字符串。

参数：

NormalizeDiacritics

函数：
NormalizeDiacritics（source）

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

参数：

不

函数：
Not（source）

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

参数：

RemoveDuplicates

Description:
RemoveDuplicates 函数采用多值字符串，并确保每个值是唯一的。

语法：
mvstr RemoveDuplicates(mvstr attribute)

Example:
RemoveDuplicates([proxyAddresses])
返回已删除所有重复值的清理 proxyAddress 属性。

替换

函数：
Replace（source， oldValue， regexPattern， regexGroupName， replacementValue， replacementAttributeName， template）

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

• 当提供了 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：

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

参数：

SelectUniqueValue

函数：
SelectUniqueValue（uniqueValueRule1， uniqueValueRule2， uniqueValueRule3， ...）

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

参数：

SingleAppRoleAssignment

函数：
SingleAppRoleAssignment（[appRoleAssignments]）

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

参数：

拆分

函数：
Split（源、分隔符）

Description:
使用指定的分隔符字符将字符串拆分为多值数组。

参数：

StringFromSid

Description:
StringFromSid 函数将包含安全标识符的字节数组转换为字符串。

语法：
str StringFromSid(bin ObjectSID)

StripSpaces

函数：
StripSpaces（source）

Description:
从源字符串中删除所有空格（“ ”） 字符。

参数：

开关

函数：
Switch（source， defaultValue， key1， value1， key2， value2， ...）

Description:
当源值与键匹配时，返回该键的值。 当 source 值未与任何 key 匹配时，则返回 defaultValue。 Key 和 value 参数必须始终成对出现。 该函数始终需要偶数个参数。

参数：

ToLower

函数：
ToLower（源、区域性）

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

参数：

ToUpper

函数：
ToUpper（源、区域性）

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

参数：

修剪

Description:
Trim 函数从字符串中删除前导空格和尾随空格。

语法：
str Trim(str value)

Example:
Trim(" Test ")
返回“Test”。

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

Word

Description:
Word 函数根据描述要使用的分隔符和要返回的字号的参数返回字符串中包含的单词。

语法：
str Word(str string, num WordNumber, str delimiters)

• string：要从中返回单词的字符串。
• WordNumber：标识应返回的字号的数字。
• 分隔符：表示应用于标识单词的分隔符的字符串

备注：
字符串中的字符由分隔符中其中一个字符分隔的每个字符串被标识为单词：

• 如果数字 < 1，则返回空字符串。
• 如果字符串为 null，则返回空字符串。

如果字符串包含小于数字单词，或者字符串不包含由分隔符标识的任何单词，则返回空字符串。

Example:
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) 值转换为小写

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

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

示例输入/输出：

• 输入 (PreferredFirstName)："John"
• 输入 (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")
    )

示例输入/输出：

• 输入 (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 Cloud Sync？