Microsoft Entra ID での属性マッピングの式の記述

クラウド同期を構成する場合、指定できる属性マッピングの種類の 1 つが式マッピングです。

式マッピングを使用すると、スクリプトのような式を使用して属性をカスタマイズできます。 これにより、オンプレミスのデータを新しい値または別の値に変換できます。 たとえば、この 1 つの属性はクラウド アプリケーションのいずれかで使用されるため、2 つの属性を 1 つの属性に結合できます。

次のドキュメントでは、データの変換に使用されるスクリプトのような式について説明します。 これはプロセスの一部にすぎません。 次に、この式を使用して、テナントへの Web 要求に配置する必要があります。 その詳細については、「変換」を参照してください 。

構文の概要

属性マッピングの式の構文は、Visual Basic for Applications (VBA) 関数を思い起こさせます。

• 式全体は、名前の後にかっこで囲まれた引数で構成される関数の観点から定義する必要があります。
  FunctionName(<<argument 1>>,<<argument N>>)

• 関数は相互に入れ子にすることができます。 例えば：
  FunctionOne(FunctionTwo(<<argument1>>))

• 関数には、次の 3 種類の引数を渡すことができます。

  1. 属性。角かっこで囲む必要があります。 例: [attributeName]
  2. 文字列定数。二重引用符で囲む必要があります。 例: "United States"
  3. その他の関数。 例: FunctionOne(<<argument1>>, FunctionTwo(<<argument2>>))

• 文字列定数の場合、文字列に円記号 ( \ ) または引用符 ( " ) が必要な場合は、円記号 ( \ ) 記号でエスケープする必要があります。 例: "会社名: \"Contoso\""

関数の一覧

追加

機能：
Append(source, suffix)

説明:
ソース文字列値を受け取り、サフィックスを末尾に追加します。

パラメーター:

BitAnd

説明:
BitAnd 関数は、値に指定のビットを設定します。

構文 :
num BitAnd(num value1, num value2)

• value1, value2: ともに AND になる数値

備考:
この関数は両方のパラメーターをバイナリ表現に変換し、ビットを次に設定します。

• 0 - value1 と value2 内の対応するビットの 1 つまたは両方が 0 の場合
• 1 - 対応するビットの両方が 1 の場合。

つまり、両方のパラメーターの対応するビットが 1 の場合を除くすべてのケースで 0 を返します。

例:

BitAnd(&HF, &HF7)
16 進数の "F" と "F7" がこの値に評価されるため、7 を返します。

CBool

説明:
CBool 関数は、式の評価結果に基づいてブール値を返します。

構文 :
bool CBool(exp Expression)

備考:
式の評価結果が 0 以外の値の場合は 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 の 16 進数でエンコードされた値に変換します。

構文 :
str ConvertToUTF8Hex(str source)

備考:
この関数の出力形式は、DN 属性の形式として Microsoft Entra ID で使用されます。

例:
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)

説明:
1 つの形式から日付文字列を受け取り、別の形式に変換します。

パラメーター:

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

説明:
Item 関数は複数値の文字列/属性から 1 つの項目を返します。

構文 :
var Item(mvstr attribute, num index)

• attribute: 複数値の属性
• index: 複数値の文字列内の項目へのインデックス。

備考:
Contains 関数は複数値の属性内の項目に対するインデックスを返すため、Item 関数を Contains 関数と共に使用すると便利です。

インデックスが範囲外にある場合は、エラーをスローします。

例:
Mid(Item([proxyAddresses],Contains([proxyAddresses], "SMTP:")),6)
プライマリ メール アドレスを返します。

IsString

説明:
式を文字列型として評価できる場合、IsString 関数の評価結果は True になります。

構文 :
bool IsString(var expression)

備考:
CStr() が式の解析に成功するかどうかを判断するために使用します。

参加する

機能：
Join(separator, source1, source2, ...)

説明:
Join() は Append() に似ていますが、複数の ソース 文字列値を 1 つの文字列に結合でき、各値は 区切り文字列 で区切られます。

ソース値の 1 つが複数値属性の場合、その属性内のすべての値が区切り記号の値で区切って結合されます。

パラメーター:

左

説明:
Left 関数は文字列の左端から数えて指定した文字数分の文字を返します。

構文 :
str Left(str string, num NumChars)

• string: 返される文字を含む文字列
• NumChars: 文字列の左端から数えて返される文字数を指定する数値

備考:
string 内の最初の numChars 文字分の文字を含む文字列。

• numChars = 0 の場合、空の文字列を返します。
• numChars < 0 の場合、入力文字列を返します。
• string が null の場合、空の文字列を返します。

string に含まれる文字数が numChars で指定した数より少ない場合は、string と同一の文字列 (パラメーター 1 のすべての文字が含まれる) が返されます。

例:
Left("John Doe", 3)
Joh を返します。

中間

機能：
Mid(source, start, length)

説明:
ソース値の部分文字列を返します。 部分文字列は、ソース文字列の一部の文字のみを含む文字列です。

パラメーター:

NormalizeDiacritics

機能：
NormalizeDiacritics(source)

説明:
1 つの文字列引数が必要です。 文字列を返しますが、任意の分音文字を等価の非分音文字に置き換えます。 通常、ユーザー プリンシパル名、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 が指定されている場合:

  • source に値がない場合は、source が返されます。
  • source に値がある場合、関数は regexPattern をソース文字列に適用し、regexGroupName に一致するすべての値を replacementAttributeName に関連付けられた値に置き換えます。

パラメーター:

SelectUniqueValue

機能：
SelectUniqueValue(uniqueValueRule1, uniqueValueRule2, uniqueValueRule3, ...)

説明:
少なくとも 2 つの引数が必要です。これは、式を使用して定義された一意の値生成規則です。 この関数は、各ルールを評価し、生成された値でターゲット アプリ/ディレクトリ内の一意性をチェックします。 最初に見つかった一意の値が返されます。 すべての値がターゲットに既に存在する場合、エントリはエスクローされ、理由は監査ログに記録されます。 指定できる引数の数に上限はありません。

パラメーター:

SingleAppRoleAssignment

機能：
SingleAppRoleAssignment([appRoleAssignments])

説明:
特定のアプリケーションのユーザーに割り当てられているすべての appRoleAssignment の一覧から 1 つの appRoleAssignment を返します。 この関数は、appRoleAssignments オブジェクトを 1 つのロール名文字列に変換するために必要です。 ベスト プラクティスは、一度に 1 人の appRoleAssignment のみが 1 人のユーザーに割り当てられるようにすることです。また、複数のロールが割り当てられている場合、返されるロール文字列は予測できない可能性があることに注意してください。

パラメーター:

Split

機能：
Split(source, delimiter)

説明:
指定した区切り文字を使用して、文字列を複数値配列に分割します。

パラメーター:

StringFromSid

説明:
StringFromSid 関数は、セキュリティ識別子が含まれるバイト配列を文字列に変換します。

構文 :
str StringFromSid(bin ObjectSID)

StripSpaces

機能：
StripSpaces(source)

説明:
ソース文字列からすべてのスペース (" ") 文字を削除します。

パラメーター:

スイッチ

機能：
Switch(source, defaultValue, key1, value1, key2, value2, ...)

説明:
ソース値がキーと一致する場合は、そのキーの値を返します。 ソース値がキーと一致しない場合は、defaultValue を返します。 キー と 値 のパラメーターは常にペアである必要があります。 この関数は常に偶数のパラメーターを受け取ります。

パラメーター:

ToLower

機能：
ToLower(source, culture)

説明:
指定されたカルチャ 規則を使用して 、ソース 文字列値を受け取り、小文字に変換します。 カルチャ情報が指定されていない場合は、インバリアント カルチャが使用されます。

パラメーター:

ToUpper

機能：
ToUpper(source, culture)

説明:
指定されたカルチャ ルールを使用して 、ソース 文字列値を受け取り、大文字に変換します。 カルチャ情報が指定されていない場合は、インバリアント カルチャが使用されます。

パラメーター:

トリミング

説明:
Trim 関数は、文字列の先頭と末尾の空白文字を削除します。

構文 :
str Trim(str value)

例:
Trim(" Test ")
"test" を返します。

Trim([proxyAddresses])
proxyAddress 属性の値ごとに先頭と末尾の空白文字を削除します。

ワード

説明:
Word 関数は、使用する区切り記号と返す単語の番号を表すパラメーターに基づいて、文字列内に含まれる単語を返します。

構文 :
str Word(str string, num WordNumber, str delimiters)

• string: 返される単語を含む文字列。
• WordNumber: 返すべき単語の番号を指定する数値。
• delimiters: 単語を識別するために使用される区切り記号を表す文字列

備考:
delimiters 内のいずれかの文字で区切られた string 内の各文字列が、単語として識別されます。

• 数値 < 1 の場合、空の文字列を返します。
• string が null の場合、空の文字列を返します。

string に含まれる単語の数が指定より少ないか、区切り記号文字で識別されるどの単語も string に含まれていない場合は、空の文字列が返されます。

例:
Word("The quick brown fox",3," ")
"brown" を返します。

Word("This,string!has&many separators",3,",!&#")
"has" を返します。

例示

既知のドメイン名を削除する

ユーザー名を取得するには、ユーザーの電子メールから既知のドメイン名を削除する必要があります。
たとえば、ドメインが "contoso.com" の場合は、次の式を使用できます。

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

サンプルの入力/出力:

• INPUT (mail): "john.doe@contoso.com"
• 出力: "john.doe"

ユーザー名に定数サフィックスを追加する

Salesforce サンドボックスを使用している場合は、同期する前に、すべてのユーザー名に追加のサフィックスを追加することが必要になる場合があります。

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

サンプルの入力/出力:

• INPUT: (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"
• OUTPUT: ["PermissionSetOne", "PermissionSetTwo"]

特定の形式の文字列として日付を出力する

特定の形式で SaaS アプリケーションに日付を送信する場合。
たとえば、ServiceNow の日付を書式設定します。

式:

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

サンプルの入力/出力:

• INPUT (extensionAttribute1): "20150123105347.1Z"
• 出力: "2015-01-23"

定義済みの一連のオプションに基づいて値を置き換える

Microsoft Entra ID に格納されている状態コードに基づいて、ユーザーのタイム ゾーンを定義する必要があります。
状態コードが定義済みのオプションのいずれとも一致しない場合は、既定値の "Australia/Sydney" を使用します。

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

サンプルの入力/出力:

• INPUT (状態): "QLD"
• 出力: "Australia/Brisbane"

正規表現を使用して文字を置換する

正規表現の値に一致する文字を見つけて削除する必要があります。

式:

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

サンプルの入力/出力:

• INPUT (PreferredFirstName): "John"
• INPUT (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")
    )

サンプルの入力/出力:

• INPUT (PreferredFirstName): "John"
• INPUT (PreferredLastName): "Smith"
• OUTPUT: John.Smith@contoso.comの UPN 値がまだディレクトリに存在しない場合は "John.Smith@contoso.com"
• OUTPUT: John.Smith@contoso.comの UPN 値がディレクトリに既に存在する場合は "J.Smith@contoso.com"
• OUTPUT: "Jo.Smith@contoso.com" (上記の 2 つの UPN 値がディレクトリに既に存在する場合)

次のステップ

• プロビジョニングとは
• Microsoft Entra クラウド同期とは?