日期宣告轉換
此文章提供在 Azure Active Directory B2C (Azure AD B2C) 中，使用識別體驗架構結構描述日期宣告轉換的範例。 如需詳細資訊，請參閱宣告轉換。
AssertDateTimeIsGreaterThan
判斷提示某個日期晚於第二個日期。 判斷 rightOperand 是否大於 leftOperand。 若是，擲回例外狀況。 查看此宣告轉換的即時示範。
| 元素 | TransformationClaimType | 資料類型 | 注意 |
|---|---|---|---|
| InputClaim | leftOperand | 字串 | 第一個宣告的類型，應該晚於第二個宣告。 |
| InputClaim | rightOperand | 字串 | 第二個宣告的類型，應該早於第一個宣告。 |
| InputParameter | AssertIfEqualTo | boolean | 指定當左運算元等於右運算元時，這個判斷提示是否應該擲回錯誤。 可能的值：true (預設) 或 false。 |
| InputParameter | AssertIfRightOperandIsNotPresent | boolean | 指定當右運算元遺失時，是否應該傳遞這個判斷提示。 |
| InputParameter | TreatAsEqualIfWithinMillseconds | int | 指定若要將兩個日期時間視為相等，彼此之間所允許相隔的毫秒數 (例如，為了考慮時鐘誤差因素)。 |
AssertDateTimeIsGreaterThan 宣告轉換一律會從驗證技術設定檔執行，其會透過自我判斷技術設定檔來呼叫。 DateTimeGreaterThan 自我判斷技術設定檔中繼資料會控制技術設定檔要呈現給使用者的錯誤訊息。 錯誤訊息可以當地語系化。
AssertDateTimeIsGreaterThan 的範例
下列範例會比較 currentDateTime 宣告與 approvedDateTime 宣告。 如果 currentDateTime 晚於 approvedDateTime，則會擲回錯誤。 兩個值若相差不到 5 分鐘 (30000 毫秒)，轉換會將兩者視為相等。 如果這些值相等，則不會擲回錯誤，因為 AssertIfEqualTo 設定為 false。
<ClaimsTransformation Id="AssertApprovedDateTimeLaterThanCurrentDateTime" TransformationMethod="AssertDateTimeIsGreaterThan">
<InputClaims>
<InputClaim ClaimTypeReferenceId="approvedDateTime" TransformationClaimType="leftOperand" />
<InputClaim ClaimTypeReferenceId="currentDateTime" TransformationClaimType="rightOperand" />
</InputClaims>
<InputParameters>
<InputParameter Id="AssertIfEqualTo" DataType="boolean" Value="false" />
<InputParameter Id="AssertIfRightOperandIsNotPresent" DataType="boolean" Value="true" />
<InputParameter Id="TreatAsEqualIfWithinMillseconds" DataType="int" Value="300000" />
</InputParameters>
</ClaimsTransformation>
注意
在上述範例中，如果您移除 AssertIfEqualTo 輸入參數，且 currentDateTime 等於 approvedDateTime，則會擲回錯誤。
AssertIfEqualTo 預設值為 true。
- 輸入宣告：
- leftOperand：2022-01-01T15:00:00
- rightOperand：2022-01-22T15:00:00
- 輸入參數：
- AssertIfEqualTo：false
- AssertIfRightOperandIsNotPresent：true
- TreatAsEqualIfWithinMillseconds：300000 (30 秒)
- 結果：擲回錯誤
呼叫宣告轉換
下列 Example-AssertDates 驗證技術設定檔會呼叫 AssertApprovedDateTimeLaterThanCurrentDateTime 宣告轉換。
<TechnicalProfile Id="Example-AssertDates">
<DisplayName>Unit test</DisplayName>
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.ClaimsTransformationProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="ComparisonResult" DefaultValue="false" />
</OutputClaims>
<OutputClaimsTransformations>
<OutputClaimsTransformation ReferenceId="AssertDates" />
</OutputClaimsTransformations>
<UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>
自我判斷技術設定檔會呼叫驗證 Example-AssertDates 技術設定檔。
<TechnicalProfile Id="SelfAsserted-AssertDateTimeIsGreaterThan">
<DisplayName>User ID signup</DisplayName>
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
<Metadata>
<Item Key="ContentDefinitionReferenceId">api.selfasserted</Item>
<Item Key="DateTimeGreaterThan">Custom error message if the provided right operand is greater than the right operand.</Item>
</Metadata>
...
<ValidationTechnicalProfiles>
<ValidationTechnicalProfile ReferenceId="ClaimsTransformation-AssertDateTimeIsGreaterThan" />
</ValidationTechnicalProfiles>
</TechnicalProfile>
ConvertDateTimeToDateClaim
將 DateTime 宣告類型轉換為 Date 宣告類型。 宣告轉換會移除日期中的時間格式。 查看此宣告轉換的即時示範。
| 元素 | TransformationClaimType | 資料類型 | 注意 |
|---|---|---|---|
| InputClaim | inputClaim | dateTime | 要轉換的宣告類型。 |
| OutputClaim | outputClaim | date | 叫用此宣告轉換之後所產生的宣告類型。 |
ConvertDateTimeToDateClaim 的範例
下列範例會示範如何將宣告 systemDateTime (日期時間資料類型) 轉換為另一個宣告 systemDate (日期資料類型)。
<ClaimsTransformation Id="ConvertToDate" TransformationMethod="ConvertDateTimeToDateClaim">
<InputClaims>
<InputClaim ClaimTypeReferenceId="systemDateTime" TransformationClaimType="inputClaim" />
</InputClaims>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="systemDate" TransformationClaimType="outputClaim" />
</OutputClaims>
</ClaimsTransformation>
- 輸入宣告：
- inputClaim：2022-01-03T11:34:22.0000000Z
- 輸出宣告：
- outputClaim：2022-01-03
ConvertDateToDateTimeClaim
將 Date 宣告類型轉換為 DateTime 宣告類型。 宣告轉換會轉換時間格式，並對日期新增 12:00:00 AM。 查看此宣告轉換的即時示範。
| 元素 | TransformationClaimType | 資料類型 | 注意 |
|---|---|---|---|
| InputClaim | inputClaim | date | 要轉換的宣告類型。 |
| OutputClaim | outputClaim | dateTime | 叫用此宣告轉換之後所產生的宣告類型。 |
ConvertDateToDateTimeClaim 的範例
下列範例會示範如何將宣告 dateOfBirth (日期資料類型) 轉換為另一個宣告 dateOfBirthWithTime (日期時間資料類型)。
<ClaimsTransformation Id="ConvertToDateTime" TransformationMethod="ConvertDateToDateTimeClaim">
<InputClaims>
<InputClaim ClaimTypeReferenceId="dateOfBirth" TransformationClaimType="inputClaim" />
</InputClaims>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="dateOfBirthWithTime" TransformationClaimType="outputClaim" />
</OutputClaims>
</ClaimsTransformation>
- 輸入宣告：
- inputClaim：2022-01-03
- 輸出宣告：
- outputClaim：2022-01-03T00:00:00.0000000Z
DateTimeComparison
比較兩個日期，並判斷第一個日期是晚於、早於還是等於另一個日期。 結果是值為 true 或 false 的新布林值宣告。 查看此宣告轉換的即時示範。
| 元素 | TransformationClaimType | 資料類型 | 注意 |
|---|---|---|---|
| InputClaim | firstDateTime | dateTime | 要比較其是晚於、早於還是等於第二個日期的第一個日期。 Null 值會擲回例外狀況。 |
| InputClaim | secondDateTime | dateTime | 要比較的第二個日期。 Null 值會被視為目前日期和時間。 |
| InputParameter | timeSpanInSeconds | int | 要新增至第一個日期的時間範圍。 可能的值：範圍從負 -2,147,483,648 到正 2,147,483,647。 |
| InputParameter | ! 運算子之後 | 字串 | 下列其中一個值：same、later than 或 earlier than。 |
| OutputClaim | result | boolean | 叫用此宣告轉換之後所產生的宣告。 |
DateTimeComparison 的範例
使用此宣告轉換來判斷第一個日期加上 timeSpanInSeconds 參數是晚於、早於還是等於另一個日期。 下列範例顯示第一個日期 (2022-01-01T00:00:00) 加上 90 天晚於第二個日期 (2022-03-16T00:00:00)。
<ClaimsTransformation Id="CompareLastTOSAcceptedWithCurrentDateTime" TransformationMethod="DateTimeComparison">
<InputClaims>
<InputClaim ClaimTypeReferenceId="extension_LastTOSAccepted" TransformationClaimType="secondDateTime" />
<InputClaim ClaimTypeReferenceId="currentDateTime" TransformationClaimType="firstDateTime" />
</InputClaims>
<InputParameters>
<InputParameter Id="operator" DataType="string" Value="later than" />
<InputParameter Id="timeSpanInSeconds" DataType="int" Value="7776000" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="isLastTOSAcceptedGreaterThanNow" TransformationClaimType="result" />
</OutputClaims>
</ClaimsTransformation>
- 輸入宣告：
- firstDateTime：2022-01-01T00:00:00.100000Z
- secondDateTime：2022-03-16T00:00:00.100000Z
- 輸入參數：
- 運算子：晚於
- timeSpanInSeconds：7776000 (90 天)
- 輸出宣告：
- 結果：true
IsTermsOfUseConsentRequired
判斷 dateTime 宣告類型是否早於或大於特定日期。 結果是值為 true 或 false 的新布林值宣告。 查看此宣告轉換的即時示範。
| Item | TransformationClaimType | 資料類型 | 注意 |
|---|---|---|---|
| InputClaim | termsOfUseConsentDateTime | dateTime | 要檢查其是否早於或晚於 termsOfUseTextUpdateDateTime 輸入參數的 dateTime 宣告類型。 未定義的值會傳回 true 結果。 |
| InputParameter | termsOfUseTextUpdateDateTime | dateTime | 要檢查其是否早於或晚於 termsOfUseConsentDateTime 輸入宣告的 dateTime 宣告類型。 日期的時間部分是選擇性的。 |
| OutputClaim | result | boolean | 叫用此宣告轉換之後所產生的宣告類型。 |
使用此宣告轉換來判斷 dateTime 宣告類型是否早於或大於特定日期。 例如，檢查使用者是否已同意最新版本的使用規定 (TOU) 或服務條款。 若要檢查使用者上次同意的時間，請將使用者上次接受 TOU 的時間儲存在擴充屬性中。 當您的 TOU 措辭變更時，請在變更時更新 termsOfUseTextUpdateDateTime 輸入參數。 然後，呼叫此宣告轉換來比較日期。 如果宣告轉換傳回 true，termsOfUseConsentDateTime 值會早於 termsOfUseTextUpdateDateTime 值，而且您可以要求使用者接受更新的 TOU。
<ClaimsTransformation Id="IsTermsOfUseConsentRequired" TransformationMethod="IsTermsOfUseConsentRequired">
<InputClaims>
<InputClaim ClaimTypeReferenceId="extension_termsOfUseConsentDateTime" TransformationClaimType="termsOfUseConsentDateTime" />
</InputClaims>
<InputParameters>
<InputParameter Id="termsOfUseTextUpdateDateTime" DataType="dateTime" Value="2021-11-15T00:00:00" />
</InputParameters>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="termsOfUseConsentRequired" TransformationClaimType="result" />
</OutputClaims>
</ClaimsTransformation>
IsTermsOfUseConsentRequired 範例
- 輸入宣告：
- termsOfUseConsentDateTime：2020-03-09T09:15:00
- 輸入參數：
- termsOfUseTextUpdateDateTime：2021-11-15
- 輸出宣告：
- 結果：true
GetCurrentDateTime
取得目前的 UTC 日期和時間，並將值新增至宣告類型。 查看此宣告轉換的即時示範。
| 元素 | TransformationClaimType | 資料類型 | 注意 |
|---|---|---|---|
| OutputClaim | currentDateTime | dateTime | 叫用此宣告轉換之後所產生的宣告類型。 |
GetCurrentDateTime 的範例
下列範例說明如何取得目前的日期和時間：
<ClaimsTransformation Id="GetSystemDateTime" TransformationMethod="GetCurrentDateTime">
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="systemDateTime" TransformationClaimType="currentDateTime" />
</OutputClaims>
</ClaimsTransformation>
- 輸出宣告：
- currentDateTime：2022-01-14T11:40:35.0000000Z
後續步驟
- 在 Azure AD B2C 社群 GitHub 存放庫中，尋找更多宣告轉換範例