How to use account field expressions - Identity as a Service

Gelişmiş bir hesap alanı ifadesi, yerleşik IDaaS ifade motorunun değerlendirdiği bir model referansı ile bir işlevi eşleştirir. Uygulama tek oturum açma (SSO) öznitelikleri ve kimlik sağlayıcı alan eşlemeleri için hesap alanı değerlerini dönüştürmek, birleştirmek veya koşullu olarak seçmek amacıyla bu ifadeleri kullanın.

İfadelerin çalışma şekli

SAML ve OIDC uygulamalarında gelişmiş ifadeler, IDaaS'ın döndürdüğü kullanıcı bilgilerine yeni parametreler ekler. Hedef uygulamanın dönüştürülmesi, birleştirilmesi veya koşula göre seçilmesi gereken ek bir parametre gerektirdiği durumlarda ifade kullanın.

Bir ifade iki bölümden oluşur:

Model: IDaaS hesabı için User ve uygulama hesabı için AppUser.
İşlev: Çalıştırılan mantık.

İfadeleri kullanabileceğiniz yerler

İfadeler aşağıdaki yapılandırma alanlarında desteklenir; her birinin farklı kısıtlamaları vardır.

OIDC uygulama SSO'su: id_token içinde döndürülen bilgileri genişletin. OIDC uygulamasının SSO yapılandırma sayfasında id_token uzantı alanı bölümünü bulun ve Extended Value alanına full_phone gibi ihtiyacınız olan ifadeyi girin.
SAML uygulama SSO'su: SSO sırasında IDaaS'ın döndürdüğü kullanıcı bilgilerine parametreler ekleyin. SamlArray işlevi yalnızca SAML SSO için kullanılabilir.
Kimlik sağlayıcı alan eşlemesi: Bir kimlik sağlayıcı (IdP) ile senkronize edilen alan eşlemesinde özel alan değerleri atamak için aynı ifadeleri kullanın.
OIDC kimlik sağlayıcıları için alan önekleri: Otomatik bağlama için id_token içindeki yalnızca sub, phoneNumber ve email alanları idpUser. önekini kullanır; örneğin idpUser.sub. Diğer tüm alanlar idpUser.rawUserInfo. önekini kullanmalıdır; örneğin idpUser.rawUserInfo.aud. Daha fazla bilgi için bkz. OIDC kimlik sağlayıcısını bağlama.

Ayrıntılar için bkz. SAML Öznitelik Beyanları değer belirtimleri, OIDC id_token genişletilmiş değer belirtimleri ve alan yönetimi.

Modeller

Bir ifade, bir model aracılığıyla değerleri okur.

User modeli

Bir ifade içinde User modelinin alanlarına başvurun; örneğin user.username ve user.lockExpireTime.

Field Display Name	Field ID	Data Type	Required	Unique	User Permissions	Description
Account ID	userId	String	No	Yes	Visible	The user ID.
Account name	username	String	Yes	Yes	Visible	The username.
Display name	displayName	String	No	No	Editable	The display name of the user.
Email	email	String	No	Yes	Editable	The email address.
Phone number	phoneNumber	String	No	Yes	Editable	The mobile phone number.
Phone region	phoneRegion	String	No	No	Editable	The region code of the mobile phone number. For example, the code for China is "86", without "00" or "+".
External ID	userExternalId	String	No	Yes	Visible	The external ID of the user.
Source type	userSourceType	String	No	No	Visible	The source type. Valid values: `build_in` (created in IDaaS), `ding_talk`, `ad` (Active Directory), `ldap`, `we_com`, `lark`, and `idp_auto_build` (automatic creation by an IdP).
Source ID	userSourceId	String	No	No	Visible	The source ID.
Account status	status	String	No	No	Visible	The status of the user. Valid values: `enabled` and `disabled`.
Description	description	String	No	No	Visible	The description.
Account expiration time	accountExpireTime	Number	No	No	Visible	The time when the user expires. The value is a UNIX timestamp in milliseconds.
Registration time	registerTime	Number	No	No	Visible	The time when the user was registered. The value is a UNIX timestamp in milliseconds.
Password expiration time	passwordExpireTime	Number	No	No	Visible	The time when the password expires. The value is a UNIX timestamp in milliseconds.
Lock expiration time	lockExpireTime	Number	No	No	Visible	The time when the lock expires. The value is a UNIX timestamp in milliseconds.
Creation time	createTime	Number	No	No	Visible	The time when the user was created. The value is a UNIX timestamp in milliseconds.
Update time	updateTime	Number	No	No	Visible	The time when the user information was last updated. The value is a UNIX timestamp in milliseconds.

Bir hesap için örnek User modeli verileri:

{
  "customFieldMap": {
    "place": {
      "fieldName": "place",
      "fieldValue": "beijing"
    },
    "age": {
      "fieldName": "age",
      "fieldValue": "18"
    }
  },
  "identityProviderUserMap": {
    "idp_m2gngriuenktdkxxxxxx": {
      "identityProviderId": "idp_m2gngriuenktdkxxxxxx",
      "identityProviderType": "ding_talk",
      "identityProviderExternalId": "corp_1234xxxxxxx",
      "identityProviderUserId": "b2ed5fc0xxxxx"
    }
  },
  "organizationalUnits": [
    {
      "organizationalUnitId": "ou_sdfadtaaxxxxxx",
      "organizationalUnitName": "name_001",
      "primary": false
    },
    {
      "organizationalUnitId": "ou_werttxxxxxx",
      "organizationalUnitName": "name_002",
      "primary": true
    }
  ],
  "primaryOrganizationalUnitId": "ou_werttxxxxxx",
  "customFields": [
    {
      "fieldName": "place",
      "fieldValue": "beijing"
    },
    {
      "fieldName": "age",
      "fieldValue": "18"
    }
  ],
  "groups": [
    {
      "groupId": "group_jp6al4sn4n4wjgjxxxxxx",
      "groupName": "group1",
      "groupExternalId": "group_jp6al4sn4n4wjgjxxxxxx"
    },
    {
      "groupId": "group_vavikcxewkf5h3oxxxxxx",
      "groupName": "group2",
      "groupExternalId": "group_vavikcxewkf5h3oxxxxxx"
    }
  ],
  "userId": "user_x3zyd6cxxxxxxxxxxxxx",
  "username": "name_001",
  "displayName": "displayname_001",
  "passwordSet": true,
  "phoneRegion": "86",
  "phoneNumber": "333xxxx3333",
  "phoneNumberVerified": true,
  "email": "xxxxx@example.com",
  "emailVerified": true,
  "userExternalId": "b2ed5fc0xxxxxxxxxx",
  "userSourceType": "ding_talk",
  "userSourceId": "corp_1234xxxxxxx",
  "status": "enabled",
  "accountExpireTime": "-1",
  "passwordExpireTime": "-1",
  "registerTime": "1730454581598",
  "lockExpireTime": "-1",
  "createTime": "1730454582379",
  "updateTime": "1733479455307"
}

AppUser modeli

Bir ifade içinde IDaaS AppUser modelinin alanlarına başvurun; örneğin appUser.username.

Field ID	Description
username	The username of the application account.

IdP User modeli

IdP User modeli, bir kimlik sağlayıcı ile veri senkronize ettiğinizde geçerlidir. Örneğin, DingTalk'in çalışma konumu alanı idpUser.work_place şeklindedir.

Kullanılabilir alanlar kimlik sağlayıcıya bağlıdır. İlgili sağlayıcının belgelerine bakın. DingTalk için bkz. DingTalk belgeleri - Kullanıcı ayrıntılarını sorgulama.

İşlevler

İfade motorunun işlevleri yeteneklere göre gruplandırılmıştır:

Dize işlevleri

Dize değerlerini birleştirir, kırpar, değiştirir, böler ve parçalarını çıkarır.

Function	Syntax	Description	Example
Append	Append(str1, str2, ..., strn)	Giriş bağımsız değişkenlerini yeni bir dizede birleştirir. `str1+str2+...` ile eşdeğerdir.	Input: `Append("str1", "@example.com")` → Output: `str1@example.com`
Join	Join(source1, source2, ..., sourceN, separator)	Birden çok kaynak değeri tek bir dizede birleştirir. Değerler belirtilen ayırıcı ile ayrılır.	Input: `Join("str1", "str2", 123,"-")` → Output: `"str1-str2-123"`
StringReplace	StringReplace(source, search, replacement)	Kaynak dizedeki düz bir alt dizgeyi başka bir dizeyle değiştirir.	Input: `StringReplace("hello $str", "$str", "world")` → Output: `hello world`
Trim	Trim(source)	Kaynak dizenin başındaki ve sonundaki boşluk karakterlerini kaldırır.	Input: `Trim(" 123 ")` → Output: `"123"`
TrimLeft	TrimLeft(source)	Kaynak dizenin başındaki boşluk karakterlerini kaldırır.	Input: `TrimLeft(" 123 ")` → Output: `"123 "`
TrimRight	TrimRight(source)	Kaynak dizenin sonundaki boşluk karakterlerini kaldırır.	Input: `TrimRight(" 123 ")` → Output: `" 123"`
ToLower	ToLower(source)	Bir dizeyi küçük harfe dönüştürür.	Input: `ToLower(" Abc ")` → Output: `" abc "`
ToUpper	ToUpper(source)	Bir dizeyi büyük harfe dönüştürür.	Input: `ToUpper(" Abc ")` → Output: `" ABC "`
Substring	Substring(source, fromIndex, endIndex)	Kaynak dizenin bir alt dizgesini döndürür. Alt dizge `fromIndex` konumunda başlar ve `endIndex` konumundan önce biter. `source` gereklidir ve sözdiziminin desteklediği herhangi bir türde olabilir. `fromIndex` ve `endIndex` gereklidir ve tamsayı olmalıdır. Herhangi bir değer tamsayı değilse null döndürülür.	Input: `Substring("0123456", 1, 5)` → Output: `1234`; Input: `Substring("0123456", -1, 7)` → Output: `0123456`; Input: `Substring("0123456", "1", 5)` → Output: `null`
SubstringBefore	SubstringBefore(source, subString)	Soldan sağa doğru arama yaparak kaynak dizede hedef dizenin ilk oluşumundan önce gelen alt dizgeyi döndürür. Hedef dize yoksa null döndürülür. `source` ve `subString` gereklidir ve sözdiziminin desteklediği herhangi bir türde olabilir. Dönüş değeri bir dizedir.	Input: `SubstringBefore("test@example@com", "@")` → Output: `"test"`
Split	Split(source, separator)	Bir dizeyi böler ve bir dizi döndürür.	Input: `Split("str1,str2,str3",",")` → Output: `["str1", "str2", "str3"]`

Koşullu ve null işleme işlevleri

Bir alan eksik olduğunda başka bir değere geri dönün, varsayılan bir değer uygulayın veya bir koşula göre dallanın.

Function	Syntax	Description	Example
Coalesce	Coalesce(source1, source2, ..., sourceN, defaultValue)	İlk boş olmayan bağımsız değişkeni döndürür. Tüm bağımsız değişkenler boşsa `null` döndürür. Bir bağımsız değişken null değilse ve uzunluğu 0'dan büyükse boş değildir.	Input: `Coalesce("", user.phoneRegion, "86")` → Output: Telefon bölge kodu boşsa veya eksikse `86`
IIF	IIF(condition, whenTrue, whenFalse)	Üçlü işlem gerçekleştirir. `condition` sonucuna bağlı olarak farklı bir değer döndürür: Koşul doğruysa `whenTrue`, yanlışsa `whenFalse`.	Input: `IIF(true, 1, 2)` → Output: `1`; Input: `IIF(false, 1, 2)` → Output: `2`
IsNull	IsNull(value)	`value` null ise, yani değer eksikse `true` döndürür.	Input: `IsNull(null)` → Output: `true`; Input: `IsNull("")` → Output: `false`
IsNullOrEmpty	IsNullOrEmpty(value)	`value` null veya boş bir dize ise `true` döndürür.	Input: `IsNullOrEmpty(user.email)` → Output: E-posta adresi null ise, yani değer eksikse `true`; Input: `IsNullOrEmpty("")` → Output: `true`

Karşılaştırma ve mantıksal işlevler

Bu işlevler true veya false döndürür. Bunları tek başına veya IIF öğesinin condition bağımsız değişkeni olarak kullanın.

Function	Syntax	Description	Example
Contains	Contains(str1,str2)	Bir dizenin belirtilen alt dizgeyi içerip içermediğini kontrol eder. `true` veya `false` döndürür.	Input: `Contains("test", "t")` → Output: `true`; Input: `Contains("test", "a")` → Output: `false`
StartsWith	StartsWith(str1, str2)	Bir dizenin belirtilen önekle başlayıp başlamadığını kontrol eder. Tam olarak iki bağımsız değişken kabul eder.	Input: `StartsWith("test", "t")` → Output: `true`; Input: `StartsWith("test", "e")` → Output: `false`
Equals	Equals(str1, str2, ignoreCase)	İki dizenin eşitliğini karşılaştırır. Karşılaştırma varsayılan olarak büyük/küçük harfe duyarlıdır: `Equals(str1,str2)` ve `Equals(str1,str2,false)` büyük/küçük harfe duyarlı karşılaştırmalardır, `Equals(str1,str2,true)` ise büyük/küçük harfe duyarsız bir karşılaştırmadır.	Input: `Equals("test","Test")` → Output: `false`; Input: `Equals("test","Test",true)` → Output: `true`; Input: `Equals("test","Test",false)` → Output: `false`
Or	Or(true,false,...,true)	Birden çok koşulu mantıksal OR ile değerlendirir. En az bir koşul doğruysa `true` döndürür.	Input: `Or(true,false)` → Output: `true`; Input: `Or(true,true,false)` → Output: `true`; Input: `Or(false,false)` → Output: `false`
And	And(true,false,...,true)	Birden çok koşulu mantıksal AND ile değerlendirir. En az bir koşul yanlışsa `false` döndürür.	Input: `And(true,false)` → Output: `false`; Input: `And(true,true,false)` → Output: `false`; Input: `And(true,true,true)` → Output: `true`
xOr	xOr(true,false,...,true)	Tam olarak iki koşul kabul eder. Her iki koşul da doğruysa veya her iki koşul da yanlışsa `false` döndürür. Bir koşul doğru ve diğeri yanlışsa `true` döndürür.	Input: `xOr(true,false)` → Output: `true`; Input: `xOr(true,true)` → Output: `false`; Input: `xOr(false,false)` → Output: `false`

Dizi işlevleri

Bir dizi oluşturur, öğelerinden birini okur ve bir hesabın grupları gibi nesne dizilerini yeniden şekillendirir.

Function	Syntax	Description	Example
Array	Array(source1, source2,...)	Birden çok değeri bir dizide birleştirir. Bir değer Object türünde olabilir.	Input: `Array(1, 2, 3)` → Output: `[1, 2, 3]`
ArrayAdd	ArrayAdd(Array(), "test")	Bir diziye öğe ekler.	Input: `ArrayAdd(Array(), "test")` → Output: `["test"]`
ArrayMap	ArrayMap($ArrayObject, __item.ObjectProperty)	Bir dizideki her nesneden belirtilen özelliğin değerini çıkararak yeni bir dizi oluşturur.	Bir kullanıcının ait olduğu grupların ID listesini alın. Input: `ArrayMap(user.groups, __item.groupId)` → Output: `["groupId1","groupId2","groupId3"]`
ArrayIndex	ArrayIndex(Array(), n)	Bir dizide belirtilen konumdaki öğeyi döndürür. İndeks 0'dan başlar.	Input: `ArrayIndex(Array(1,2,3), 0)` → Output: `1`
ArrayJoin	ArrayJoin(Array(), str)	Bir dizinin öğelerini belirtilen dizeyi kullanarak birleştirir.	Input: `ArrayJoin(Array(1,2,3), "-")` → Output: `"1-2-3"`

Nesne işlevleri

Anahtar-değer çiftlerinden bir nesne oluşturur, tek bir özelliği okur ve bir nesneyi JSON dizesine serileştirir.

Function	Syntax	Description	Example
Object	Object(key1, value1, key2, value2, ...)	Belirtilen anahtar-değer çiftlerinden bir Nesne oluşturur. Sıfır veya çift sayıda bağımsız değişken kabul eder.	Input: `Object("key1", "value1", "key2", "value2")` → Output: İlgili nesne, `{"key1": "value1", "key2": "value2"}`
ObjectIndex	ObjectIndex(user, "username")	Bir nesnenin belirtilen özelliğinin değerini döndürür.	`ObjectIndex(user, "username")` ifadesi `user.username` ile eşdeğerdir.
ObjectToJsonString	ObjectToJsonString(user.groups)	Bir nesneyi JSON dizesine dönüştürür.	-

Tarih ve saat işlevleri

Geçerli saati biçimlendirilmiş bir UTC dizesi veya UNIX zaman damgası olarak döndürür.

Function	Syntax	Description	Example
Now	Now()	Geçerli UTC tarih ve saatini `yyyy-MM-dd'T'HH:mm:ssXXX` biçiminde temsil eden bir dize döndürür.	Output: `2021-11-01T09:52:11Z`
CurrentTimeMillis	CurrentTimeMillis()	Geçerli saati milisaniye cinsinden UNIX zaman damgası olarak döndürür.	-

Telefon numarası işlevleri

ExtractPhoneRegion ve ExtractPhoneNumber bir cep telefonu numarasını bölge kodu ve numaranın kendisi olarak ayırır. İkisi de aynı parametreleri kabul eder; hangilerini ileteceğiniz numaranın biçimine bağlıdır.

Mobile phone number format	Parameters to pass
Includes a region code, and the region code is preceded by a plus sign (+)	You do not need to pass `autoAppendPlusSignal` and `defaultRegion`.
Includes a region code, and the region code is not preceded by a plus sign	Pass `autoAppendPlusSignal=true` and set `defaultRegion` to the default country or region code.
Does not include a region code, and you want to set a default region code	Pass `autoAppendPlusSignal=false` and set `defaultRegion` to the default country or region code.

ExtractPhoneRegion

ExtractPhoneRegion(source, defaultRegion,autoAppendPlusSignal) bir cep telefonu numarasından bölge kodunu çıkarır.

source: Cep telefonu numarası.
defaultRegion: Telefon bölge kodunun varsayılan ülkesi veya bölgesi. Ülke veya bölge kodu için ISO 3166 Ülke Kodları standardının alfa-2 kodunu kullanın; örneğin CN, US veya TW.
autoAppendPlusSignal: Artı işaretinin (+) otomatik olarak eklenip eklenmeyeceğini belirtir. true değeri işareti ekler, false değeri eklemez.

Örnekler:
Cep telefonu numarası +86131xxxxx000, +86 131xxxxx000 veya +86-131xxxxx000 ise: Input: ExtractPhoneRegion(idpUser.mobile) → Return: 86
Cep telefonu numarası 86131xxxxx000, 86 131xxxxx000 veya 86-131xxxxx000 ise: Input: ExtractPhoneRegion(idpUser.mobile, "CN", true) → Return: 86
Cep telefonu numarası 131xxxxx000 ise: Input: ExtractPhoneRegion(idpUser.mobile, "CN", false) → Return: 86

ExtractPhoneNumber

ExtractPhoneNumber(source, defaultRegion,autoAppendPlusSignal) bir cep telefonu numarasından bölge kodu olmadan gerçek cep telefonu numarasını çıkarır.

source: Cep telefonu numarası.
defaultRegion: Telefon bölge kodunun varsayılan ülkesi veya bölgesi. Ülke veya bölge kodu için ISO 3166 Ülke Kodları standardının alfa-2 kodunu kullanın; örneğin CN, US veya TW.
autoAppendPlusSignal: Artı işaretinin (+) otomatik olarak eklenip eklenmeyeceğini belirtir. true değeri işareti ekler, false değeri eklemez.

Örnekler:
Cep telefonu numarası +86131xxxxx000, +86 131xxxxx000 veya +86-131xxxxx000 ise: Input: ExtractPhoneNumber(idpUser.mobile) → Return: 131xxxxx000
Cep telefonu numarası 86131xxxxx000, 86 131xxxxx000 veya 86-131xxxxx000 ise: Input: ExtractPhoneNumber(idpUser.mobile, "CN", true) → Return: 131xxxxx000
Cep telefonu numarası 131xxxxx000 ise: Input: ExtractPhoneNumber(idpUser.mobile, "CN", false) → Return: 131xxxxx000

SAML işlevi

Function	Syntax	Description
SamlArray	SamlArray(Array())	Yalnızca SAML SSO için kullanılabilir.

Örnek:

Input: SamlArray(Array("group1","group2"))
SAML Yanıtı çıktısı. <saml2:Attribute Name="grouIdArray"NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"><saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xsd:string"> xsi:type="xsd:string"> group2 </saml2:AttributeValue></saml2:Attribute>

Yaygın ifade örnekleri

Yaygın senaryolar ve gerekli değeri üreten ifadeler:

Scenario	Example expression
Get the username and append the fixed string "@example.com".	`Append(user.username, "@example.com")`
Return the email address if the email address is not empty. If the email address is empty, return the mobile phone number.	`Coalesce(user.email, user.phoneNumber)`
Fill in a fixed mobile phone number by default if the mobile phone number is empty.	`IIF(IsNullOrEmpty(user.phoneNumber), "1888888****", user.phoneNumber)`
Join the phone region code and the mobile phone number with a hyphen (-).	`Join(user.phoneRegion, user.phoneNumber, "-")`
Return a custom welcome message that includes the display name.	`StringReplace("hello $DisplayName", "$DisplayName", user.displayName)`
Mask the middle four digits of the mobile phone number with asterisks (*).	`Append(Substring(user.phoneNumber, 0, 4), "****", Substring(user.phoneNumber, 8, 10))`
Extract the username from the email address.	`SubstringBefore(user.email, "@")`
Assemble the email field in the array format that the SCIM specification requires.	`Array(Object("email", user.email, "type", "work", "primary", true))`