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 存放庫中，尋找更多宣告轉換範例
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應