Написание выражений для сопоставлений атрибутов в идентификаторе Microsoft Entra

При настройке облачной синхронизации один из типов сопоставлений атрибутов, которые можно указать, — это сопоставление выражений.

Сопоставление выражений позволяет настраивать атрибуты с помощью выражения, аналогичного скрипту. Это позволяет преобразовать локальные данные в новое или другое значение. Например, может потребоваться объединить два атрибута в один атрибут, так как этот один атрибут используется одним из облачных приложений.

В следующем документе рассматриваются такие выражения, как скрипт, которые используются для преобразования данных. Это только часть процесса. Затем вам потребуется использовать это выражение и поместить его в веб-запрос к клиенту. Дополнительные сведения об этом см. в разделе "Преобразования"

Общие сведения о синтаксисе

Синтаксис выражений для сопоставлений атрибутов напоминает функции Visual Basic для приложений (VBA).

• Все выражение должно быть определено с точки зрения функций, которые состоят из имени, за которым следует аргументы в скобках:
  FunctionName(<<argument 1>>,<<argument N>>)

• Вы можете вложить функции друг в друга. Например:
  FunctionOne(FunctionTwo(<<argument1>>))

• В функции можно передать три разных типа аргументов:

  1. Атрибуты, которые должны быть заключены в квадратные скобки. Например: [attributeName]
  2. Строковые константы, которые должны быть заключены в двойные кавычки. Например: "Соединенные Штаты"
  3. Другие функции. Например: FunctionOne(, FunctionTwo(<<argument1>><<argument2>>))

• Для строковых констант, если требуется обратная косая черта (\ ) или кавычки (" ) в строке, она должна быть экранирована с символом обратной косой черты (\ ) . Например: "Имя компании: \"Contoso\""

Список функций

Добавить

Функция:
Append(source, суффикс)

Описание.
Принимает исходное строковое значение и добавляет суффикс к концу.

Параметры:

BitAnd

Описание.
Функция BitAnd задает конкретное значение для битов.

Синтаксис
num BitAnd(num value1, num value2)

• value1, value2: числовые значения, которые должны быть соединены оператором AND.

Примечания:
Эта функция преобразует оба параметра в двоичное представление и устанавливает для бита следующие значения:

• 0 — если один или оба соответствующих бита в value1 и value2 равны 0;
• 1 — если оба соответствующих бита равны 1.

Другими словами, функция возвращает значение 0 всегда, за исключением случаев, когда соответствующие биты обоих параметров равны 1.

Пример:

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) — здесь предполагается кодирование Юникод.
str ConvertFromBase64(str source, enum Encoding)

• source: строка в кодировке Base64
• Кодировка: Юникод, ASCII, UTF8

Пример
ConvertFromBase64("SABlAGwAbABvACAAdwBvAHIAbABkACEA")
ConvertFromBase64("SGVsbG8gd29ybGQh", UTF8)

Оба примера возвращают сообщение "Hello world!".

ConvertToBase64

Описание.
Функция ConvertToBase64 преобразует строку в строку Юникода в кодировке base64.
Преобразует значение массива целых чисел в эквивалентное строковое представление в кодировке знаков base64.

Синтаксис
str ConvertToBase64(str source)

Пример:
ConvertToBase64("Hello world!")
Возвращает SABlAGwAbABvACAAdwBvAHIAbABkACEA.

ConvertToUTF8Hex

Описание.
Функция ConvertToUTF8Hex преобразует значение в шестнадцатеричной кодировке UTF8.

Синтаксис
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)
Возвращает значение DateTime, равное 2012-01-01 23:00:00.

DNComponent

Описание.
Функция DNComponent возвращает значение указанного компонента различающегося имени начиная с левого края.

Синтаксис
str DNComponent(ref dn, num ComponentNumber)

• dn: ссылочный атрибут для интерпретации.
• ComponentNumber: компонент в различающемся имени для возврата.

Пример:
DNComponent(CRef([dn]),1)
Если значение различающегося имени равно 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.

Синтаксис
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 возвращает значение True, если выражение принимает значение NULL.

Синтаксис
bool IsNull(var Expression)

Примечания:
Значение NULL для атрибута выражается в отсутствии атрибута.

Пример:
IsNull([displayName])
Возвращает значение True, если атрибут не присутствует в CS или MV.

Пустое или отсутствует

Описание.
Функция IsNullOrEmpty возвращает значение True, если выражение имеет значение NULL или является пустой строкой.

Синтаксис
bool IsNullOrEmpty(var Expression)

Примечания:
Для атрибута это будет значение True, если атрибут отсутствует или же присутствует, но является пустой строкой.
Обратной функцией этой функции является IsPresent.

Пример:
IsNullOrEmpty([displayName])
Возвращает значение True, если атрибут не присутствует или является пустой строкой в CS или MV.

IsPresent

Описание.
Функция IsPresent возвращает значение True, если результат выражения — строка, которая не имеет значение NULL и не является пустой.

Синтаксис
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(), за исключением того, что он может объединить несколько исходных строк в одну строку, и каждое значение будет разделено строкой разделителя .

Если одно из исходных значений является атрибутом с несколькими значениями, то каждое значение этого атрибута будет объединены вместе, разделенным значением разделителя.

Параметры:

Лево

Описание.
Функция Left возвращает указанное количество символов из левой части строки.

Синтаксис
str Left(str string, num NumChars)

• string: строка, из которой возвращаются символы.
• NumChars: число, определяющее количество символов для возврата из начала строки (слева).

Примечания:
Строка, содержащая первые numChars символов в строке:

• если numChars = 0, возвращается пустая строка;
• если numChars < 0, возвращается введенная строка;
• если строка имеет значение Null, возвращается пустая строка.

Если строка содержит меньше символов, чем указано в numChars, возвращается строка без изменений (т. е. содержащая все символы в параметре 1).

Пример:
Left("John Doe", 3)
Возвращает Joh.

Средний

Функция:
Mid(source, start, length)

Описание.
Возвращает подстроку исходного значения. Подстрока — это строка, содержащая только некоторые символы из исходной строки.

Параметры:

НормализованныеDiacritics

Функция:
NormalizeDiacritics(source)

Описание.
Требуется один строковый аргумент. Возвращает строку, но с любыми диакритических символами, замененными эквивалентными некритичными символами. Обычно используется для преобразования имен и фамилий, содержащих диакритические символы (знаки акцента) в юридические значения, которые можно использовать в различных идентификаторах пользователей, таких как имена субъектов-пользователей, имена учетных записей SAM и адреса электронной почты.

Параметры:

Не

Функция:
Not(source)

Описание.
Переворачивает логическое значение источника. Если исходное значение равно True, возвращает значение False. В противном случае возвращает значение True.

Параметры:

RemoveDuplicates

Описание.
Функция RemoveDuplicates принимает строку с несколькими значениями и проверяет, чтобы каждое значение было уникальным.

Синтаксис
mvstr RemoveDuplicates(mvstr attribute)

Пример:
RemoveDuplicates([proxyAddresses])
Возвращает очищенный атрибут proxyAddress, в котором удалены все повторяющиеся значения.

Заменить

Функция:
Replace(source, oldValue, regexPattern, regexGroupName, replaceValue, replaceAttributeName, template)

Описание.
Заменяет значения в строке. Он работает по-разному в зависимости от указанных параметров:

• При указании oldValue и заменыValue :

  • Заменяет все вхождения oldValue в источникена replaceValue

• При указании старого значения ишаблона :

  • Заменяет все вхождения oldValue в шаблонеисходным значением.

• При указании regexPattern и replacementValue :

  • Функция применяет regexPattern к исходной строке и можно использовать имена групп regex для создания строки для заменыValue.

• При regexPattern, regexGroupName предоставляется заменаValue :

  • Функция применяет regexPattern к исходной строке и заменяет все значения, соответствующие regexGroupName , на replaceValue

• При использовании regexPattern, regexGroupName предоставляется заменаAttributeName :

  • Если источник не имеет значения, возвращается источник
  • Если источник имеет значение, функция применяет regexPattern к исходной строке и заменяет все значения, соответствующие regexGroupName значением, связанному с заменойAttributeName.

Параметры:

SelectUniqueValue

Функция:
SelectUniqueValue(uniqueValueRule1, uniqueValueRule2, uniqueValueRule3, ...)

Описание.
Требует не менее двух аргументов, которые являются уникальными правилами создания значений, определенными с помощью выражений. Функция вычисляет каждое правило, а затем проверяет значение, созданное для уникальности в целевом приложении или каталоге. Первое уникальное значение будет возвращено. Если все значения уже существуют в целевом объекте, запись будет депонирована, а причина регистрируется в журналах аудита. Нет верхней границы к числу аргументов, которые можно указать.

Параметры:

SingleAppRoleAssignment

Функция:
SingleAppRoleAssignment([appRoleAssignments])

Описание.
Возвращает один appRoleAssignment из списка всех приложений appRoleAssignment, назначенных пользователю для данного приложения. Эта функция необходима для преобразования объекта appRoleAssignments в одну строку имени роли. Обратите внимание, что рекомендуется убедиться, что одновременно одному пользователю назначено только одно приложение AppRoleAssignment, и если возвращаемая строка роли назначена нескольким ролям, возможно, не предсказуема.

Параметры:

Разделение

Функция:
Split(source, разделитель)

Описание.
Разбивает строку на многозначный массив, используя указанный символ разделителя.

Параметры:

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: строка, представляющая разделители, которые должны использоваться для идентификации слов.

Примечания:
Каждая строка символов в строке, разделенной одним из символов-разделителей, определяется как слово:

• если number < 1, возвращается пустая строка;
• если string имеет значение Null, возвращается пустая строка.

Если строка содержит меньше слов, чем number, или строка не содержит слов, идентифицируемых с помощью разделителей, возвращается пустая строка.

Пример:
Word("The quick brown fox",3," ")
Возвращает значение "brown".

Word("This,string!has&many separators",3,",!&#")
Вернет значение "has".

Примеры

Полоса известного доменного имени

Чтобы получить имя пользователя, необходимо удалить известное доменное имя из сообщения электронной почты пользователя.
Например, если домен имеет значение "contoso.com", можно использовать следующее выражение:

Выражение:
Replace([mail], "@contoso.com", , ,"", ,)

Пример входных и выходных данных:

• Входные данные (mail): "[email protected]"
• Выходные данные: john.doe

Добавление констант суффикса к имени пользователя

Если вы используете песочницу Salesforce, может потребоваться добавить дополнительный суффикс ко всем именам пользователей перед синхронизацией.

Выражение:
Append([userPrincipalName], ".test")

Пример входных и выходных данных:

• Входные данные: (userPrincipalName): "[email protected]"
• Выходные данные: "[email protected]"

Создание псевдонима пользователя путем объединения частей первого и фамилии

Необходимо создать псевдоним пользователя, принимая первые 3 буквы имени пользователя и первые 5 букв фамилии пользователя.

Выражение:
Append(Mid([givenName], 1, 3), Mid([surname], 1, 5))

Пример входных и выходных данных:

• INPUT (givenName): "Джон"
• INPUT (фамилия): "Doe"
• Выходные данные: "JohDoe"

Удаление диакритических символов из строки

Необходимо заменить символы, содержащие знаки акцента эквивалентными символами, которые не содержат знаки акцента.

Выражение:
NormalizeDiacritics([givenName])

Пример входных и выходных данных:

• ВВОД (givenName): "Zoë"
• ВЫХОДНЫЕ ДАННЫЕ: "Zoe"

Разделение строки на многозначный массив

Необходимо взять список строк с разделителями-запятыми и разделить их на массив, который можно подключить к атрибуту с несколькими значениями, например атрибуту Salesforce PermissionSets. В этом примере список наборов разрешений заполнен в extensionAttribute5 в идентификаторе Microsoft Entra ID.

Выражение:
Split([extensionAttribute5], ",")

Пример входных и выходных данных:

• Входные данные: (extensionAttribute5): "PermissionSetOne, PermissionSetTwo"
• ВЫХОДНЫЕ ДАННЫЕ: ["PermissionSetOne", "PermissionSetTwo"]

Дата вывода в виде строки в определенном формате

Вы хотите отправить даты в приложение SaaS в определенном формате.
Например, необходимо отформатировать даты для ServiceNow.

Выражение:

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

Пример входных и выходных данных:

• ВВОД : (extensionAttribute1): "20150123105347.1Z"
• ВЫХОДНЫЕ ДАННЫЕ: "2015-01-23"

Замена значения на основе предопределенного набора параметров

Необходимо определить часовой пояс пользователя на основе кода состояния, хранящегося в идентификаторе Microsoft Entra.
Если код штата не соответствует ни одному из предопределенных параметров, используйте значение по умолчанию "Австралия/Сидней".

Выражение:
Switch([state], "Australia/Sydney", "NSW", "Australia/Sydney","QLD", "Australia/Brisbane", "SA", "Australia/Adelaide")

Пример входных и выходных данных:

• ВВОД : (state): "QLD"
• OUTPUT: "Австралия/Брисбен"

Замена символов с помощью регулярного выражения

Необходимо найти символы, соответствующие значению регулярного выражения, и удалить их.

Выражение:

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

Пример входных и выходных данных:

• INPUT (mailNickname: "john_doe72"
• ВЫХОДНЫЕ ДАННЫЕ: "72"

Преобразование созданного значения userPrincipalName (UPN) в нижний регистр

В приведенном ниже примере значение имени участника-пользователя создается путем объединения полей источника PreferredFirstName и PreferredLastName, а функция ToLower работает с созданной строкой для преобразования всех символов в нижний регистр.

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

Пример входных и выходных данных:

• Входные данные (предпочитаемое имя): "John".
• Входные данные (предпочитаемая фамилия): "Smith".
• Выходные данные: "[email protected]"

Создание уникального значения для атрибута userPrincipalName (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")
    )

Пример входных и выходных данных:

• Входные данные (предпочитаемое имя): "John".
• Входные данные (предпочитаемая фамилия): "Smith".
• OUTPUT: "[email protected]" если значение [email protected] имени участника-пользователя еще не существует в каталоге
• OUTPUT: "[email protected]" если значение [email protected] имени участника-пользователя уже существует в каталоге
• OUTPUT: "[email protected]" если указанные выше два значения имени участника-пользователя уже существуют в каталоге

Дальнейшие действия

• Что такое предоставление ресурсов?
• Что такое облачная синхронизация Microsoft Entra?