JSON 宣告轉換
本文提供的範例說明在 Azure Active Directory B2C (Azure AD B2C) 中使用 Identity Experience Framework (IEF) 結構描述的 JSON 宣告轉換。 如需詳細資訊,請參閱宣告轉換。
CreateJsonArray
從宣告值建立 JSON 單一元素陣列。 查看此宣告轉換的即時示範。
元素 | TransformationClaimType | 資料類型 | 注意 |
---|---|---|---|
InputClaim | inputClaim | 字串 | 要新增至輸出宣告的宣告。 |
OutputClaim | outputClaim | 字串 | 叫用此宣告轉換之後產生的 JSON 字串。 |
CreateJsonArray 範例
下列範例建立 JSON 單一陣列。
<ClaimsTransformation Id="createlJsonPayload" TransformationMethod="CreateJsonArray">
<InputClaims>
<InputClaim ClaimTypeReferenceId="email" TransformationClaimType="inputClaim" />
</InputClaims>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="result" TransformationClaimType="outputClaim" />
</OutputClaims>
</ClaimsTransformation>
- 輸入宣告:
- inputClaim:someone@example.com
- 輸出宣告:
- outputClaim:["someone@contoso.com"]
GenerateJson
使用宣告值或常數來產生 JSON 字串。 採用點標記法的路徑字串用於表示 JSON 字串中插入資料的位置。 以點分割之後,任何整數解譯為 JSON 陣列的索引,而非整數解譯為 JSON 物件的索引。
查看此宣告轉換的即時示範。
元素 | TransformationClaimType | 資料類型 | 注意 |
---|---|---|---|
InputClaim | 採用點標記法的任何字串 | 字串 | JSON 的 JsonPath,其中將插入宣告值。 |
InputParameter | 採用點標記法的任何字串 | 字串 | JSON 的 JsonPath,其中將插入常數字串值。 |
OutputClaim | outputClaim | 字串 | 產生的 JSON 字串。 |
JSON 陣列
若要將 JSON 物件新增至 JSON 陣列,請使用陣列名稱的格式和陣列中的索引。 陣列是以零為基底。 從零到 N 開始,不略過任何數字。 陣列中的項目可以包含任何物件。 例如,第一個項目包含兩個物件:app 和 appId。 第二個項目包含單一物件 program。 第三個項目包含四個物件、color、language、logo 和 background。
下列範例示範如何設定 JSON 陣列。
電子郵件陣列會搭配動態值使用 InputClaims
。
值陣列會搭配靜態值使用 InputParameters
。
<ClaimsTransformation Id="GenerateJsonPayload" TransformationMethod="GenerateJson">
<InputClaims>
<InputClaim ClaimTypeReferenceId="mailToName1" TransformationClaimType="emails.0.name" />
<InputClaim ClaimTypeReferenceId="mailToAddress1" TransformationClaimType="emails.0.address" />
<InputClaim ClaimTypeReferenceId="mailToName2" TransformationClaimType="emails.1.name" />
<InputClaim ClaimTypeReferenceId="mailToAddress2" TransformationClaimType="emails.1.address" />
</InputClaims>
<InputParameters>
<InputParameter Id="values.0.app" DataType="string" Value="Mobile app" />
<InputParameter Id="values.0.appId" DataType="string" Value="123" />
<InputParameter Id="values.1.program" DataType="string" Value="Holidays" />
<InputParameter Id="values.2.color" DataType="string" Value="Yellow" />
<InputParameter Id="values.2.language" DataType="string" Value="Spanish" />
<InputParameter Id="values.2.logo" DataType="string" Value="contoso.png" />
<InputParameter Id="values.2.background" DataType="string" Value="White" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="result" TransformationClaimType="outputClaim" />
</OutputClaims>
</ClaimsTransformation>
此宣告轉換的結果:
{
"values": [
{
"app": "Mobile app",
"appId": "123"
},
{
"program": "Holidays"
},
{
"color": "Yellow",
"language": "Spanish",
"logo": "contoso.png",
"background": "White"
}
],
"emails": [
{
"name": "Joni",
"address": "joni@contoso.com"
},
{
"name": "Emily",
"address": "emily@contoso.com"
}
]
}
若要在輸入宣告和輸入參數中指定 JSON 陣列,您必須在 InputClaims
元素中啟動陣列,從零到 N。然後,在 InputParameters
元素中,從最後一個索引繼續索引。
下列範例示範在輸入宣告和輸入參數中定義的陣列。
值陣列 values.0
的第一個項目定義於輸入宣告中。 輸入參數會繼續從索引一個 values.1
到兩個索引 values.2
。
<ClaimsTransformation Id="GenerateJsonPayload" TransformationMethod="GenerateJson">
<InputClaims>
<InputClaim ClaimTypeReferenceId="app" TransformationClaimType="values.0.app" />
<InputClaim ClaimTypeReferenceId="appId" TransformationClaimType="values.0.appId" />
</InputClaims>
<InputParameters>
<InputParameter Id="values.1.program" DataType="string" Value="Holidays" />
<InputParameter Id="values.2.color" DataType="string" Value="Yellow" />
<InputParameter Id="values.2.language" DataType="string" Value="Spanish" />
<InputParameter Id="values.2.logo" DataType="string" Value="contoso.png" />
<InputParameter Id="values.2.background" DataType="string" Value="White" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="result" TransformationClaimType="outputClaim" />
</OutputClaims>
</ClaimsTransformation>
GenerateJson 範例
下列範例根據 "email" 和 "OTP" 的宣告值及常數字串來產生 JSON 字串。
<ClaimsTransformation Id="GenerateRequestBody" TransformationMethod="GenerateJson">
<InputClaims>
<InputClaim ClaimTypeReferenceId="email" TransformationClaimType="personalizations.0.to.0.email" />
<InputClaim ClaimTypeReferenceId="otp" TransformationClaimType="personalizations.0.dynamic_template_data.otp" />
<InputClaim ClaimTypeReferenceId="copiedEmail" TransformationClaimType="personalizations.0.dynamic_template_data.verify-email" />
</InputClaims>
<InputParameters>
<InputParameter Id="template_id" DataType="string" Value="d-4c56ffb40fa648b1aa6822283df94f60"/>
<InputParameter Id="from.email" DataType="string" Value="service@contoso.com"/>
<InputParameter Id="personalizations.0.subject" DataType="string" Value="Contoso account email verification code"/>
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="requestBody" TransformationClaimType="outputClaim"/>
</OutputClaims>
</ClaimsTransformation>
下列宣告轉換會輸出 JSON 字串宣告,作為傳送至 SendGrid (協力廠商電子郵件提供者) 的要求主體。 JSON 物件的結構是以 InputParameter 的 ID (採用點標記法) 及 InputClaim 的 TransformationClaimType 來定義。 點標記法中的數字暗指陣列。 值來自於 InputClaim 的值和 InputParameter 的 "Value" 屬性。
- 輸入宣告:
- email,轉換宣告類型 personalizations.0.to.0.email:"someone@example.com"
- copiedEmail,轉換宣告類型 personalizations.0.dynamic_template_data.verify-email:"someone@example.com"
- otp,轉換宣告類型 personalizations.0.dynamic_template_data.otp "346349"
- 輸入參數:
- template_id:"d-4c56ffb40fa648b1aa6822283df94f60"
- from.email:"service@contoso.com"
- personalizations.0.subject "Contoso account email verification code"
- 輸出宣告:
outputClaim:
{ "personalizations": [ { "to": [ { "email": "someone@example.com" } ], "dynamic_template_data": { "otp": "346349", "verify-email" : "someone@example.com" }, "subject": "Contoso account email verification code" } ], "template_id": "d-989077fbba9746e89f3f6411f596fb96", "from": { "email": "service@contoso.com" } }
GenerateJson 的另一個範例
下列範例根據宣告值和常數字串來產生 JSON 字串。
<ClaimsTransformation Id="GenerateRequestBody" TransformationMethod="GenerateJson">
<InputClaims>
<InputClaim ClaimTypeReferenceId="email" TransformationClaimType="customerEntity.email" />
<InputClaim ClaimTypeReferenceId="objectId" TransformationClaimType="customerEntity.userObjectId" />
<InputClaim ClaimTypeReferenceId="givenName" TransformationClaimType="customerEntity.firstName" />
<InputClaim ClaimTypeReferenceId="surname" TransformationClaimType="customerEntity.lastName" />
</InputClaims>
<InputParameters>
<InputParameter Id="customerEntity.role.name" DataType="string" Value="Administrator"/>
<InputParameter Id="customerEntity.role.id" DataType="long" Value="1"/>
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="requestBody" TransformationClaimType="outputClaim"/>
</OutputClaims>
</ClaimsTransformation>
下列宣告轉換會輸出 JSON 字串宣告,作為傳送至 REST API 的要求主體。 JSON 物件的結構是以 InputParameter 的 ID (採用點標記法) 及 InputClaim 的 TransformationClaimType 來定義。 值來自於 InputClaim 的值和 InputParameter 的 "Value" 屬性。
- 輸入宣告:
- email,轉換宣告類型 customerEntity.email:"john.s@contoso.com"
- objectId,轉換宣告類型 customerEntity.userObjectId "01234567-89ab-cdef-0123-456789abcdef"
- givenName,轉換宣告類型 customerEntity.firstName "John"
- surname,轉換宣告類型 customerEntity.lastName "Smith"
- 輸入參數:
- customerEntity.role.name:"Administrator"
- customerEntity.role.id 1
- 輸出宣告:
requestBody:
{ "customerEntity":{ "email":"john.s@contoso.com", "userObjectId":"01234567-89ab-cdef-0123-456789abcdef", "firstName":"John", "lastName":"Smith", "role":{ "name":"Administrator", "id": 1 } } }
GenerateJson宣告轉換接受純字串。 如果輸入宣告包含 JSON 字串,則會逸出該字串。 在下列範例中,如果您使用 上述 CreateJsonArray的電子郵件輸出,也就是 [「 someone@contoso.com 」],作為輸入參數,電子郵件看起來會如下列 JSON 宣告所示:
- 輸出宣告:
requestBody:
{ "customerEntity":{ "email":"[\"someone@contoso.com\"]", "userObjectId":"01234567-89ab-cdef-0123-456789abcdef", "firstName":"John", "lastName":"Smith", "role":{ "name":"Administrator", "id": 1 } } }
GetClaimFromJson
從 JSON 資料中取得指定的元素。 查看此宣告轉換的即時示範。
元素 | TransformationClaimType | 資料類型 | 注意 |
---|---|---|---|
InputClaim | inputJson | 字串 | 由宣告轉換用來取得項目的宣告。 |
InputParameter | claimToExtract | 字串 | 要擷取的 JSON 元素名稱。 |
OutputClaim | extractedClaim | 字串 | 叫用此宣告轉換之後產生的宣告,即 claimToExtract 輸入參數中指定的元素值。 |
GetClaimFromJson 範例
在下列範例中,宣告轉換會從 JSON 資料擷取 emailAddress
元素:{"emailAddress": "someone@example.com", "displayName": "Someone"}
<ClaimsTransformation Id="GetEmailClaimFromJson" TransformationMethod="GetClaimFromJson">
<InputClaims>
<InputClaim ClaimTypeReferenceId="customUserData" TransformationClaimType="inputJson" />
</InputClaims>
<InputParameters>
<InputParameter Id="claimToExtract" DataType="string" Value="emailAddress" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="extractedEmail" TransformationClaimType="extractedClaim" />
</OutputClaims>
</ClaimsTransformation>
- 輸入宣告:
- inputJson:{"emailAddress": "", "displayName": "Someone"}
- 輸入參數:
- claimToExtract:emailAddress
- 輸出宣告:
- extractedClaim:
GetClaimFromJson 的另一個範例
GetClaimFromJson 宣告轉換從 JSON 資料中取得單一元素。 即上述範例中的 emailAddress。 若要取得 displayName,請建立另一個宣告轉換。 例如:
<ClaimsTransformation Id="GetDispalyNameClaimFromJson" TransformationMethod="GetClaimFromJson">
<InputClaims>
<InputClaim ClaimTypeReferenceId="customUserData" TransformationClaimType="inputJson" />
</InputClaims>
<InputParameters>
<InputParameter Id="claimToExtract" DataType="string" Value="displayName" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="displayName" TransformationClaimType="extractedClaim" />
</OutputClaims>
</ClaimsTransformation>
- 輸入宣告:
- inputJson:{"emailAddress": "", "displayName": "Someone"}
- 輸入參數:
- claimToExtract:displayName
- 輸出宣告:
- extractedClaim:Someone
GetClaimsFromJsonArray
從 JSON 資料中取得指定元素的清單。 查看此宣告轉換的即時示範。
元素 | TransformationClaimType | 資料類型 | 注意 |
---|---|---|---|
InputClaim | jsonSourceClaim | 字串 | 具有 JSON 承載的宣告。 宣告轉換使用此宣告來取得宣告。 |
InputParameter | errorOnMissingClaims | boolean | 指定如果遺漏其中一個宣告,是否要擲回錯誤。 |
InputParameter | includeEmptyClaims | 字串 | 指定是否要包含空的宣告。 |
InputParameter | jsonSourceKeyName | 字串 | 元素索引鍵名稱 |
InputParameter | jsonSourceValueName | 字串 | 元素值名稱 |
OutputClaim | 集合 | string、int、boolean 及 datetime | 要擷取的宣告清單。 宣告的名稱應該等於 jsonSourceClaim 輸入宣告中所指定的宣告名稱。 |
GetClaimsFromJsonArray 範例
在下列範例中,宣告轉換從 JSON 資料中擷取下列宣告:email (string)、displayName (string)、membershipNum (int)、active (boolean) 及 birthdate (datetime)。
<ClaimsTransformation Id="GetClaimsFromJson" TransformationMethod="GetClaimsFromJsonArray">
<InputClaims>
<InputClaim ClaimTypeReferenceId="jsonSourceClaim" TransformationClaimType="jsonSource" />
</InputClaims>
<InputParameters>
<InputParameter Id="errorOnMissingClaims" DataType="boolean" Value="false" />
<InputParameter Id="includeEmptyClaims" DataType="boolean" Value="false" />
<InputParameter Id="jsonSourceKeyName" DataType="string" Value="key" />
<InputParameter Id="jsonSourceValueName" DataType="string" Value="value" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="email" />
<OutputClaim ClaimTypeReferenceId="displayName" />
<OutputClaim ClaimTypeReferenceId="membershipID" />
<OutputClaim ClaimTypeReferenceId="active" />
<OutputClaim ClaimTypeReferenceId="birthDate" />
</OutputClaims>
</ClaimsTransformation>
輸入宣告:
jsonSourceClaim:
[ { "key": "email", "value": "someone@example.com" }, { "key": "displayName", "value": "Someone" }, { "key": "membershipID", "value": 6353399 }, { "key": "active", "value": true }, { "key": "birthDate", "value": "2005-09-23T00:00:00Z" } ]
輸入參數:
- errorOnMissingClaims:false
- includeEmptyClaims:false
- jsonSourceKeyName:key
- jsonSourceValueName:value
輸出宣告:
- email:"someone@example.com"
- displayName:"Someone"
- membershipID:6353399
- active:true
- birthDate:2005-09-23T00:00:00Z
GetClaimsFromJsonArrayV2
從字串集合 JSON 元素取得指定專案的清單。 查看此宣告轉換的即時示範。
元素 | TransformationClaimType | 資料類型 | 注意 |
---|---|---|---|
InputClaim | jsonSourceClaim | stringCollection | 具有 JSON 承載的字串集合宣告。 宣告轉換使用此宣告來取得宣告。 |
InputParameter | errorOnMissingClaims | boolean | 指定如果遺漏其中一個宣告,是否要擲回錯誤。 |
InputParameter | includeEmptyClaims | 字串 | 指定是否要包含空的宣告。 |
InputParameter | jsonSourceKeyName | 字串 | 元素索引鍵名稱 |
InputParameter | jsonSourceValueName | 字串 | 元素值名稱 |
OutputClaim | 集合 | string、int、boolean 及 datetime | 要擷取的宣告清單。 宣告的名稱應該等於 jsonSourceClaim 輸入宣告中所指定的宣告名稱。 |
GetClaimsFromJsonArrayV2 的範例
在下列範例中,宣告轉換從 JSON 資料中擷取下列宣告:email (string)、displayName (string)、membershipNum (int)、active (boolean) 及 birthdate (datetime)。
<ClaimsTransformation Id="GetClaimsFromJson" TransformationMethod="GetClaimsFromJsonArrayV2">
<InputClaims>
<InputClaim ClaimTypeReferenceId="jsonSourceClaim" TransformationClaimType="jsonSource" />
</InputClaims>
<InputParameters>
<InputParameter Id="errorOnMissingClaims" DataType="boolean" Value="false" />
<InputParameter Id="includeEmptyClaims" DataType="boolean" Value="false" />
<InputParameter Id="jsonSourceKeyName" DataType="string" Value="key" />
<InputParameter Id="jsonSourceValueName" DataType="string" Value="value" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="email" />
<OutputClaim ClaimTypeReferenceId="displayName" />
<OutputClaim ClaimTypeReferenceId="membershipID" />
<OutputClaim ClaimTypeReferenceId="active" />
<OutputClaim ClaimTypeReferenceId="birthDate" />
</OutputClaims>
</ClaimsTransformation>
輸入宣告:
jsonSourceClaim[0] (字串集合第一個專案) :
{ "key": "email", "value": "someone@example.com" }
jsonSourceClaim[1] (字串集合第二個專案) :
{ "key": "displayName", "value": "Someone" }
jsonSourceClaim[2] (字串集合第三個專案) :
{ "key": "membershipID", "value": 6353399 }
jsonSourceClaim[3] (字串集合第四個專案) :
{ "key": "active", "value": true }
jsonSourceClaim[4] (字串集合第五個專案) :
{ "key": "birthDate", "value": "2005-09-23T00:00:00Z" }
輸入參數:
- errorOnMissingClaims:false
- includeEmptyClaims:false
- jsonSourceKeyName:key
- jsonSourceValueName:value
輸出宣告:
- email:"someone@example.com"
- displayName:"Someone"
- membershipID:6353399
- active:true
- birthDate:2005-09-23T00:00:00Z
GetNumericClaimFromJson
從 JSON 資料中取得指定的數值 (long) 元素。 查看此宣告轉換的即時示範。
元素 | TransformationClaimType | 資料類型 | 注意 |
---|---|---|---|
InputClaim | inputJson | 字串 | 具有 JSON 承載的宣告。 宣告轉換使用此宣告來取得數值宣告。 |
InputParameter | claimToExtract | 字串 | 要擷取的 JSON 元素名稱。 |
OutputClaim | extractedClaim | long | 叫用此宣告轉換之後產生的宣告,即 claimToExtract 輸入參數中指定的元素值。 |
GetNumericClaimFromJson 範例
在下列範例中,宣告轉換會從 JSON 資料中擷取 id
元素。
<ClaimsTransformation Id="GetIdFromResponse" TransformationMethod="GetNumericClaimFromJson">
<InputClaims>
<InputClaim ClaimTypeReferenceId="exampleInputClaim" TransformationClaimType="inputJson" />
</InputClaims>
<InputParameters>
<InputParameter Id="claimToExtract" DataType="string" Value="id" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="membershipId" TransformationClaimType="extractedClaim" />
</OutputClaims>
</ClaimsTransformation>
輸入宣告:
inputJson:
{ "emailAddress": "someone@example.com", "displayName": "Someone", "id": 6353399 }
輸入參數
- claimToExtract:id
輸出宣告:
- extractedClaim:6353399
GetSingleItemFromJson
從 JSON 資料中取得第一個元素。 查看此宣告轉換的即時示範。
元素 | TransformationClaimType | 資料類型 | 注意 |
---|---|---|---|
InputClaim | inputJson | 字串 | 具有 JSON 承載的宣告。 宣告轉換使用此宣告從 JSON 資料中取得項目。 |
OutputClaim | 索引鍵 | 字串 | JSON 中的第一個元素索引鍵。 |
OutputClaim | value | 字串 | JSON 中的第一個元素值。 |
GetSingleItemFromJson 範例
在下列範例中,宣告轉換從 JSON 資料中擷取第一個元素 (名字)。
<ClaimsTransformation Id="GetGivenNameFromResponse" TransformationMethod="GetSingleItemFromJson">
<InputClaims>
<InputClaim ClaimTypeReferenceId="json" TransformationClaimType="inputJson" />
</InputClaims>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="givenNameKey" TransformationClaimType="key" />
<OutputClaim ClaimTypeReferenceId="givenName" TransformationClaimType="value" />
</OutputClaims>
</ClaimsTransformation>
輸入宣告:
inputJson:
{ "givenName": "Emily", "lastName": "Smith" }
輸出宣告:
- key:givenName
- value:Emilty
GetSingleValueFromJsonArray
從 JSON 資料陣列中取得第一個元素。 查看此宣告轉換的即時示範。
元素 | TransformationClaimType | 資料類型 | 注意 |
---|---|---|---|
InputClaim | inputJsonClaim | 字串 | 具有 JSON 承載的宣告。 宣告轉換使用此宣告從 JSON 陣列中取得值。 |
OutputClaim | extractedClaim | 字串 | 叫用此宣告轉換之後產生的宣告,即 JSON 陣列中的第一個元素。 |
GetSingleValueFromJsonArray 範例
在下列範例中,宣告轉換從 JSON 陣列 ["someone@example.com", "Someone", 6353399]
中擷取第一個元素 (電子郵件地址)。
<ClaimsTransformation Id="GetEmailFromJson" TransformationMethod="GetSingleValueFromJsonArray">
<InputClaims>
<InputClaim ClaimTypeReferenceId="userData" TransformationClaimType="inputJsonClaim" />
</InputClaims>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="email" TransformationClaimType="extractedClaim" />
</OutputClaims>
</ClaimsTransformation>
- 輸入宣告:
- inputJsonClaim["", "Someone", 6353399]
- 輸出宣告:
- extractedClaim:
XmlStringToJsonString
將 XML 資料轉換為 JSON 格式。 查看此宣告轉換的即時示範。
元素 | TransformationClaimType | 資料類型 | 注意 |
---|---|---|---|
InputClaim | Xml | 字串 | 具有 XML 承載的宣告。 宣告轉換使用此宣告將資料從 XML 轉換為 JSON 格式。 |
OutputClaim | json | 字串 | 叫用此宣告轉換之後產生的宣告,即 JSON 格式的資料。 |
<ClaimsTransformation Id="ConvertXmlToJson" TransformationMethod="XmlStringToJsonString">
<InputClaims>
<InputClaim ClaimTypeReferenceId="intpuXML" TransformationClaimType="xml" />
</InputClaims>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="outputJson" TransformationClaimType="json" />
</OutputClaims>
</ClaimsTransformation>
XmlStringToJsonString 範例
在下列範例中,宣告轉換會將下列 XML 資料轉換為 JSON 格式。
輸入宣告:
<user>
<name>Someone</name>
<email>someone@example.com</email>
</user>
輸出宣告:
{
"user": {
"name":"Someone",
"email":"someone@example.com"
}
}
下一步
- 在 Azure AD B2C 社群 GitHub 存放庫中,尋找更多宣告轉換範例