共用方式為


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 開始,而不略過任何數位。 陣列中的專案可以包含任何物件。 例如,第一個專案包含兩個物件 :appappId。 第二個專案包含單一物件 程式。 第三個專案包含四個物件: 色彩語言標誌背景

下列範例示範如何設定 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"
  }
}

下一步