JSON 声明转换

项目
10/14/2024

本文提供了在 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	点表示法后面的任何字符串	string	JSON 的 JsonPath，声明值将插入到其中。
InputParameter	点表示法后面的任何字符串	string	JSON 的 JsonPath，常量字符串值将插入到其中。
OutputClaim	outputClaim	string	生成的 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 的第一项在输入声明中定义。输入参数从索引 1 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 对象的结构由 InputClaims 的 InputParameters 和 TransformationClaimTypes 的点表示法中的 ID 定义。点表示法中的数字表示数组。值来自 InputClaims 的值和 InputParameters 的“Value”属性。

输入声明：
- 电子邮件，转换声明类型 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 帐户电子邮件验证码"

输出声明：

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 对象的结构由 InputClaims 的 InputParameters 和 TransformationClaimTypes 的点表示法中的 ID 定义。值来自 InputClaims 的值和 InputParameters 的“Value”属性。

输入声明：
- 电子邮件，转换声明类型 customerEntity.email：“john.s@contoso.com”
- objectId, transformation claim type customerEntity.userObjectId "01234567-89ab-cdef-0123-456789abcdef"
- givenName, transformation claim type customerEntity.firstName "John"
- surname, transformation claim type 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	string	由声明转换用于获取项的声明。
InputParameter	claimToExtract	string	要提取的 JSON 元素的名称。
OutputClaim	extractedClaim	string	调用此声明转换后生成的声明，即 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：Someone

GetClaimsFromJsonArray

从 Json 数据中获取指定元素列表。查看此声明转换的实时演示。

元素	TransformationClaimType	数据类型	说明
InputClaim	jsonSourceClaim	string	具有 JSON 有效负载的声明。此声明由声明转换用于获取声明。
InputParameter	errorOnMissingClaims	boolean	指定如果缺少一个声明是否引发错误。
InputParameter	includeEmptyClaims	string	指定是否包含空声明。
InputParameter	jsonSourceKeyName	string	元素键名称
InputParameter	jsonSourceValueName	string	元素值名称
OutputClaim	集合	字符串、int、布尔值，和日期时间	要提取的声明列表。声明名称应等于 jsonSourceClaim 输入声明中指定的名称。

GetClaimsFromJsonArray 示例

在以下示例中，声明转换从 JSON 数据中提取以下声明：email（字符串）、displayName（字符串）、membershipNum (int)、active（布尔值）和 birthDate（日期时间）。

<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	string	指定是否包含空声明。
InputParameter	jsonSourceKeyName	string	元素键名称
InputParameter	jsonSourceValueName	string	元素值名称
OutputClaim	集合	字符串、int、布尔值，和日期时间	要提取的声明列表。声明名称应等于 jsonSourceClaim 输入声明中指定的名称。

GetClaimsFromJsonArrayV2 示例

<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	string	具有 JSON 有效负载的声明。此声明由声明转换用于获取数字声明。
InputParameter	claimToExtract	string	要提取的 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	string	具有 JSON 有效负载的声明。此声明由声明转换用于从 JSON 数据中获取项。
OutputClaim	key	string	JSON 中的第一个元素键。
OutputClaim	value	string	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	string	具有 JSON 有效负载的声明。此声明由声明转换用于从 JSON 数组中获取值。
OutputClaim	extractedClaim	string	调用此声明后生成的声明，即 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	string	具有 XML 有效负载的声明。此声明由声明转换用于将数据从 XML 转换为 JSON 格式。
OutputClaim	json	string	调用此声明转换后生成的声明，即采用 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 存储库中查看更多声明转换示例

通过

JSON 声明转换

CreateJsonArray

CreateJsonArray 示例

GenerateJson

JSON 数组

GenerateJson 示例

GenerateJson 的另一个示例

GetClaimFromJson

GetClaimFromJson 示例

另一个 GetClaimFromJson 示例

GetClaimsFromJsonArray

GetClaimsFromJsonArray 示例

GetClaimsFromJsonArrayV2

GetClaimsFromJsonArrayV2 示例

GetNumericClaimFromJson

GetNumericClaimFromJson 示例

GetSingleItemFromJson

GetSingleItemFromJson 示例

GetSingleValueFromJsonArray

GetSingleValueFromJsonArray 示例

XmlStringToJsonString

XmlStringToJsonString 示例

后续步骤

其他资源