在 Azure AD B2C 中定義電話號碼宣告轉換

發行項
01/11/2024

本文提供在 Azure Active Directory B2C (Azure AD B2C) 自訂原則中，使用電話號碼宣告轉換的參考與範例。如需一般宣告轉換的詳細資訊，請參閱 ClaimsTransformations。

注意

這項功能處於公開預覽狀態。

ConvertPhoneNumberClaimToString

將 phoneNumber 資料類型轉換成 string 資料類型。查看此宣告轉換的即時示範。

元素	TransformationClaimType	資料類型	注意
InputClaim	phoneNumber	phoneNumber	要轉換成字串的宣告。
OutputClaim	phoneNumberString	字串	已叫用此宣告轉換之後，所產生的宣告。

ConvertPhoneNumberClaimToString 的範例

在此範例中，數值類型為 phoneNumber 的 cellPhoneNumber 宣告會轉換成數值類型為 string 的行動電話宣告。

<ClaimsTransformation Id="PhoneNumberToString" TransformationMethod="ConvertPhoneNumberClaimToString">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="cellPhoneNumber" TransformationClaimType="phoneNumber" />
  </InputClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="cellPhone" TransformationClaimType="phoneNumberString" />
  </OutputClaims>
</ClaimsTransformation>

輸入宣告：
- phoneNumber: +11234567890 (phoneNumber)
輸出宣告：
- phoneNumberString: +11234567890 (string)

ConvertStringToPhoneNumberClaim

驗證電話號碼的格式。若有效，將其變更為 Azure AD B2C 所使用的標準格式。如果所提供的電話號碼格式不正確，則會傳回錯誤訊息。查看此宣告轉換的即時示範。

元素	TransformationClaimType	資料類型	注意
InputClaim	phoneNumberString	字串	電話號碼的字串宣告。電話號碼必須是國際格式，請在前方加上「+」和「國家/地區」代碼來完成。如果提供 `country` 輸入宣告，則電話號碼會是當地格式 (不含國家/地區代碼)。
InputClaim	country	字串	[選擇性] 電話號碼的國家/地區代碼字串宣告採用 ISO3166 格式 (兩個字母的 ISO-3166 國家/地區代碼)。
OutputClaim	outputClaim	phoneNumber	此宣告轉換的結果。

ConvertStringToPhoneNumberClaim 宣告轉換一律會從驗證技術設定檔執行，該設定檔會透過自我判斷技術設定檔或顯示控制項來呼叫。 UserMessageIfClaimsTransformationInvalidPhoneNumber 自我判斷技術設定檔中繼資料會控制要呈現給使用者的錯誤訊息。

錯誤訊息執行路徑的圖表

ConvertStringToPhoneNumberClaim 的範例

下列範例會檢查 phoneString 宣告確實是有效的電話號碼，然後傳回標準 Azure AD B2C 格式的電話號碼。否則會擲回錯誤訊息。

<ClaimsTransformation Id="ConvertStringToPhoneNumber" TransformationMethod="ConvertStringToPhoneNumberClaim">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="phoneString" TransformationClaimType="phoneNumberString" />
    <InputClaim ClaimTypeReferenceId="countryCode" TransformationClaimType="country" />
  </InputClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="phoneNumber" TransformationClaimType="outputClaim" />
  </OutputClaims>
</ClaimsTransformation>

輸入宣告：
- phoneNumberString:033 456-7890
- country:DK
輸出宣告：
- outputClaim: +450334567890

沒有國家/地區代碼宣告的 ConvertStringToPhoneNumberClaim 範例

查看此宣告轉換模式的即時示範。

輸入宣告：
- phoneNumberString: +1 (123) 456-7890
輸出宣告：
- outputClaim: +11234567890

呼叫 ConvertStringToPhoneNumberClaim 宣告轉換

自我判斷技術設定檔呼叫的驗證技術設定檔若包含此宣告轉換，則自我判斷技術設定檔可以定義錯誤訊息。

<TechnicalProfile Id="SelfAsserted-LocalAccountSignUp-Phone">
  <Metadata>
    <Item Key="UserMessageIfClaimsTransformationInvalidPhoneNumber">Custom error message if the phone number is not valid.</Item>
  </Metadata>
  ...
</TechnicalProfile>

GetNationalNumberAndCountryCodeFromPhoneNumberString

從輸入宣告中擷取國家/地區代碼及國際電話，並在提供的電話號碼無效時，選擇性地擲回例外狀況。查看此宣告轉換的即時示範。

元素	TransformationClaimType	資料類型	注意
InputClaim	phoneNumber	字串	電話號碼的字串宣告。電話號碼必須是國際格式，請在前方加上「+」和「國家/地區」代碼來完成。
InputParameter	throwExceptionOnFailure	boolean	[選擇性] 指出當電話號碼無效時，是否擲回例外狀況的參數。預設值為 false。
InputParameter	countryCodeType	字串	[選擇性] 此參數會指出輸出宣告中的國家/地區代碼類型。可用的值為 CallingCode (國家/地區的國際電話代碼，例如 + 1)，或 ISO3166 (兩個字母的 ISO-3166 國家/地區代碼)。
OutputClaim	nationalNumber	字串	電話號碼中國家/地區號碼的字串宣告。
OutputClaim	countryCode	字串	電話號碼中國家/地區代碼的字串宣告。

如果 GetNationalNumberAndCountryCodeFromPhoneNumberString 宣告轉換是從自我判斷技術設定檔或顯示控制項動作所呼叫的驗證技術設定檔中執行，則 UserMessageIfPhoneNumberParseFailure 自我判斷技術設定檔中繼資料會控制呈現給使用者的錯誤訊息。

錯誤訊息執行路徑的圖表

您可以使用此宣告轉換，將完整的電話號碼分割成國家/地區代碼和國家/地區號碼。如果提供的電話號碼無效，您可以選擇擲回錯誤訊息。

GetNationalNumberAndCountryCodeFromPhoneNumberString 的範例

下列範例會嘗試將電話號碼分割成國家/地區號碼和國家/地區代碼。如果電話號碼有效，該電話號碼將會由國家/地區號碼覆寫。如果電話號碼無效，將不會擲回例外狀況，而且電話號碼仍會有其原始值。

<ClaimsTransformation Id="GetNationalNumberAndCountryCodeFromPhoneNumberString" TransformationMethod="GetNationalNumberAndCountryCodeFromPhoneNumberString">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="phoneNumber" TransformationClaimType="phoneNumber" />
  </InputClaims>
  <InputParameters>
    <InputParameter Id="throwExceptionOnFailure" DataType="boolean" Value="false" />
    <InputParameter Id="countryCodeType" DataType="string" Value="ISO3166" />
  </InputParameters>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="nationalNumber" TransformationClaimType="nationalNumber" />
    <OutputClaim ClaimTypeReferenceId="countryCode" TransformationClaimType="countryCode" />
  </OutputClaims>
</ClaimsTransformation>

輸入宣告：
- phoneNumber: +49 (123) 456-7890
輸入參數：
- throwExceptionOnFailure: false
- countryCodeType:ISO3166
輸出宣告：
- nationalNumber:1234567890
- countryCode:DE

具有 CallingCode 參數的 GetNationalNumberAndCountryCodeFromPhoneNumberString 範例

下列範例會嘗試將電話號碼分割成國際號碼及國家/地區撥號代碼。

<ClaimsTransformation Id="GetNationalNumberAndCountryCodeFromPhoneNumberString" TransformationMethod="GetNationalNumberAndCountryCodeFromPhoneNumberString">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="phoneNumber" TransformationClaimType="phoneNumber" />
  </InputClaims>
  <InputParameters>
    <InputParameter Id="throwExceptionOnFailure" DataType="boolean" Value="false" />
    <InputParameter Id="countryCodeType" DataType="string" Value="CallingCode" />
  </InputParameters>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="nationalNumber" TransformationClaimType="nationalNumber" />
    <OutputClaim ClaimTypeReferenceId="countryCode" TransformationClaimType="countryCode" />
  </OutputClaims>
</ClaimsTransformation>

輸入宣告：
- phoneNumber: +49 (123) 456-7890
輸入參數
- throwExceptionOnFailure: false
- countryCodeType:CallingCode
輸出宣告：
- nationalNumber:1234567890
- countryCode: +49

呼叫 GetNationalNumberAndCountryCodeFromPhoneNumberString 宣告轉換