JSON 声明转换JSON claims transformations

Note

在 Azure Active Directory B2C 中,custom policies 主要用于解决复杂方案。In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. 大多数情况下,建议使用内置的用户流For most scenarios, we recommend that you use built-in user flows.

本文提供了在 Azure Active Directory B2C (Azure AD B2C) 中使用标识体验框架架构的 JSON 声明转换的示例。This article provides examples for using the JSON claims transformations of the Identity Experience Framework schema in Azure Active Directory B2C (Azure AD B2C). 有关详细信息,请参阅 ClaimsTransformationsFor more information, see ClaimsTransformations.

GenerateJsonGenerateJson

使用声明值或常量生成 JSON 字符串。Use either claim values or constants to generate a JSON string. 点表示法后面的路径字符串用于指示将数据插入 JSON 字符串的位置。The path string following dot notation is used to indicate where to insert the data into a JSON string. 按点拆分后,任何整数都解释为 JSON 数组的索引,而非整数则解释为 JSON 对象的索引。After splitting by dots, any integers are interpreted as the index of a JSON array and non-integers are interpreted as the index of a JSON object.

项目Item TransformationClaimTypeTransformationClaimType 数据类型Data Type 注释Notes
InputClaimInputClaim 点表示法后面的任何字符串Any string following dot notation stringstring JSON 的 JsonPath,声明值将插入到其中。The JsonPath of the JSON where the claim value will be inserted into.
InputParameterInputParameter 点表示法后面的任何字符串Any string following dot notation stringstring JSON 的 JsonPath,常量字符串值将插入到其中。The JsonPath of the JSON where the constant string value will be inserted into.
OutputClaimOutputClaim outputClaimoutputClaim stringstring 生成的 JSON 字符串。The generated JSON string.

以下示例基于“email”和“otp”的声明值以及常量字符串生成 JSON 字符串。The following example generates a JSON string based on the claim value of "email" and "otp" as well as constant strings.

<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" />
  </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>

示例Example

以下声明转换输出一个 JSON 字符串声明,该声明将作为发送到 SendGrid (第三方电子邮件提供程序)的请求正文。The following claims transformation outputs a JSON string claim that will be the body of the request sent to SendGrid (a third-party email provider). JSON 对象的结构由 InputClaims 的 InputParameters 和 TransformationClaimTypes 的点表示法中的 ID 定义。The JSON object's structure is defined by the IDs in dot notation of the InputParameters and the TransformationClaimTypes of the InputClaims. 点表示法中的数字表示数组。Numbers in the dot notation imply arrays. 值来自 InputClaims 的值和 InputParameters 的“Value”属性。The values come from the InputClaims' values and the InputParameters' "Value" properties.

  • 输入声明:Input claims :
    • email, 转换声明类型 personalizations.0.to.0.email: "someone@example.com"email, transformation claim type personalizations.0.to.0.email: "someone@example.com"
    • otp, 转换声明类型 personalizations.0.dynamic_template_data.otp "346349"otp, transformation claim type personalizations.0.dynamic_template_data.otp "346349"
  • 输入参数:Input parameter:
    • template_id: "d-4c56ffb40fa648b1aa6822283df94f60"template_id: "d-4c56ffb40fa648b1aa6822283df94f60"
    • from.email: "service@contoso.com"from.email: "service@contoso.com"
    • personalizations.0.subject "Contoso 帐户电子邮件验证码"personalizations.0.subject "Contoso account email verification code"
  • 输出声明:Output claim:
    • requestBody:JSON 值requestBody: JSON value
{
  "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"
  }
}

GetClaimFromJsonGetClaimFromJson

从 JSON 数据中获取指定的元素。Get a specified element from a JSON data.

项目Item TransformationClaimTypeTransformationClaimType 数据类型Data Type 注释Notes
InputClaimInputClaim inputJsoninputJson stringstring 由声明转换用于获取项的 ClaimTypes。The ClaimTypes that are used by the claims transformation to get the item.
InputParameterInputParameter claimToExtractclaimToExtract stringstring 要提取的 JSON 元素的名称。the name of the JSON element to be extracted.
OutputClaimOutputClaim extractedClaimextractedClaim stringstring 调用此声明转换后生成的 ClaimType,即 claimToExtract 输入参数中指定的元素值。The ClaimType that is produced after this claims transformation has been invoked, the element value specified in the claimToExtract input parameter.

在以下示例中,声明转换提取 JSON 数据中的 emailAddress 元素:{"emailAddress": "someone@example.com", "displayName": "Someone"}In the following example, the claims transformation extracted the emailAddress element from the JSON data: {"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>

示例Example

  • 输入声明:Input claims:
    • inputJson: {"emailAddress": "someone@example.com", "displayName":"Someone"}inputJson: {"emailAddress": "someone@example.com", "displayName": "Someone"}
  • 输入参数:Input parameter:
    • claimToExtract: emailAddressclaimToExtract: emailAddress
  • 输出声明:Output claims:
    • extractedClaim: someone@example.comextractedClaim: someone@example.com

GetClaimsFromJsonArrayGetClaimsFromJsonArray

从 Json 数据中获取指定元素列表。Get a list of specified elements from Json data.

项目Item TransformationClaimTypeTransformationClaimType 数据类型Data Type 注释Notes
InputClaimInputClaim jsonSourceClaimjsonSourceClaim stringstring 由声明转换用于获取声明的 ClaimTypes。The ClaimTypes that are used by the claims transformation to get the claims.
InputParameterInputParameter errorOnMissingClaimserrorOnMissingClaims booleanboolean 指定如果缺少一个声明是否引发错误。Specifies whether to throw an error if one of the claims is missing.
InputParameterInputParameter includeEmptyClaimsincludeEmptyClaims stringstring 指定是否包含空声明。Specify whether to include empty claims.
InputParameterInputParameter jsonSourceKeyNamejsonSourceKeyName stringstring 元素键名称Element key name
InputParameterInputParameter jsonSourceValueNamejsonSourceValueName stringstring 元素值名称Element value name
OutputClaimOutputClaim 集合Collection 字符串、int、布尔值,和日期时间string, int, boolean, and datetime 要提取的声明列表。List of claims to extract. 声明名称应等于 jsonSourceClaim 输入声明中指定的名称。The name of the claim should be equal to the one specified in jsonSourceClaim input claim.

在以下示例中,声明转换从 JSON 数据中提取以下声明:email(字符串)、displayName(字符串)、membershipNum (int)、active(布尔值)和 birthdate(日期时间)。In the following example, the claims transformation extracts the following claims: email (string), displayName (string), membershipNum (int), active (boolean) and birthdate (datetime) from the JSON data.

[{"key":"email","value":"someone@example.com"}, {"key":"displayName","value":"Someone"}, {"key":"membershipNum","value":6353399}, {"key":"active","value":true}, {"key":"birthdate","value":"1980-09-23T00:00:00Z"}]
<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="membershipNum" />
    <OutputClaim ClaimTypeReferenceId="active" />
    <OutputClaim ClaimTypeReferenceId="birthdate" />
  </OutputClaims>
</ClaimsTransformation>
  • 输入声明:Input claims:
    • jsonSourceClaim: [{"key":"email","value":"someone@example.com"}, {"key":"displayName","value":"Someone"}, {"key":"membershipNum","value":6353399}, {"key":"active","value": true}, {"key":"birthdate","value":"1980-09-23T00:00:00Z"}]jsonSourceClaim: [{"key":"email","value":"someone@example.com"}, {"key":"displayName","value":"Someone"}, {"key":"membershipNum","value":6353399}, {"key":"active","value": true}, {"key":"birthdate","value":"1980-09-23T00:00:00Z"}]
  • 输入参数:Input parameters:
    • errorOnMissingClaims: falseerrorOnMissingClaims: false
    • includeEmptyClaims: falseincludeEmptyClaims: false
    • jsonSourceKeyName: keyjsonSourceKeyName: key
    • jsonSourceValueName: valuejsonSourceValueName: value
  • 输出声明:Output claims:
    • email: "someone@example.com"email: "someone@example.com"
    • displayName:"Someone"displayName: "Someone"
    • membershipNum:6353399membershipNum: 6353399
    • active: trueactive: true
    • birthdate:1980-09-23T00:00:00Zbirthdate: 1980-09-23T00:00:00Z

GetNumericClaimFromJsonGetNumericClaimFromJson

从 JSON 数据中获取指定的数值 (long) 元素。Gets a specified numeric (long) element from a JSON data.

项目Item TransformationClaimTypeTransformationClaimType 数据类型Data Type 注释Notes
InputClaimInputClaim inputJsoninputJson stringstring 由声明转换用于获取声明的 ClaimTypes。The ClaimTypes that are used by the claims transformation to get the claim.
InputParameterInputParameter claimToExtractclaimToExtract stringstring 要提取的 JSON 元素的名称。The name of the JSON element to extract.
OutputClaimOutputClaim extractedClaimextractedClaim longlong 调用此 ClaimsTransformation 后生成的 ClaimType,即 claimToExtract 输入参数中指定的元素值。The ClaimType that is produced after this ClaimsTransformation has been invoked, the element's value specified in the claimToExtract input parameters.

在以下示例中,声明转换提取 JSON 数据中的 id 元素。In the following example, the claims transformation extracts the id element from the JSON data.

{
    "emailAddress": "someone@example.com",
    "displayName": "Someone",
    "id" : 6353399
}
<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>

示例Example

  • 输入声明:Input claims:
    • inputJson: {"emailAddress": "someone@example.com", "displayName":"Someone", "id" :6353399}inputJson: {"emailAddress": "someone@example.com", "displayName": "Someone", "id" : 6353399}
  • 输入参数Input parameters
    • claimToExtract: idclaimToExtract: id
  • 输出声明:Output claims:
    • extractedClaim:6353399extractedClaim: 6353399

GetSingleItemFromJsonGetSingleItemFromJson

从 JSON 数据中获取第一个元素。Gets the first element from a JSON data.

项目Item TransformationClaimTypeTransformationClaimType 数据类型Data Type 注释Notes
InputClaimInputClaim inputJsoninputJson stringstring ClaimType,由声明转换用于从 JSON 数据中获取项。The ClaimTypes that are used by the claims transformation to get the item from the JSON data.
OutputClaimOutputClaim keykey stringstring JSON 中的第一个元素键。The first element key in the JSON.
OutputClaimOutputClaim valuevalue stringstring JSON 中的第一个元素值。The first element value in the JSON.

在下面的示例中,声明转换从 JSON 数据中提取第一个元素(名字)。In the following example, the claims transformation extracts the first element (given name) from the JSON data.

<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>

示例Example

  • 输入声明:Input claims:
    • inputJson: {"givenName":"Emilty", "lastName":"Smith"}inputJson: {"givenName": "Emilty", "lastName": "Smith"}
  • 输出声明:Output claims:
    • key: givenNamekey: givenName
    • value:Emiltyvalue: Emilty

GetSingleValueFromJsonArrayGetSingleValueFromJsonArray

从 JSON 数据数组中获取第一个元素。Gets the first element from a JSON data array.

项目Item TransformationClaimTypeTransformationClaimType 数据类型Data Type 注释Notes
InputClaimInputClaim inputJsonClaiminputJsonClaim stringstring 由声明转换用于从 JSON 数组中获取项的 ClaimTypes。The ClaimTypes that are used by the claims transformation to get the item from the JSON array.
OutputClaimOutputClaim extractedClaimextractedClaim stringstring 调用此 ClaimsTransformation 后生成的 ClaimType,即 JSON 数组中的第一个元素。The ClaimType that is produced after this ClaimsTransformation has been invoked, the first element in the JSON array.

在以下示例中,声明转换提取 JSON 数组 ["someone@example.com", "Someone", 6353399] 中的第一个元素(电子邮件地址)。In the following example, the claims transformation extracts the first element (email address) from the JSON array ["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>

示例Example

  • 输入声明:Input claims:
    • inputJsonClaim: ["someone@example.com", "Someone", 6353399]inputJsonClaim: ["someone@example.com", "Someone", 6353399]
  • 输出声明:Output claims:
    • extractedClaim: someone@example.comextractedClaim: someone@example.com

XmlStringToJsonStringXmlStringToJsonString

将 XML 数据转换为 JSON 格式。Converts XML data to JSON format.

项目Item TransformationClaimTypeTransformationClaimType 数据类型Data Type 注释Notes
InputClaimInputClaim xmlxml stringstring 由声明转换用于将数据从 XML 转换为 JSON 格式的 ClaimTypes。The ClaimTypes that are used by the claims transformation to convert the data from XML to JSON format.
OutputClaimOutputClaim jsonjson stringstring 调用此 ClaimsTransformation 后生成的 ClaimType,即采用 JSON 格式的数据。The ClaimType that is produced after this ClaimsTransformation has been invoked, the data in JSON format.
<ClaimsTransformation Id="ConvertXmlToJson" TransformationMethod="XmlStringToJsonString">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="intpuXML" TransformationClaimType="xml" />
  </InputClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="outputJson" TransformationClaimType="json" />
  </OutputClaims>
</ClaimsTransformation>

在以下示例中,声明转换将以下 XML 数据转换为 JSON 格式。In the following example, the claims transformation converts the following XML data to JSON format.

示例Example

输入声明:Input claim:

<user>
  <name>Someone</name>
  <email>someone@example.com</email>
</user>

输出声明:Output claim:

{
  "user": {
    "name":"Someone",
    "email":"someone@example.com"
  }
}