在 Microsoft Entra ID 中撰寫屬性對應表達式的參考

當您設定布建至 SaaS 應用程式時,您可以指定的其中一種屬性對應類型是表達式對應。 針對這些對應,您必須撰寫類似腳本的表達式,以便將使用者的數據轉換成 SaaS 應用程式更容易接受的格式。

語法概觀

屬性對應表達式的語法讓人想起 Visual Basic for Applications (VBA) 函式。

  • 整個表達式必須以函式來定義,其中包含名稱,後面接著括弧中的自變數: FunctionName(<<argument 1>><<argument N>>

  • 您可以在彼此內巢狀函式。 例如: FunctionOne(FunctionTwo(<<argument1>>))

  • 您可以將三種不同類型的自變數傳遞至函式:

    1. 屬性,必須以方括弧括住。 例如:[attributeName]
    2. 字串常數,必須以雙引弧括住。 例如:“美國”
    3. 其他函式。 例如:FunctionOne(<<argument1>>, FunctionTwo(<<argument2>>))
  • 對於字串常數,如果您需要字串中的反斜杠(\ ) 或引號 (“ ),則必須使用反斜杠 (\) 符號逸出。 例如:“公司名稱:\”Contoso\“”

  • 語法會區分大小寫,在函式中輸入字串時,必須將其視為字串,而複製會直接從此處貼上它們。

函式清單

AppendAppRoleAssignmentsComplexBitAndCBoolCDateCoalesceConvertToBase64ConvertToUTF8HexCountCStrdateAdddateDiffDateFromNumFormatDateTimeGuidIgnoreFlowIfNullOrEmpty IIFinStrIsNullIsNullOrEmptyIsPresentIsStringItemJoinLeftNormalizeDiacriticsnotnowNumFromDate PCaseRandomStringRedactRemoveDuplicatesreplaceSelectUniqueValueSingleAppRoleAssignmentSplitStripSpacesswitchToLowerToUpper Word


附加

函式: Append(source,後綴)

描述: 取得來源字串值,並將後綴附加至它的結尾。

參數:

名稱 必要/重複 類型 備註
source 必要 String 通常來源物件的屬性名稱。
尾碼 必要 String 您要附加至來源值結尾的字串。

將常數後綴附加至用戶名稱

範例:如果您使用 Salesforce 沙箱,您可能需要先將另一個後綴附加至所有用戶名稱,再進行同步處理。

Expression:Append([userPrincipalName], ".test")

範例輸入/輸出:

  • INPUT: (userPrincipalName): “John.Doe@contoso.com”
  • 輸出:“John.Doe@contoso.com.test”

AppRoleAssignmentsComplex

函式: AppRoleAssignmentsComplex([appRoleAssignments])

描述: 用來為用戶設定多個角色。 如需詳細的使用方式,請參閱 教學課程 - 在 Microsoft Entra ID 中自定義 SaaS 應用程式的使用者布建屬性對應。

參數:

名稱 必要/重複 類型 備註
[appRoleAssignments] 必要 String [appRoleAssignments] 物件。

BitAnd

函式: BitAnd(value1,value2)

描述: 此函式會將這兩個參數轉換成二進位表示法,並將位設定為:

  • 0 - 如果 value1 和 value2 中的一個或兩個對應位都是 0
  • 1 - 如果這兩個對應的位都是 1。

換句話說,它會在所有情況下傳回 0,但兩個參數的對應位都是 1。

參數:

名稱 必要/重複 類型 備註
value1 必要 數量 應為 AND』ed 且值為 2 的數值
value2 必要 數量 應為 AND』ed 且值為 1 的數值

範例:BitAnd(&HF, &HF7)

11110111 AND 00000111 = 00000111,因此 BitAnd 會傳回 7,00000111的二進位值。


CBool

功能:CBool(Expression)

描述:CBool 根據評估的表達式傳回布爾值。 如果表達式評估為非零值,則會 CBool 傳回 True,否則會傳 回 False

參數:

名稱 必要/重複 類型 備註
運算式 必要 expression 任何有效的表達式

範例:CBool([attribute1] = [attribute2])
如果兩個屬性都有相同的值,則傳回 True。


CDate

功能:
CDate(expression)

描述
CDate 函式會從字串傳回 UTC DateTime。 DateTime 不是原生屬性類型,但可以在 FormatDateTimeDateAdd 等日期函式中使用。

參數:

名稱 必要/重複 類型 備註
運算式 必要 運算式 任何代表日期/時間的有效字串。 如需支援的格式,請參閱 .NET 自定義日期和時間格式字串

備註:
傳回的字串一律為UTC,並遵循 M/d/yyyy h:mm:ss tt 格式

範例 1:
CDate([StatusHireDate])
範例輸入/輸出:

  • INPUT (StatusHireDate): “2020-03-16-07:00”
  • 輸出:「2020/3/16 7:00:00 AM」 <-- 請注意傳回上述 DateTime 的 UTC 對等專案

範例 2:
CDate("2021-06-30+08:00")
範例輸入/輸出:

  • 輸入:“2021-06-30+08:00”
  • 輸出:「2021 年 6 月 29 日下午 4:00:00」 <- 請注意傳回上述 DateTime 的 UTC 對等專案

範例 3:
CDate("2009-06-15T01:45:30-07:00")
範例輸入/輸出:

  • 輸入:“2009-06-15T01:45:30-07:00”
  • 輸出:「2009/6/15 8:45:30 AM」 <-- 請注意傳回上述 DateTime 的 UTC 對等專案

Coalesce

函式: Coalesce(source1, source2, ..., defaultValue)

描述: 傳回非 NULL 的第一個來源值。 如果所有自變數都是 NULL 且 defaultValue 存在,則會傳回 defaultValue。 如果所有自變數都是 NULL 且 defaultValue 不存在,Coalesce 會傳回 NULL。

參數:

名稱 必要/重複 類型 備註
source1 sourceN 必要 String 必要、可變次數。 通常來源物件的屬性名稱。
defaultValue 選擇性 String 當所有來源值都是 NULL 時要使用的預設值。 可以是空字串 (“” )。

如果不是 NULL,則為 Flow 郵件值,否則為 flow userPrincipalName

範例:如果您想要在郵件屬性存在時流動郵件屬性。 如果不是,您想要改為流動 userPrincipalName 的值。

Expression:Coalesce([mail],[userPrincipalName])

範例輸入/輸出:

  • 輸入 (郵件): NULL
  • INPUT (userPrincipalName): “John.Doe@contoso.com”
  • 輸出:“John.Doe@contoso.com”

ConvertToBase64

函式: ConvertToBase64(來源)

描述: ConvertToBase64 函式會將字串轉換成 Unicode base64 字串。

參數:

名稱 必要/重複 類型 備註
source 必要 String 要轉換成base 64的字串

範例:ConvertToBase64("Hello world!")

傳回 “SABlAGwAbABvACAAdwBvAHIAbABkACEA”


ConvertToUTF8Hex

函式: ConvertToUTF8Hex(來源)

描述: ConvertToUTF8Hex 函式會將字串轉換成 UTF8 十六進位編碼值。

參數:

名稱 必要/重複 類型 備註
source 必要 String 要轉換成UTF8 Hex的字串

範例:ConvertToUTF8Hex("Hello world!")

傳回 48656C6C6F20776F726C6421


計數

函式: Count(attribute)

描述: Count 函式會傳回多重值屬性中的元素數目

參數:

名稱 必要/重複 類型 備註
attribute 必要 屬性 將計算元素的多重值屬性

CStr

函式: CStr(value)

描述: CStr 函式會將值轉換成字串數據類型。

參數:

名稱 必要/重複 類型 備註
value 必要 numeric、reference 或 boolean 可以是數值、參考屬性或布爾值。

範例:CStr([dn])

傳回 “cn=Joe,dc=contoso,dc=com”


DateAdd

功能:
DateAdd(interval, value, dateTime)

描述
傳回日期/時間字串,表示已加入指定時間間隔的日期。 傳回的日期格式為: M/d/yyyy h:mm:ss tt

參數:

名稱 必要/重複 類型 備註
區間 必要 String 您要新增的時間間隔。 請參閱下表下方的已接受值。
value 必要 數值 您要新增的單位數目。 它可以是正面的(在未來取得日期)或負數(過去取得日期)。
dateTime 必要 Datetime DateTime 代表加入間隔的日期。

傳遞日期字串做為輸入時,請使用 CDate 函式來包裝 datetime 字串。 若要以 UTC 取得系統時間,請使用 Now 函式。

間隔字串必須具有下列其中一個值:

  • yyyy Year
  • m Month
  • d 日
  • ww 周
  • h 小時
  • n 分鐘
  • s Second

範例 1:根據 Workday 中的傳入 StatusHireDate 產生日期值
DateAdd("d", 7, CDate([StatusHireDate]))

範例 interval value dateTime (變數 StatusHireDate 的值) output
新增 7 天至雇用日期 "d" 7 2012-03-16-07:00 2012/3/23 上午 7:00:00
取得僱用日期前十天的日期 "d" -10 2012-03-16-07:00 2012/3/6 上午 7:00:00
新增兩周至僱用日期 “ww” 2 2012-03-16-07:00 2012 年 3 月 30 日上午 7:00:00
新增10個月的雇用日期 "m" 10 2012-03-16-07:00 2013 年 1 月 16 日上午 7:00:00
新增兩年到僱用日期 "yyyy" 2 2012-03-16-07:00 2014/3/16 上午 7:00:00

DateDiff

功能:
DateDiff(interval, date1, date2)

描述
此函式會 使用 interval 參數傳回數位,指出兩個輸入日期之間的差異。 它會傳回

  • 如果 date2 > date1 為正數,
  • 如果 date2 < date1 為負數,
  • 0 如果 date2 == date1

參數:

名稱 必要/選用 類型 備註
區間 必要 String 用於計算差異的時間間隔。
date1 必要 Datetime DateTime 代表有效的日期。
date2 必要 Datetime DateTime 代表有效的日期。

傳遞日期字串做為輸入時,請使用 CDate 函式來包裝 datetime 字串。 若要以 UTC 取得系統時間,請使用 Now 函式。

間隔字串必須具有下列其中一個值:

  • yyyy Year
  • m Month
  • d 日
  • ww 周
  • h 小時
  • n 分鐘
  • s Second

範例 1:比較目前日期與 Workday 與不同間隔的雇用日期
DateDiff("d", Now(), CDate([StatusHireDate]))

範例 interval date1 date2 output
兩個日期之間的日數正差 d 2021-08-18+08:00 2021-08-31+08:00 13
兩個日期之間的天數負差 d 2021/8/25 下午 5:41:18 2012-03-16-07:00 -3449
兩個日期之間的周數差異 ww 2021/8/25 下午 5:41:18 2012-03-16-07:00 -493
兩個日期之間的月份差異 m 2021/8/25 下午 5:41:18 2012-03-16-07:00 -113
兩個日期之間的年份差異 yyyy 2021/8/25 下午 5:41:18 2012-03-16-07:00 -9
當兩個日期都相同時的差異 d 2021-08-31+08:00 2021-08-31+08:00 0
兩個日期之間的小時差異 小時 2021-08-24 2021-08-25 24
兩個日期之間的分鐘數差異 n 2021-08-24 2021-08-25 1440
兩個日期之間的秒數差異 s 2021-08-24 2021-08-25 86400

範例 2:結合 DateDiff 與 IIF 函式來設定屬性值
如果帳戶在 Workday 中為作用中,則只有當雇用日期在接下來五天內,才將使用者的 accountEnabled 屬性設定為 True。

Switch([Active], , 
  "1", IIF(DateDiff("d", Now(), CDate([StatusHireDate])) > 5, "False", "True"), 
  "0", "False")

DateFromNum

函式: DateFromNum(value)

描述: DateFromNum 函式會將AD 日期格式中的值轉換成DateTime類型。

參數:

名稱 必要/重複 類型 備註
value 必要 Date 要轉換成 DateTime 類型的 AD 日期

範例:DateFromNum([lastLogonTimestamp])

DateFromNum(129699324000000000)

會傳回 DateTime,代表 2012 年 1 月 1 日下午 11:00。


FormatDateTime

函式: FormatDateTime(source、dateTimeStyles、inputFormat、outputFormat)

描述: 採用一種格式的日期字串,並將其轉換成不同的格式。

參數:

名稱 必要/重複 類型 備註
source 必要 String 通常來源物件的屬性名稱。
dateTimeStyles 選擇性 String 使用此參數來指定自定義某些日期和時間剖析方法之字串剖析的格式選項。 如需支援的值,請參閱 DateTimeStyles 檔。如果保留空白,使用的預設值為 DateTimeStyles.RoundtripKind、DateTimeStyles.AllowLeadingWhite、DateTimeStyles.AllowTrailingWhite
inputFormat 必要 String 來源值的預期格式。 如需支援的格式,請參閱 .NET 自定義日期和時間格式字串
outputFormat 必要 String 輸出日期的格式。

以特定格式將日期輸出為字串

範例:您想要以特定格式將日期傳送至 SaaS 應用程式,例如 ServiceNow。 您可以考慮使用下列表示式。

Expression:

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

範例輸入/輸出:

  • INPUT (extensionAttribute1): “20150123105347.1Z”
  • 輸出:“2015-01-23”

GUID

函式: Guid()

描述: 函式 Guid 會產生新的隨機 GUID

範例:
Guid()
範例輸出:“1088051a-cd4b-4288-84f8-e02042ca72bc”


IgnoreFlowIfNullOrEmpty

函式: IgnoreFlowIfNullOrEmpty(expression)

描述: IgnoreFlowIfNullOrEmpty 函式會指示布建服務忽略屬性,並在封閉函式或屬性為 NULL 或空白時從流程卸除該屬性。

參數:

名稱 必要/重複 類型 備註
運算式 必要 運算式 要評估的表達式

範例 1:如果屬性為 Null,請勿流動屬性
IgnoreFlowIfNullOrEmpty([department])
如果布建流程為 Null 或空白,則上述表達式會從布建流程卸除部門屬性。

範例 2:如果表示式對應評估為空字串或 Null,則不要流動屬性
假設 SuccessFactors 屬性前置詞會使用下列表達式對應至 內部部署的 Active Directory 属性 personalTitle
IgnoreFlowIfNullOrEmpty(Switch([prefix], "", "3443", "Dr.", "3444", "Prof.", "3445", "Prof. Dr."))
上述表達式會先評估 Switch 函式。 如果前置詞屬性沒有 Switch 函式中所列的任何值,則 Switch 會傳回空字串,而且布建流程中不會包含屬性 personalTitle,以 內部部署的 Active Directory。


IIF

函式: IIF(condition,valueIfTrue,valueIfFalse)

描述: IIF 函式會根據指定的條件傳回一組可能值。

參數:

名稱 必要/重複 類型 備註
condition 必要 變數或表達式 任何可評估為 true 或 false 的值或表達式。
valueIfTrue 必要 變數或字串 如果條件評估為 true,則傳回的值。
valueIfFalse 必要 變數或字串 如果條件評估為 false,則傳回的值。

下列比較運算子可用於 條件中:

  • 等於 (=) 且不等於 (<>)
  • 大於 (>) 且大於等於 (>=)
  • 小於 (<) 和小於等於 (<=)

範例: 如果 country=“USA”,請將目標屬性值設定為來源國家/地區屬性,否則請將目標屬性值設定為來源部門屬性。 IIF([country]="USA",[country],[department])

已知的限制

本節包含 IIF 函式的限制和因應措施。 如需針對使用者建立問題進行疑難解答的資訊,請參閱 建立失敗,因為 Null /空白值

  • IIF 函式目前不支援 AND 和 OR 邏輯運算符。
  • 若要實作 AND 邏輯,請使用沿著 trueValue 路徑鏈結的巢狀 IIF 語句。 範例:如果 country=“USA” and state=“CA”, return value “True”, else return “False”。 IIF([country]="USA",IIF([state]="CA","True","False"),"False")
  • 若要實作 OR 邏輯,請使用沿著 falseValue 路徑鏈結的巢狀 IIF 語句。 範例:如果 country=“USA” 或 state=“CA”, return value “True”, else return “False”。 IIF([country]="USA","True",IIF([state]="CA","True","False"))
  • 如果 IIF 函式中使用的來源屬性是空的或 Null,則條件檢查會失敗。
    • 不支援的 IIF 運算式範例:
      • IIF([country]="","Other",[country])
      • IIF(IsNullOrEmpty([country]),"Other",[country])
      • IIF(IsPresent([country]),[country],"Other")
    • 建議的因應措施:使用 Switch 函式來檢查空白/Null 值。 範例:如果 country 屬性是空的,請設定值 “Other”。 如果存在,請將國家/地區屬性值傳遞至目標屬性。
      • Switch([country],[country],"","Other")

InStr

函式: InStr(value1, value2, start, compareType)

描述: InStr 函式會尋找字串中第一個出現的子字串

參數:

名稱 必要/重複 類型 備註
value1 必要 String 要搜尋的字串
value2 必要 String 要找到的字串
start 選擇性 整數 尋找子字串的起始位置
compareType 選擇性 列舉 可以是 vbTextCompare 或 vbBinaryCompare

範例:InStr("The quick brown fox","quick")

評估為 5

InStr("repEated","e",3,vbBinaryCompare)

評估為 7


IsNull

函式: IsNull(Expression)

描述: 如果表達式評估為 Null,則 IsNull 函式會傳回 true。 針對屬性,Null 會以沒有 屬性來表示。

參數:

名稱 必要/重複 類型 備註
運算式 必要 運算式 要評估的表達式

範例:IsNull([displayName])

如果屬性不存在,則傳回 True。


IsNullorEmpty

函式: IsNullOrEmpty(Expression)

描述: 如果表達式為 Null 或空字串,則 IsNullOrEmpty 函式會傳回 true。 如果是屬性,如果屬性不存在或存在,但為空字串,則此屬性會評估為 True。 此函式的反函數名稱為IsPresent。

參數:

名稱 必要/重複 類型 備註
運算式 必要 運算式 要評估的表達式

範例:IsNullOrEmpty([displayName])

如果屬性不存在或為空字串,則傳回 True。


IsPresent

函式: IsPresent(Expression)

描述: 如果表達式評估為不是 Null 且不是空的字串,則 IsPresent 函式會傳回 true。 此函式的反向名稱為IsNullOrEmpty。

參數:

名稱 必要/重複 類型 備註
運算式 必要 運算式 要評估的表達式

範例:Switch(IsPresent([directManager]),[directManager], IsPresent([skiplevelManager]),[skiplevelManager], IsPresent([director]),[director])


IsString

函式: IsString(Expression)

描述: 如果表達式可以評估為字串類型,則IsString函式會評估為True。

參數:

名稱 必要/重複 類型 備註
運算式 必要 運算式 要評估的表達式

項目

函式: Item(attribute, index)

描述: Item 函式會從多重值字串/屬性傳回一個專案。

參數:

名稱 必要/重複 類型 備註
attribute 必要 屬性 要搜尋的多值屬性
index 必要 整數 索引至多重值字串中的專案

範例:Item([proxyAddresses], 1) 傳回多重值屬性中的第一個專案。 不應該使用索引 0。


聯結

函式: Join(separator, source1, source2, ...)

描述: Join() 類似於 Append(),不同之處在於它可以將多個 來源 字串值合併成單一 字串,而且每個值都會以分隔符 字串分隔。

如果其中一個來源值是多重值屬性,則該屬性中的每個值都會聯結在一起,並以分隔符值分隔。

參數:

名稱 必要/重複 類型 備註
separator 必要 String 字串,用來在串連成一個字串時分隔來源值。 如果不需要分隔符,可以是 “ ” ”
source1 sourceN 必要、可變次數 String 要聯結在一起的字串值。

Left

函式: Left(String,NumChars)

描述: Left 函式會從字串左邊傳回指定的字元數。 如果 numChars = 0,則傳回空字串。 如果為 numChars < 0,則傳回輸入字串。 如果 string 為 null,則傳回空字串。 如果 string 包含的字元少於 numChars 中指定的數位,則會傳回與字串相同的字串(也就是包含參數 1 中的所有字元)。

參數:

名稱 必要/重複 類型 備註
String 必要 屬性 要傳回字元的來源字串
NumChars 必要 整數 數字,識別要從字串開頭 (左) 傳回的字元數

範例:Left("John Doe", 3)

會傳回 「Joh」。


Mid

函式: Mid(來源、開始、長度)

描述: 傳回來源值的子字串。 子字串是只包含來源字串中某些字元的字串。

參數:

名稱 必要/重複 類型 備註
source 必要 String 通常屬性的名稱。
start 必要 整數 來源字串中應該啟動子字串的索引。 字串中的第一個字元索引為 1、第二個字元有索引 2 等等。
length 必要 整數 子字串的長度。 如果長度在來源字串之外結束,函式會從開始索引傳回子字串,直到來源字串的結尾。

NormalizeDiacritics

函式: NormalizeDiacritics(來源)

描述: 需要一個字串自變數。 傳回字串,但以任何變音符號字元取代為相等的非字元。 通常用來將名字和姓氏轉換成包含變音符號字元(輔色標記)的法律值,這些值可用於各種使用者標識元,例如用戶主體名稱、SAM 帳戶名稱和電子郵件位址。

參數:

名稱 必要/重複 類型 備註
source 必要 String 通常是名字或姓氏屬性。
具有變音符號的字元 標準化字元 具有變音符號的字元 標準化字元
ä, à, â, â, å, á, ą, ă, ā, ā̀, ā, ā, ǟ, āー, ǡ, a̱, åーー a Ä, À, Â, Â, Å, Á, Ą, Ă, Ā̀, Ā̂, Ā, Ǟ, Āー, Ǡ, A̱, Åー A
æ, ǣ Ae Æ, Ǣ 阿拉伯聯合大公國
ç, č, ć, cー, c̱ c Ç、Č、Ć、Cー、C̱ C
ď, dー, ḏ d Ď, Dー, Ḏ D
è, è, é, ê, е, л, л, ḗ, ḕ, ̂, е̃, êー, êー, e̱, éー, e̊ー e È、È、É、Ê、Л、Л、Л、Ḗ、̂、̂、Е̂、Е̃、Êー、E̱、Еー、E̊ー E
ğ, ḡ, g̱ g Ğ, Ḡ, G̱ G
ï, î, í, ı, ı, ī, ī̀, ī̂, ī̃, i̱ i Ï, Î, Î, Í, ー, Ī̀, Ī̂, Ī̃, I̱ I
ľ, ł, lー, ḹ, ḻ l Ł, Ľ, Lー, Ḹ, Ḻ L
ñ, ṉ, ṉ, ṉ n Ñ, , Ṉ, Ṉ
ö, ò, õ, ô, ô, ó, ˻, ṑ, ṛ, õ, ȫ, éȫ, ǭ, ȭ, ȭ, ȱ, o̱ o Ö, Ò, Õ, Ô, Ó, Ö, Ṓ, Ṑ, Ṛ, ̃, Ȫ, Ȫ, Ǭ, Ȭ, Ȱ, O̱ O
ø, øØØ, œŒØ Oe Ø,ØØ,ŒŒØ OE
ṟ, ṝ r Ṟ、Ṝ R
ß ss
š, л, ș, ş, sー, s̱ s Š, Ș, Ş, Sー, S̱ S
ť, ț, tー, ṯ t Ť, Ț, Tー, Ṯ T
ü, ù, û, ú, л, ű, ū, ū̀, ū̂, ū̃, uーー, ǖ, ṻ, ṳー, u̱ u Ü, Ù, Û, Ú, Ú, Ű, Ū̀, Ū̂, Ū̃, Uーー, Ǖ, Ṻ, Ṳー, U̱ U
ÿ, ý, ȳ, ȳ̀, ȳ̃, y̱ y Ÿ, Ý, Ȳ, Ȳ́, Ȳ̀, Ȳ̃, Y̱ Y
ẕ, ž, ž, zー, ẕ z Ẕ, Ž, Ž, Zー, Ẕ Z

從字串中移除變音符號

範例:以不包含輔色的對等字元取代包含輔色的字元。

表達式: NormalizeDiacritics([givenName])

範例輸入/輸出:

  • INPUT (givenName): “Zoé”
  • 輸出:“Zoe”

Not

函式: Not(source)

描述:翻轉來源布爾值。 如果 來源 值為 True,則傳回 False。 否則會傳回 True。

參數:

名稱 必要/重複 類型 備註
source 必要 布爾字串 預期的 來源 值為 「True」 或 「False」。

Now

函式: Now()

描述
Now 函式會傳回字串,此字串代表 M/d/yyyy h:mm:ss tt 格式的目前 UTC DateTime。

範例:Now()
傳回 2021 年 7 月 2 日下午 3:33:38 的範例值


NumFromDate

函式: NumFromDate(value)

描述:NumFromDate 函式會將 DateTime 值轉換成 Active Directory 格式,以設定 accountExpires 之類的屬性。 使用此函式,將從 Workday 和 SuccessFactors 等雲端 HR 應用程式收到的 DateTime 值轉換為其對等 AD 表示法。

參數:

名稱 必要/重複 類型 備註
value 必要 String ISO 8601 格式的日期時間字串。 如果日期變數的格式不同,請使用 FormatDateTime 函式,將日期轉換為 ISO 8601 格式。

範例:

  • Workday 範例假設您想要將屬性 ContractEndDate 從 Workday 對應,其格式為 2020-12-31-08:00AD 中的 accountExpires 欄位,以下是如何使用此函式,並變更時區位移以符合您的地區設定。 NumFromDate(Join("", FormatDateTime([ContractEndDate], ,"yyyy-MM-ddzzz", "yyyy-MM-dd"), " 23:59:59-08:00"))

  • SuccessFactors 範例假設您想要將屬性 endDate 從 SuccessFactors 對應,其格式為 M/d/yyyy hh:mm:ss ttAD 中的 accountExpires 欄位,以下是如何使用此函式,並變更時區位移以符合您的地區設定。 NumFromDate(Join("",FormatDateTime([endDate], ,"M/d/yyyy hh:mm:ss tt","yyyy-MM-dd")," 23:59:59-08:00"))


PCase

函式: PCase(source,wordSeparators)

描述: PCase 函式會將字串中每個單字的第一個字元轉換成大寫,而所有其他字元都會轉換成小寫。

參數:

名稱 必要/選用 類型 備註
source 必要 String 要轉換成適當大小寫的來源 值。
wordSeparators 選擇性 String 指定一組用來做為文字分隔符的字元(例如:“,-'”)

備註:

  • 如果未指定 wordSeparators 參數,PCase 會在內部叫用 .NET 函式 ToTitleCase,將來源字元串轉換成適當的大小寫。 .NET 函式 ToTitleCase 支援一組 完整的 Unicode 字元類別 目錄做為文字分隔符。
    • 空白字元
    • 新行字元
    • 控制 字元,例如CRLF
    • 格式化 控制字元
    • 連線 orPunctuation 字元,例如底線
    • DashPunctuation 字元,例如破折號和連字元(包括 En Dash、Em Dash、double 連字元等字元)
    • 在括弧、大括弧、角括弧等配對中出現的OpenPunctuation和 ClosePunctuation 字元。
    • InitialQuotePunctuation 和 FinalQuotePunctuation 字元,例如單引號、雙引號和角引號。
    • 其他Punctuation 字元,例如驚嘆號、數字符號、百分比符號、ampersand、星號、逗號、完整停止、冒號、分號等。
    • MathSymbol 字元,例如加號、小於和大於符號、垂直線、波狀符號、等號等。
    • CurrencySymbol 字元,例如美元符號、美分符號、英鎊符號、歐元符號等。
    • 修飾詞Symbol 字元,例如宏、輔色、箭頭等。
    • 其他Symbol 字元,如著作權標誌、學位標誌、註冊標誌等。
  • 如果指定 wordSeparators 參數,PCase 只會使用指定為單字分隔符的字元。

範例:

假設您要從 SAP SuccessFactors 和 HR 採購 屬性 firstNamelastName ,這兩個屬性都是大寫的。 使用 PCase 函式,您可以將名稱轉換成適當的大小寫,如下所示。

運算式 輸入 輸出 備註
PCase([firstName]) firstName = “PABLO GONSALVES (SECOND)” “巴勃羅·岡薩維斯(第二)” 未指定 wordSeparators 參數時PCase 函式會使用預設單字分隔符字元集。
PCase([lastName]," '-") lastName = “PINTO-DE'SILVA” “Pinto-de'Silva” PCase 函式會使用 wordSeparators 參數中的字元來識別單字,並將其轉換成適當的大小寫。
PCase(Join(" ",[firstName],[lastName])) firstName = GREGORY, lastName = “JAMES” “格雷戈里·詹姆斯” 您可以在 PCase 內巢狀 Join 函式。 未指定 wordSeparators 參數時PCase 函式會使用預設單字分隔符字元集。

RandomString

函式: RandomString(Length、MinimumNumbers、MinimumSpecialCharacters、MinimumCapital、MinimumLowerCase、CharactersToAvoid)

描述: RandomString 函式會根據指定的條件產生隨機字串。 您可以在這裏識別允許的字元。

參數:

名稱 必要/重複 類型 備註
長度 必要 數值 隨機字串的總長度。 這應該大於或等於 MinimumNumbers、MinimumSpecialCharacters 和 MinimumCapital 的總和。 最多 256 個字元。
MinimumNumbers 必要 數值 隨機字串中的最小數位。
MinimumSpecialCharacters 必要 數值 特殊字元數目下限。
MinimumCapital 必要 數值 隨機字串中的大寫字母數目下限。
MinimumLowerCase 必要 數值 隨機字串中的小寫字母數目下限。
CharactersToAvoid 選擇性 String 產生隨機字串時要排除的字元。

範例 1: - 產生不含特殊字元限制的隨機字串:RandomString(6,3,0,0,3) 產生具有6個字元的隨機字串。 字串包含3個數位和3個小寫字元(1a73qt)。

範例 2: - 產生具有特殊字元限制的隨機字串:RandomString(10,2,2,2,1,"?,") 產生 10 個字元的隨機字串。 字串包含至少 2 個數位、2 個特殊字元、2 個大寫字母、1 個小寫字母,並排除字元 “?” 和 “,”(1@!2BaRg53)。


修訂

函式: Redact()

描述: Redact 函式會將屬性值取代為布建記錄中的字串常值 “[Redact]”。

參數:

名稱 必要/重複 類型 備註
attribute/value 必要 String 指定要從記錄中修訂的屬性或常數 /字串。

範例 1: 修訂屬性:Redact([userPrincipalName]) 從布建記錄中移除 userPrincipalName。

範例 2: 修訂字串:Redact("StringToBeRedacted") 從布建記錄中移除常數位符串。

範例 3: 修訂隨機字串:Redact(RandomString(6,3,0,0,3)) 從布建記錄中移除隨機字串。


RemoveDuplicates

函式: RemoveDuplicates(attribute)

描述: RemoveDuplicates 函式會採用多重值字元串,並確定每個值都是唯一的。

參數:

名稱 必要/重複 類型 備註
attribute 必要 多重值屬性 已移除重複專案的多重值屬性

範例:RemoveDuplicates([proxyAddresses]) 傳回已清理的 proxyAddress 屬性,其中會移除所有重複的值。


Replace

函式: Replace(source、oldValue、regexPattern、regexGroupName、replacementValue、replacementAttributeName、template)

描述: 以區分大小寫的方式取代字串中的值。 函式的行為會根據所提供的參數而有所不同:

  • 提供 oldValue 和 replacementValue

    • 以 replacementValue 取代來源所有出現的 oldValue
  • 提供 oldValue範本

    • 以來源值取代範本所有出現的 oldValue
  • 提供 regexPatternreplacementValue

    • 函式會將 regexPattern 套用至 來源 字串,而且您可以使用 regex 組名來建構 replacementValue 的 字串

注意

若要深入瞭解 regex 群組建構和具名子表達式,請參閱 正則表達式中的群組建構。

  • regexPatternregexGroupNamereplacementValue 提供時:

    • 函式會將 regexPattern 套用至 來源 字串,並將所有符合 regexGroupName 的值取代為 replacementValue
  • 提供 regexPatternregexGroupNamereplacementAttributeName

    • 如果 source 有值,則會傳回 source
    • 如果 source 沒有值,函式會將 regexPattern 套用至 replacementAttributeName,並傳回符合 regexGroupName 的值

參數:

名稱 必要/重複 類型 備註
source 必要 String 通常來源物件的屬性名稱。
oldValue 選擇性 String 要取代於來源範本中的值。
regexPattern 選擇性 String 來源中要取代值的 Regex 模式。 使用 replacementAttributeName會套用 regexPatternreplacementAttributeName 擷取值。
regexGroupName 選擇性 String regexPattern 內的組名。 使用 named replacementAttributeName 時,我們會從 replacementAttributeName 擷取具名 regex 群組的值,並將它當做取代值傳回。
replacementValue 選擇性 String 要取代舊值的新值。
replacementAttributeName 選擇性 String 要用於取代值的屬性名稱
範本 選擇性 String 提供範本值時 ,我們會在範本 內尋找 oldValue ,並將它取代為 來源 值。

使用正則表達式取代字元

範例 1:使用 oldValue 和 replacementValue,將整個來源字串取代為另一個字符串。

假設您的 HR 系統具有 屬性 BusinessTitle。 在最近的職稱變更中,貴公司想要將任何職稱為「產品開發人員」的任何人更新為「軟體工程師」。 在此情況下,您可以在屬性對應中使用下列表達式。

Replace([BusinessTitle],"Product Developer", , , "Software Engineer", , )

  • 來源[BusinessTitle]
  • oldValue:“Product Developer”
  • replacementValue:“軟體工程師”
  • 表達式輸出:軟體工程師

範例 2: 使用 oldValue範本 將來源字串插入另一個 範本化 字串中。

參數 oldValue 在此案例中是錯誤的。 它實際上是已取代的值。
假設您想要一律以 格式 <username>@contoso.com產生登入標識碼。 有一 個名為 UserID 的來源屬性,您希望該值用於 <username> 登入標識碼的部分。 在此情況下,您可以在屬性對應中使用下列表達式。

Replace([UserID],"<username>", , , , , "<username>@contoso.com")

  • source:[UserID] = “jsmith”
  • oldValue:<username>
  • 範本:<username>@contoso.com
  • 表達式輸出: “jsmith@contoso.com”

範例 3: 使用 regexPatternreplacementValue 擷取來源字串的一部分,並將它取代為使用 regex 模式或 regex 組名所建立的空字符串或自定義值。

假設您有來源屬性 telephoneNumber ,其具有元件 country code ,並以 phone number 空格字元分隔。 例如, +91 9998887777 在此情況下,您可以在屬性對應中使用下列表達式來擷取 10 位數的電話號碼。

Replace([telephoneNumber], , "\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})", , "${phoneNumber}", , )

  • source:[telephoneNumber] = “+91 9998887777”
  • regexPattern:\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})
  • replacementValue:${phoneNumber}
  • 表達式輸出: 9998887777

您也可以使用此模式來移除字元並折疊字串。 例如,下列表達式會移除行動數位字串中的括號、虛線和空格字元,並只傳回數位。

Replace([mobile], , "[()\\s-]+", , "", , )

  • 源:[mobile] = "+1 (999) 888-7777"
  • regexPattern:[()\\s-]+
  • replacementValue: “” (空字串)
  • 表達式輸出: 19998887777

範例 4: 使用 regexPatternregexGroupNamereplacementValue 來擷取來源字元串的一部分,並將它取代為另一個常值或空字串。

假設您的來源系統具有具有兩個元件街號和街道名稱的屬性 AddressLineData。 在最近的移動中,假設位址的街道號碼已變更,而您想要只更新位址行的街道號碼部分。 在此情況下,您可以在屬性對應中使用下列表達式來擷取街號。

Replace([AddressLineData], ,"(?<streetNumber>^\\d*)","streetNumber", "888", , )

  • source:[AddressLineData] = “545 Tremont Street”
  • regexPattern:(?<streetNumber>^\\d*)
  • regexGroupName: “streetNumber”
  • replacementValue: “888”
  • 表達式輸出: 888 Tremont Street

以下是另一個範例,其中 UPN 中的網域後綴會取代為空字串,以產生沒有網域後綴的登入標識符。

Replace([userPrincipalName], , "(?<Suffix>@(.)*)", "Suffix", "", , )

  • source:[userPrincipalName] = “jsmith@contoso.com”
  • regexPattern:(?<Suffix>@(.)*)
  • regexGroupName: “Suffix”
  • replacementValue: “” (空字串)
  • 表達式輸出: jsmith

範例 5: 使用 regexPatternregexGroupNamereplacementAttributeName 來處理來源屬性是空的或沒有值的案例。

假設您的來源系統有一個電話號碼的屬性。 如果 telephoneNumber 是空的,您想要擷取移動號碼屬性的 10 位數。 在此情況下,您可以在屬性對應中使用下列表達式。

Replace([telephoneNumber], , "\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})", "phoneNumber" , , [mobile], )

  • source:[telephoneNumber] = “” (空字串)
  • regexPattern:\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})
  • regexGroupName: “phoneNumber”
  • replacementAttributeName:[mobile] = “+91 8887779999”
  • 表達式輸出: 8887779999

範例 6: 您需要尋找符合正則表示式值的字元,並加以移除。

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

  • source [mailNickname]
  • oldValue: “john_doe72”
  • replaceValue: “”
  • 表達式輸出:72

SelectUniqueValue

函式: SelectUniqueValue(uniqueValueRule1、uniqueValueRule2、uniqueValueRule3、...)

描述: 至少需要兩個自變數,這是使用表達式定義的唯一值產生規則。 函式會評估每個規則,然後檢查在目標應用程式/目錄中產生的唯一性值。 找到的第一個唯一值會是傳回的值。 如果目標中已經有所有值,專案就會被委付,而且原因會記錄在稽核記錄中。 無法提供自變數的數目上限。

  • 此函式必須位於最上層,而且無法巢狀化。
  • 此函式無法套用至具有相符優先順序的屬性。
  • 此函式僅供專案建立使用。 將它與屬性搭配使用時,將 [ 套用對應 ] 屬性設定為 [僅在物件建立期間]。
  • 此函式目前僅支援「Workday 至 Active Directory 使用者布建」和「SuccessFactors 至 Active Directory 使用者佈建」。 它無法與其他佈建應用程式搭配使用。
  • SelectUniqueValue 函式在 內部部署的 Active Directory 中執行的 LDAP 搜尋不會逸出特殊字元,例如變音符號。 如果您傳遞字串,例如包含特殊字元的 「Jéssica Smith」,您將會遇到處理錯誤。 巢狀 NormalizeDiacritics 函 式,如下列範例所示,將特殊字元正規化。

參數:

名稱 必要/重複 類型 備註
uniqueValueRule1 ... uniqueValueRuleN 至少需要 2 個,沒有上限 String 要評估的唯一值產生規則清單。

產生 userPrincipalName (UPN) 屬性的唯一值

範例:根據使用者的名字、中間名和姓氏,您必須產生UPN屬性的值,並在目標AD目錄中檢查其唯一性,再將值指派給UPN屬性。

Expression:

    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如果的 John.Smith@contoso.com UPN 值不存在於目錄中
  • 輸出:「J.Smith@contoso.com如果的 John.Smith@contoso.com UPN 值已存在於目錄中
  • 輸出:「Jo.Smith@contoso.com如果上述兩個 UPN 值已存在於目錄中

SingleAppRoleAssignment

函式: SingleAppRoleAssignment([appRoleAssignments])

描述: 從指定應用程式指派給使用者的所有 appRoleAssignment 清單中傳回單一 appRoleAssignment。 需要此函式,才能將 appRoleAssignments 物件轉換成單一角色名稱字串。 最佳做法是確保一次只將一個 appRoleAssignment 指派給一位使用者。 在使用者有多個應用程式角色指派的情況下,不支援此函式。

參數:

名稱 必要/重複 類型 備註
[appRoleAssignments] 必要 String [appRoleAssignments] 物件。

份額

函式: Split(來源、分隔符)

描述: 使用指定的分隔符,將字串分割成多重值陣列。

參數:

名稱 必要/重複 類型 備註
source 必要 String 要更新的來源 值。
分隔符 必要 String 指定將用來分割字串的字元(例如:“,”)

將字串分割成多重值數位

範例:您需要取得以逗號分隔的字串清單,並將其分割成陣列,以插入多值屬性,例如 Salesforce 的 PermissionSets 屬性。 在此範例中,已在 Microsoft Entra ID 的 extensionAttribute5 中填入許可權集合清單。

表達式: Split([extensionAttribute5], “,”)

範例輸入/輸出:

  • INPUT (extensionAttribute5): “PermissionSetOne, PermissionSetTwo”
  • OUTPUT: [“PermissionSetOne”, “PermissionSetTwo”]

StripSpaces

函式: StripSpaces(來源)

描述: 從來源字串中移除所有空格 (“ ”) 字元。

參數:

名稱 必要/重複 類型 備註
source 必要 String 要更新的來源 值。

Switch

函式: Switch(source, defaultValue, key1, value1, key2, value2, ...)

描述:當來源值符合索引鍵,傳回該索引鍵的值。 如果 來源 值不符合任何索引鍵,則會傳 回 defaultValue索引鍵 參數必須一律成對。 函式一律需要偶數個參數。 函式不應該用於引用屬性,例如manager。

注意

Switch 函式會執行來源索引鍵值的區分大小寫字元串比較。 如果您想要執行不區分大小寫的比較,請先將來源字串正規化,再使用巢狀 ToLower 函式進行比較,並確定所有索引鍵字串都使用小寫。 範例:Switch(ToLower([statusFlag]), "0", "true", "1", "false", "0")。 在此範例中 ,來源 屬性 statusFlag 可能會有值 (“True” / “true” / “TRUE”)。 不過,Switch 函式在與 索引鍵 參數的比較之前,一律會將它轉換成小寫字串 「true」。

警告

針對來源參數,請勿使用巢狀函式 IsPresent、IsNull 或 IsNullOrEmpty。 請改用常值空字串作為其中一個索引鍵值。
範例:Switch([statusFlag], "Default Value", "true", "1", "", "0")。 在此範例中,如果來源屬性statusFlag是空的,Switch 函式會傳回值 0。

參數:

名稱 必要/重複 類型 備註
source 必要 String 要更新的來源 值。
defaultValue 選擇性 String 當來源不符合任何索引鍵時要使用的預設值。 可以是空字串 (“” )。
key 必要 String 要比較來源值與的索引鍵
value 必要 String 比對索引鍵的來源取代值。

根據預先定義的選項集取代值

範例:根據儲存在 Microsoft Entra ID 中的狀態代碼,定義使用者的時區。 如果州代碼不符合任何預先定義的選項,請使用預設值 「Australia/Sydney」。。

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

範例輸入/輸出:

  • INPUT (state): “QLD”
  • 輸出:“澳大利亞/布裡斯班”

ToLower

函式: ToLower(來源、文化特性)

描述: 採用 來源 字串值,並使用指定的文化特性規則,將它轉換成小寫。 如果沒有指定文化特性資訊,則會使用非變異文化特性。

如果您想要將目標系統中的現有值設定為小寫, 請更新目標應用程式的 架構,並將您感興趣的屬性屬性 caseExact 設定為 'true'。

參數:

名稱 必要/重複 類型 備註
source 必要 String 通常來源物件的屬性名稱
culture 選擇性 String 以 RFC 4646 為基礎的文化特性名稱格式為 languagecode2-country/regioncode2,其中 languagecode2 是雙字母語言代碼, 而 country/regioncode2 則是雙字母子文化特性代碼。 範例包括日文(日本)的 ja-JP 和英文版 en-US (美國)。 如果無法使用雙字母語言代碼,則會使用衍生自 ISO 639-2 的三個字母代碼。

將產生的 userPrincipalName (UPN) 值轉換為小寫

範例:您想要串連 PreferredFirstName 和 PreferredLastName 來源字段,並將所有字元轉換成小寫,以產生 UPN 值。

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

範例輸入/輸出:

  • INPUT (PreferredFirstName): “John”
  • INPUT (PreferredLastName): “Smith”
  • 輸出:“john.smith@contoso.com”

ToUpper

函式: ToUpper(來源,文化特性)

描述: 採用 來源 字串值,並使用指定的文化特性規則,將它轉換成大寫。 如果沒有指定文化特性資訊,則會使用非變異文化特性。

如果您想要將目標系統中的現有值設定為大寫, 請更新目標應用程式的 架構,並將您感興趣的屬性屬性 CaseExact 設定為 'true'。

參數:

名稱 必要/重複 類型 備註
source 必要 String 通常來源物件的屬性名稱。
culture 選擇性 String 以 RFC 4646 為基礎的文化特性名稱格式為 languagecode2-country/regioncode2,其中 languagecode2 是雙字母語言代碼, 而 country/regioncode2 則是雙字母子文化特性代碼。 範例包括日文(日本)的 ja-JP 和英文版 en-US (美國)。 如果無法使用雙字母語言代碼,則會使用衍生自 ISO 639-2 的三個字母代碼。

單詞

函式: Word(String,WordNumber,Delimiters)

描述: Word 函式會根據描述要使用的分隔符和要傳回的字型大小的參數,傳回字串內所包含的單字。 以分隔符中其中一個字元分隔之字串中的每個字元字串都會識別為單字:

如果數位 < 1,則傳回空字串。 如果 string 為 null,則傳回空字串。 如果字串包含小於數位字,或字串不包含分隔符所識別的任何字組,則會傳回空字串。

參數:

名稱 必要/重複 類型 備註
String 必要 多重值屬性 要傳回文字的來源字串。
WordNumber 必要 整數 識別應該傳回哪個字型大小的數位
分隔符 必要 String 字串,表示應該用來識別單字的分隔符

範例:Word("The quick brown fox",3," ")

傳回 「brown」。。

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

傳回 「has」。。


範例

本節提供更多表達式函式使用範例。

等量已知功能變數名稱

從使用者的電子郵件中移除已知的功能變數名稱,以取得用戶名稱。 例如,如果網域是 「contoso.com」,您可以使用下列表達式:

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

範例輸入/輸出:

  • 輸入 (郵件):“john.doe@contoso.com”
  • 輸出:“john.doe”

藉由串連名字和姓氏的部分來產生用戶別名

藉由取得使用者名字的前三個字母和使用者姓氏的前五個字母來產生用戶別名。

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

範例輸入/輸出:

  • INPUT (givenName): “John”
  • INPUT (姓氏): “Doe”
  • 輸出:“JohDoe”

在姓氏和名字之間新增逗號。

在姓氏和名字之間新增逗號。

Expression:Join(", ", "", [surname], [givenName])

範例輸入/輸出:

  • INPUT (givenName): “John”
  • INPUT (姓氏): “Doe”
  • 輸出:“Doe,John”

根據使用者的 Microsoft Entra ID 物件識別碼,產生使用者的標識碼。 從標識碼中移除任何字母,並在開頭新增 1000。

此表達式可讓您為開頭為1000且可能是唯一的用戶產生標識碼。

表達式: Join(“”, 1000, Replace(ConvertToUTF8Hex([objectId]), , “[a-zA-Z_]*”, ,“”, ,))

範例輸入/輸出:

  • 輸入:“d05e47b1-3909-445a-ba5e-ca60cbc0e4b4”
  • 輸出:“100064303565343762312333930392343435612626135652636136306362633065346234”