JSON 宣告轉換
本文提供在 Azure Active Directory B2C (Azure AD B2C) 中使用身分識別體驗架構架構 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。 第二個專案包含單一物件 程式。 第三個專案包含四個物件: 色彩、 語言、 標誌 和 背景。
下列範例示範如何設定 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" 屬性。
- 輸入宣告:
- 電子郵件,轉換宣告類型 personalizations.0.to.0.email:“someone@example.com”
- copiedEmail, transformation claim type 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 帳戶電子郵件驗證碼”
- 輸出宣告:
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" 屬性。
- 輸入宣告:
- 電子郵件,轉換宣告類型 customerEntity.email:“john.s@contoso.com”
- objectId, transformation claim type customerEntity.userObjectId “aaaaaaaa-0000-1111-2222-bbbbbbbb”
- givenName, transformation claim type customerEntity.firstName “John”
- surname, transformation claim type customerEntity.lastName “Smith”
- 輸入參數:
- customerEntity.role.name:“系統管理員”
- customerEntity.role.id 1
- 輸出宣告:
requestBody:
{ "customerEntity":{ "email":"john.s@contoso.com", "userObjectId":"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", "firstName":"John", "lastName":"Smith", "role":{ "name":"Administrator", "id": 1 } } }
GenerateJson 宣告轉換接受純字串。 如果輸入宣告包含 JSON 字串,則會逸出該字串。 在下列範例中,如果您使用上述 CreateJsonArray 的電子郵件輸出,也就是 [“”someone@contoso.com],做為輸入參數,電子郵件看起來會如下列 JSON 宣告所示:
- 輸出宣告:
requestBody:
{ "customerEntity":{ "email":"[\"someone@contoso.com\"]", "userObjectId":"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", "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”: “someone@example.com”, “displayName”: “Someone”}
- 輸入參數:
- claimToExtract:emailAddress
- 輸出宣告:
- extractedClaim: someone@example.com
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”: “someone@example.com”, “displayName”: “Someone”}
- 輸入參數:
- claimToExtract:displayName
- 輸出宣告:
- extractedClaim:某人
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
輸出宣告:
- 電子郵件:“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
輸出宣告:
- 電子郵件:“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 | key | 字串 | 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" }
輸出宣告:
- 機碼: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@example.com, “Someone”, 6353399]
- 輸出宣告:
- extractedClaim: someone@example.com
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 存放庫上尋找更多宣告轉換範例