",
transformationContext="datasource"
).getDynamicFrame()
val ruleset = """
Rules = [
(ColumnValues "age" >= 26) OR (ColumnLength "name" >= 4)
]
"""
val dq_results = EvaluateDataQuality.processRows(
frame=datasource,
ruleset=ruleset,
additionalOptions=JsonOptions("""
{
"compositeRuleEvaluation.method":"ROW"
}
"""
)
)
}
```
在 AWS Glue Data Catalog 中，您可以在使用者介面中輕鬆設定此選項，如下所示。
![\[螢幕擷取畫面顯示複合規則設定視窗，您可以在其中選擇資料列和資料欄之間的規則評估組態。如果您選擇資料列，則複合規則將作為評估整個資料列的單一規則。如果您選擇資料欄，複合規則會評估整個資料集的個別規則，並合併結果。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/composite-rule-settings.png)
設定後，複合規則將作為評估整個資料列的單一規則。下列範例示範了此行為。
```
# Row Level outcome
+------+------+------------------------------------------------------------+---------------------------+
|myCol1|myCol2|DataQualityRulesPass |DataQualityEvaluationResult|
+------+------+------------------------------------------------------------+---------------------------+
|2 |1 |[(ColumnValues "myCol1" > 1) OR (ColumnValues "myCol2" > 2)]|Passed |
|0 |3 |[(ColumnValues "myCol1" > 1) OR (ColumnValues "myCol2" > 2)]|Passed |
+------+------+------------------------------------------------------------+---------------------------+
```
此功能不支援某些規則，因為整體結果取決於閾值或比率。將其列示如下。
依賴比率的規則：
+ 完整度
+ DatasetMatch
+ ReferentialIntegrity
+ Uniqueness
相依於閾值的規則：
當下列規則包含閾值時，其不受支援。但是，不涉及 `with threshold` 的規則仍受支援。
+ ColumnDataType
+ ColumnValues
+ CustomSQL
### 表達式
如果規則類型不會產生布林值回應，您必須提供運算式作為參數，才能建立布林值回應。例如，下列規則會根據表達式檢查欄中所有值的平均值，以傳回 true 或 false 結果。
```
Mean "colA" between 80 and 100
```
某些規則類型 (例如 `IsUnique` 和 `IsComplete`) 已傳回布林值回應。
下表列出您可以在 DQDL 規則中使用的運算式。
**支援的 DQDL 運算式**
| 表達式 | Description | 範例 |
| --- | --- | --- |
| =x | 如果規則類型回應等於 x，則解析為 true。 | Completeness "colA" = "1.0",
ColumnValues "colA" = "2022-06-30"
|
| \$1=x | 如果規則類型回應不等於 x，則解析為 true。 | ColumnValues "colA" != "a",
ColumnValues "colA" != "2022-06-30"
|
| > x | 如果規則類型回應大於 x，則解析為 true。 | ColumnValues "colA" > 10
|
| < x | 如果規則類型回應小於 x，則解析為 true。 | ColumnValues "colA" < 1000,
ColumnValues "colA" < "2022-06-30"
|
| >= x | 如果規則類型回應大於或等於 x，則解析為 true。 | ColumnValues "colA" >= 10
|
| <= x | 如果規則類型回應小於或等於 x，則解析為 true。 | ColumnValues "colA" <= 1000
|
| between x and y | 如果規則類型回應落在指定範圍內 (不含) 時，則解析為 true。只針對數字和日期類型使用此表達式類型。 | Mean "colA" between 8 and 100,
ColumnValues "colA" between "2022-05-31" and "2022-06-30"
|
| not between x and y | 如果規則類型回應不屬於指定範圍 (含)，則解析為 true。您應該只針對數字和日期類型使用此運算式類型。 | ColumnValues "colA" not between "2022-05-31" and "2022-06-30"
|
| in [a, b, c, ...] | 如果規則類型回應在指定集中，則解析為 true。 | ColumnValues "colA" in [ 1, 2, 3 ],
ColumnValues "colA" in [ "a", "b", "c" ]
|
| not in [a, b, c, ...] | 如果規則類型回應不在指定集中，則解析為 true。 | ColumnValues "colA" not in [ 1, 2, 3 ],
ColumnValues "colA" not in [ "a", "b", "c" ]
|
| matches /ab\$1c/i | 如果規則類型回應符合規則運算式，則解析為 true。 | ColumnValues "colA" matches "[a-zA-Z]*"
|
| not matches /ab\$1c/i | 如果規則類型回應不符合規則運算式，則解析為 true。 | ColumnValues "colA" not matches "[a-zA-Z]*"
|
| now() | 僅適用於 ColumnValues 規則類型以建立日期運算式。 | ColumnValues "load_date" > (now() - 3 days)
|
| matches/in […]/not matches/not in [...] with threshold | 指定符合規則條件的值的百分比。僅適用於 ColumnValues、ColumnDataType 和 CustomSQL 規則類型。 | ColumnValues "colA" in ["A", "B"] with threshold > 0.8,
ColumnValues "colA" matches "[a-zA-Z]*" with threshold between 0.2 and 0.9
ColumnDataType "colA" = "Timestamp" with threshold > 0.9
|
#### NULL、EMPTY 和 WHITESPACES\$1ONLY 的關鍵字
如果您想要驗證字串資料欄是否具有 null、空白或僅包含空格的字串，您可以使用下列關鍵字：
+ NULL/null – 此關鍵字會針對字串資料欄中的 `null` 值解析為 true。
如果超過 50% 的資料沒有 null 值，`ColumnValues "colA" != NULL with threshold > 0.5` 會傳回 true。
對於具有 null 值或長度 >5 的所有資料列，`(ColumnValues "colA" = NULL) or (ColumnLength "colA" > 5)` 會傳回 true。*請注意，這將需要使用 “compositeRuleEvaluation.method” = “ROW” 選項。*
+ EMPTY / empty – 對於字串資料欄中的空白字串 (" ") 值，此關鍵字解析為 true。有些資料格式會將字串資料欄中的 null 轉換為空白字串。此關鍵字有助於篩選掉資料中的空白字串。
如果資料列為空白、"a" 或 "b"，`(ColumnValues "colA" = EMPTY) or (ColumnValues "colA" in ["a", "b"])` 會傳回 true。*請注意，這需要使用 "compositeRuleEvaluation.method" = "ROW" 選項。*
+ WHITESPACES\$1ONLY / whitespaces\$1only – 對於字串資料欄中僅包含空格 (" ") 值的字串，此關鍵字會解析為 true。
如果資料列不是 "a" 或 "b"，也不只是空格，`ColumnValues "colA" not in ["a", "b", WHITESPACES_ONLY]` 會傳回 true。
支援的規則：
+ [ColumnValues](https://docs.aws.amazon.com/glue/latest/dg/dqdl.html#dqdl-rule-types-ColumnValues)
對於以數字或日期為基礎的表達式，如果您要驗證資料欄是否具有 null，您可以使用下列關鍵字。
+ NULL/null – 此關鍵字會針對字串資料欄中的 null 值解析為 true。
如果資料欄中的日期為 `2023-01-01` 或 null，`ColumnValues "colA" in [NULL, "2023-01-01"]` 會傳回 true。
對於具有 null 值或具有介於 1 至 9 之間的值的所有資料列，`(ColumnValues "colA" = NULL) or (ColumnValues "colA" between 1 and 9)` 會傳回 true。*請注意，這將需要使用 “compositeRuleEvaluation.method” = “ROW” 選項。*
支援的規則：
+ [ColumnValues](https://docs.aws.amazon.com/glue/latest/dg/dqdl.html#dqdl-rule-types-ColumnValues)
#### 使用 Where 子句進行篩選
**注意**
其中 Glue 4.0 AWS 僅支援 子句。
您可以在撰寫規則時篩選資料。在您要套用條件式規則時，這會很有幫助。
```
where " "
```
必須使用 `where` 關鍵字指定篩選條件，後接以引號 `("")` 括住的有效 SparkSQL 陳述式。
如果您想要將 where 子句新增至具有閾值的規則，則應在閾值條件之前指定 where 子句。
```
where "valid SparkSQL statement>" with threshold
```
使用此語法，您可以撰寫如下所示的規則。
```
Completeness "colA" > 0.5 where "colB = 10"
ColumnValues "colB" in ["A", "B"] where "colC is not null" with threshold > 0.9
ColumnLength "colC" > 10 where "colD != Concat(colE, colF)"
```
我們將驗證提供的 SparkSQL 陳述式是否有效。如果無效，規則評估將會失敗，我們將擲回格式如下的 `IllegalArgumentException`：
```
Rule where "" has provided an invalid where clause :
```
**開啟資料列層級錯誤記錄識別時的 Where 子句行為**
透過 AWS Glue Data Quality，您可以識別失敗的特定記錄。將 where 子句套用至支援資料列層級結果的規則時，我們會將由 where 子句篩選的資料列標記為 `Passed`。
如果您偏好將篩選出的資料列單獨標記為 `SKIPPED`，可以為 ETL 任務設定下列 `additionalOptions`。
```
object GlueApp {
val datasource = glueContext.getCatalogSource(
database="",
tableName="",
transformationContext="datasource"
).getDynamicFrame()
val ruleset = """
Rules = [
IsComplete "att2" where "att1 = 'a'"
]
"""
val dq_results = EvaluateDataQuality.processRows(
frame=datasource,
ruleset=ruleset,
additionalOptions=JsonOptions("""
{
"rowLevelConfiguration.filteredRowLabel":"SKIPPED"
}
"""
)
)
}
```
例如，請參閱下列規則和資料框：
```
IsComplete att2 where "att1 = 'a'"
```
| id | att1 | att2 | 資料列層級結果 (預設值) | 資料列層級結果 (已略過選項) | 說明 |
| --- | --- | --- | --- | --- | --- |
| 1 | a | f | PASSED | PASSED | |
| 2 | b | d | PASSED | 略過 | 資料列會篩選掉，因為 att1 不是 "a" |
| 3 | a | null | 失敗 | 失敗 | |
| 4 | a | f | PASSED | PASSED | |
| 5 | b | null | PASSED | 略過 | 資料列會篩選掉，因為 att1 不是 "a" |
| 6 | a | f | PASSED | PASSED | |
### 常數
在 DQDL 中，您可以定義常數值，並在指令碼中參考它們。這有助於防止與查詢大小限制相關的問題，例如，使用可能超過允許界限的大型 SQL 陳述式時。透過將這些值指派給常數，您可以簡化 DQDL 並避免達到這些限制。
下列範例示範如何定義和使用常數：
```
mySql = "select count(*) from primary"
Rules = [
CustomSql $mySql between 0 and 100
]
```
在此範例中，SQL 查詢會指派給常數 `mySql`，然後使用 `$`字首在規則中參考。
### 標籤
標籤提供有效的方法來組織和分析資料品質結果。您可以依特定標籤查詢結果，以識別特定類別內失敗的規則、依團隊或網域計算規則結果，並為不同的利益相關者建立重點報告。
例如，您可以使用標籤套用與財務團隊相關的所有規則，`"team=finance"`並產生自訂報告來展示財務團隊特有的品質指標。您可以使用 標記高優先順序規則`"criticality=high"`，以排定修復工作的優先順序。標籤可以撰寫為 DQDL 的一部分。您可以在規則結果、資料列層級結果和 API 回應中查詢標籤，以便輕鬆與現有的監控和報告工作流程整合。
**注意**
標籤僅適用於 AWS Glue ETL，不適用於以 Glue Data Catalog AWS 為基礎的資料品質。
#### DQDL 標籤的語法
DQDL 同時支援預設和規則特定的標籤。預設標籤是在規則集層級定義，並自動套用到該規則集內的所有規則。個別規則也可以有自己的標籤，而且由於標籤會實作為索引鍵/值對，因此使用相同索引鍵時，規則特定的標籤可以覆寫預設標籤。
下列範例示範如何使用預設和規則特定的標籤：
```
DefaultLabels=["frequency"="monthly"]
Rules = [
// Auto includes the default label ["frequency"="monthly"]
ColumnValues "col" > 21,
// Add ["foo"="bar"] to default label. Labels for this rule would be ["frequency"="monthly", "foo"="bar"]
Rule 1 with threshold > 0.8 labels=["foo"="bar"],
// Override default label. Labels for this rule would be ["frequency"="daily", "foo"="bar"]
Rule 2 with threshold > 0.8 labels=["foo"="bar", "frequency"="daily"]
// Labels must be applied to the entire composite rule (parentheses required)
(Rule 1 AND Rule 2) labels=["foo"="bar]
]
```
##### 標籤限制條件
標籤有下列限制：
+ 每個 DQDL 規則最多 10 個標籤。
+ 標籤會指定為索引鍵/值對的清單。
+ 標籤索引鍵和標籤值區分大小寫。
+ 標籤索引鍵的長度上限為 128 個字元。標籤索引鍵不得為空白或 null。
+ 標籤值長度上限為 256 個字元。標籤值可以是空白或 null。
#### 擷取 DQDL 標籤
您可以從規則結果、資料列層級結果和 API 回應擷取 DQDL 標籤。
##### 規則結果
DQDL 標籤一律會顯示在規則結果中。不需要額外的組態即可啟用。
##### 資料列層級結果
DQDL 標籤預設會在資料列層級結果中停用，但可以在 `AdditionalOptions`中使用 啟用`EvaluateDataQuality`。
下列範例顯示如何在資料列層級結果中啟用標籤：
```
val evaluateResult = EvaluateDataQuality.processRows(
frame=AmazonS3_node1754591511068,
ruleset=example_ruleset,
publishingOptions=JsonOptions("""{
"dataQualityEvaluationContext": "evaluateResult",
"enableDataQualityCloudWatchMetrics": "true",
"enableDataQualityResultsPublishing": "true"
}"""),
additionalOptions=JsonOptions("""{
"performanceTuning.caching":"CACHE_NOTHING",
"observations.scope":"ALL",
"rowLevelConfiguration.ruleWithLabels":"ENABLED"
}""")
)
```
啟用時，資料列層級結果資料框架會包含 `DataQualityRulesPass`、 `DataQualityRulesFail`和 `DataQualityRulesSkip`欄中每個規則的標籤。
##### API 回應
DQDL 標籤一律會顯示在`RuleResults`物件中新欄位下的 API 回應`Labels`中。
下列範例顯示 API 回應中的標籤：
```
{
"ResultId": "dqresult-example",
"ProfileId": "dqprofile-example",
"Score": 0.6666666666666666,
"RulesetName": "EvaluateDataQuality_node1754591514205",
"EvaluationContext": "EvaluateDataQuality_node1754591514205",
"StartedOn": "2025-08-22T19:36:10.448000+00:00",
"CompletedOn": "2025-08-22T19:36:16.368000+00:00",
"JobName": "anniezc-test-labels",
"JobRunId": "jr_068f6d7a45074d9105d14e4dee09db12c3b95664b45f6ee44fa29ed7e5619ba8",
"RuleResults": [
{
"Name": "Rule_0",
"Description": "IsComplete colA",
"EvaluationMessage": "Input data does not include column colA!",
"Result": "FAIL",
"EvaluatedMetrics": {},
"EvaluatedRule": "IsComplete colA",
"Labels": {
"frequency": "monthly"
}
},
{
"Name": "Rule_1",
"Description": "Rule 1 with threshold > 0.8",
"Result": "PASS",
"EvaluatedMetrics": {},
"EvaluatedRule": "Rule 1 with threshold > 0.8",
"Labels": {
"frequency": "monthly",
"foo": "bar"
}
},
{
"Name": "Rule_3",
"Description": "Rule 2 with threshold > 0.8",
"Result": "PASS",
"EvaluatedMetrics": {},
"EvaluatedRule": "Rule 2 with threshold > 0.8",
"Labels": {
"frequency": "daily",
"foo": "bar"
}
}
]
}
```
### 動態規則
**注意**
動態規則僅在 AWS Glue ETL 中受支援，且在 Glue Data Catalog AWS 中不受支援。
您現在可以編寫動態規則，將規則產生的目前指標與其歷史值進行比較。這些歷史比較是透過在表達式中使用 `last()` 運算子來啟用。例如，當目前執行中的資料列數目大於相同資料集的最近先前一個資料列計數時，規則 `RowCount > last()` 便會成功。`last()` 採用可選的自然數引數，描述要考慮的先前指標；`last(k)` 中 `k >= 1` 將參考最後 `k` 個指標。
+ 如果沒有可用的資料點，`last(k)` 將傳回預設值 0.0。
+ 如果可用的指標少於 `k`，`last(k)` 將傳回所有先前的指標。
為了形成使用 `last(k)` 的有效表達式，`k > 1` 需要彙總函數將多個歷史結果簡化為一個數字。例如，`RowCount > avg(last(5))` 將檢查目前資料集的資料列計數是否嚴格大於相同資料集最後五個資料列計數的平均值。`RowCount > last(5)` 將產生錯誤，因為當前資料集的資料列計數不能與清單進行有意義的比較。
支援的彙總函數：
+ `avg`
+ `median`
+ `max`
+ `min`
+ `sum`
+ `std` (標準偏差)
+ `abs` (絕對值)
+ `index(last(k), i)` 將允許從最後 `k` 個值中選取第 `i` 個最近的值。`i` 從零開始索引，所以 `index(last(3), 0)` 將傳回最新的資料點；而 `index(last(3), 3)` 會導致錯誤，因為只有三個資料點，但我們嘗試對第 4 個最新的資料點編製索引。
**範例表達式**
**ColumnCorrelation**
+ `ColumnCorrelation "colA" "colB" < avg(last(10))`
**DistinctValuesCount**
+ `DistinctValuesCount "colA" between min(last(10))-1 and max(last(10))+1`
大多數具有數值條件或閾值的規則類型都支援動態規則；請參閱提供的資料表[分析器和規則](#dqdl-analyzers-table)，判斷規則類型是否支援動態規則。
**從動態規則排除統計資料**
有時，您將需要從動態規則計算中排除資料統計資料。假設您執行了歷史資料載入，而且不想影響您的平均值。若要這樣做，請在 Glue ETL AWS 中開啟任務，然後選擇**資料品質**索引標籤，然後選擇**統計資料**，然後選取您要排除的統計資料。您將可以看到趨勢圖表以及統計資料表。選取您要排除的值，然後選擇**排除統計資料**。現在，排除的統計資料不會包含在動態規則計算中。
![\[螢幕擷取畫面顯示在選取統計資料之後，從下拉式功能表中排除或包含統計資料的選項。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/data-quality-excluding-statistics-from-dynamic-rules.png)
### 分析器
**注意**
Glue Data Catalog AWS 不支援分析器。
DQDL 規則使用名為 *Analyzers* 的函數來收集與資料有關的資訊。規則的布林表達式會使用此資訊來判斷規則是成功或是失敗。例如，RowCount 規則 `RowCount > 5 ` 會使用資料列計數分析器來探索資料集中的資料列數目，並將該計數與表達式 `> 5` 進行比較，從而檢查目前資料集中是否存在五個以上的資料列。
有時候，我們建議您建立分析器而不是撰寫規則，然後讓這些分析器產生可用來偵測異常的統計資料。對於這種情況，您可以建立分析器。分析器與規則有下列不同之處。
| 特性 | 分析器 | Rules |
| --- | --- | --- |
| 規則集的一部分 | 是 | 是 |
| 產生統計資料 | 是 | 是 |
| 產生觀察 | 是 | 是 |
| 可以評估和斷言條件 | 否 | 是 |
| 您可以設定動作，例如在失敗時停止作業、繼續處理作業 | 否 | 是 |
分析器可以在沒有規則的情況下獨立存在，因此您可以快速設定這些分析器並逐步建置資料品質規則。
您可以在規則集的 `Analyzers` 區塊中輸入某些規則類型，以執行分析器所需的規則並收集資訊，而無需對任何條件套用檢查。某些分析器不會與規則相關聯，在 `Analyzers` 區塊中只能作為輸入。下表指出每個項目是否受到規則或獨立分析器的支援，以及每個規則類型的其他詳細資訊。
**使用 Analyzer 的範例 Ruleset**
以下規則集使用：
+ 動態規則，檢查資料集的成長速度是否超過在過去三次作業執行的結尾平均值
+ `DistinctValuesCount` 分析器，記錄資料集 `Name` 資料欄中相異值的數目
+ `ColumnLength` 分析器，追蹤隨時間變化的最小和最大 `Name` 尺寸
您可以在作業執行的「資料品質」索引標籤中檢視分析器指標結果。
```
Rules = [
RowCount > avg(last(3))
]
Analyzers = [
DistinctValuesCount "Name",
ColumnLength "Name"
]
```
AWS Glue Data Quality 支援下列分析器。
| 分析器名稱 | 功能 |
| --- | --- |
| RowCount | 計算資料集的資料列計數 |
| Completeness | 計算資料欄的完整性百分比 |
| Uniqueness | 計算資料欄的唯一性百分比 |
| Mean | 計算數值資料欄的平均值 |
| Sum | 計算數值資料欄的總和 |
| StandardDeviation | 計算數值資料欄的標準差 |
| Entropy | 計算數值資料欄的熵 |
| DistinctValuesCount | 計算資料欄中相異值的數目 |
| UniqueValueRatio | 計算資料欄中的唯一值比率 |
| ColumnCount | 計算資料集中的資料欄數 |
| ColumnLength | 計算資料欄的長度 |
| ColumnValues | 計算數值資料欄數的下限和上限。計算非數值資料欄的 ColumnLength 下限和 ColumnLength 上限 |
| ColumnCorrelation | 計算所指定資料欄的資料欄關聯性 |
| CustomSql | 計算 CustomSQL 傳回的統計資料 |
| AllStatistics | 計算下列統計資料：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/dqdl.html) |
### 說明
您可以使用 '\$1' 字元將註解新增至 DQDL 文件。DQDL 會忽略 '\$1' 字元之後直到行尾的任何內容。
```
Rules = [
# More items should generally mean a higher price, so correlation should be positive
ColumnCorrelation "price" "num_items" > 0
]
```
# DQDL 規則類型參考
本節提供 Glue Data Quality AWS 支援的每個規則類型的參考。
**注意**
DQDL 目前不支援巢狀或清單類型的資料欄資料。
下表中括號內的值將被替換為規則引數中提供的資訊。
規則通常需要表達式的額外引數。
| Ruletype | Description | 引數 | 報告的指標 | 支援作為規則？ | 支援作為分析器？ | 傳回資料列層級結果？ | 動態規則支援？ | 產生觀察 | 支援哪些子句語法？ |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| AggregateMatch | 透過比較諸如總銷售額等摘要指標，檢查兩個資料集是否相符。這可讓金融機構比較是否從來源系統中擷取所有資料，因此非常實用。 | 一或多個彙總 | 當第一個和第二個彙總資料欄名稱相符時： `Column.[Column].AggregateMatch` 當第一個和第二個彙總資料欄名稱不相符時： `Column.[Column1,Column2].AggregateMatch` | 是 | 否 | 否 | 否 | 否 | 否 |
| AllStatistics | 獨立分析器，可為資料集中提供的資料欄收集多個指標。 | 單一資料欄名稱 | 所有類型的資料欄： `Dataset.*.RowCount` `Column.[Column].Completeness` `Column.[Column].Uniqueness` 字串值資料欄的其他指標： `ColumnLength metrics` 數值資料欄的其他指標： `ColumnValues metrics` | 否 | 是 | 否 | 否 | 否 | 否 |
| ColumnCorrelation | 檢查兩個資料欄如何相互關聯。 | 剛好兩個資料欄名稱 | Multicolumn.[Column1,Column2].ColumnCorrelation | 是 | 是 | 否 | 是 | 否 | 是 |
| ColumnCount | 檢查是否有任何資料欄遭到捨棄。 | 無 | Dataset.\$1.ColumnCount | 是 | 是 | 否 | 是 | 是 | 否 |
| ColumnDataType | 檢查資料欄是否與資料類型相容。 | 剛好一個資料欄名稱 | Column.[Column].ColumnDataType.Compliance | 是 | 否 | 否 | 是，在資料列層級閾值表達式中 | 否 | 是 |
| ColumnExists | 檢查資料集中是否存在資料欄。這可讓客戶建立自助式資料平台，確保某些資料欄可供使用。 | 剛好一個資料欄名稱 | N/A | 是 | 否 | 否 | 否 | 否 | 否 |
| ColumnLength | 檢查資料的長度是否一致。 | 剛好一個資料欄名稱 | `Column.[Column].MaximumLength` `Column.[Column].MinimumLength` 提供資料列層級閾值時的其他指標： `Column.[Column].ColumnValues.Compliance` | 是 | 是 | 是，當提供資料列層級臨界值時 | 否 | 是。僅透過分析最小和最大長度來產生觀察 | 是 |
| ColumnNamesMatchPattern | 檢查資料欄名稱是否與定義的模式相符。對於控管團隊強制執行資料欄名稱一致性非常實用。 | 資料欄名稱的 regex | Dataset.\$1.ColumnNamesPatternMatchRatio | 是 | 否 | 否 | 否 | 否 | 否 |
| ColumnValues | 檢查每個定義值的資料是否一致。此規則支援規則運算式。 | 剛好一個資料欄名稱 | `Column.[Column].Maximum` `Column.[Column].Minimum` 提供資料列層級閾值時的其他指標： `Column.[Column].ColumnValues.Compliance` | 是 | 是 | 是，當提供資料列層級臨界值時 | 否 | 是。僅透過分析最小和最大值來產生觀察 | 是 |
| 完整度 | 檢查資料中是否有任何空白或 NULL 值。 | 剛好一個資料欄名稱 | `Column.[Column].Completeness` | 是 | 是 | 是 | 是 | 是 | 是 |
| CustomSql | 客戶可以在 SQL 中實作幾乎所有類型的資料品質檢查。 | SQL 陳述式 (選用) 資料列層級閾值 | `Dataset.*.CustomSQL` 提供資料列層級閾值時的其他指標： `Dataset.*.CustomSQL.Compliance` | 是 | 否 | 是，當提供資料列層級臨界值時 | 是 | 否 | 否 |
| DataFreshness | 檢查資料是否為最新狀態。 | 剛好一個資料欄名稱 | Column.[Column].DataFreshness.Compliance | 是 | 否 | 是 | 否 | 否 | 是 |
| DatasetMatch | 比較兩個資料集並識別其是否同步。 | 參考資料集的名稱 資料欄映射 (選用) 要檢查相符項目的資料欄 | Dataset.[ReferenceDatasetAlias].DatasetMatch | 是 | 否 | 是 | 是 | 否 | 否 |
| DistinctValuesCount | 檢查重複值。 | 剛好一個資料欄名稱 | Column.[Column].DistinctValuesCount | 是 | 是 | 是 | 是 | 是 | 是 |
| DetectAnomalies | 檢查其他規則類型報告指標中的異常。 | 規則類型 | 規則類型引數報告的指標 | 是 | 否 | 否 | 否 | 否 | 否 |
| Entropy | 檢查資料的熵。 | 剛好一個資料欄名稱 | Column.[Column].Entropy | 是 | 是 | 否 | 是 | 否 | 是 |
| IsComplete | 檢查是否 100% 的資料皆為已完成。 | 剛好一個資料欄名稱 | Column.[Column].Completeness | 是 | 否 | 是 | 否 | 否 | 是 |
| IsPrimaryKey | 檢查資料欄是否為主索引鍵 (非 NULL 且是唯一的)。 | 剛好一個資料欄名稱 | 對於單一資料欄： `Column.[Column].Uniqueness` 對於多個資料欄： `Multicolumn.[CommaDelimitedColumns].Uniqueness` | 是 | 否 | 是 | 否 | 否 | 是 |
| IsUnique | 檢查是否 100% 的資料皆為唯一。 | 剛好一個資料欄名稱 | Column.[Column].Uniqueness | 是 | 否 | 是 | 否 | 否 | 是 |
| Mean | 檢查平均值是否與設定的閾值相符。 | 剛好一個資料欄名稱 | Column.[Column].Mean | 是 | 是 | 是 | 是 | 否 | 是 |
| ReferentialIntegrity | 檢查兩個資料集是否具有參照完整性。 | 資料集中一或多個資料欄名稱 參考資料集中的一或多個資料欄名稱 | Column.[ReferenceDatasetAlias].ReferentialIntegrity | 是 | 否 | 是 | 是 | 否 | 否 |
| RowCount | 檢查記錄計數是否與閾值相符。 | 無 | Dataset.\$1.RowCount | 是 | 是 | 否 | 是 | 是 | 是 |
| RowCountMatch | 檢查兩個資料集之間的記錄計數是否相符。 | 參考資料集別名 | Dataset.[ReferenceDatasetAlias].RowCountMatch | 是 | 否 | 否 | 是 | 否 | 否 |
| StandardDeviation | 檢查標準差是否與閥值相符。 | 剛好一個資料欄名稱 | Column.[Column].StandardDeviation | 是 | 是 | 是 | 是 | 否 | 是 |
| SchemaMatch | 檢查兩個資料集之間的結構描述是否相符。 | 參考資料集別名 | Dataset.[ReferenceDatasetAlias].SchemaMatch | 是 | 否 | 否 | 是 | 否 | 否 |
| Sum | 檢查總和是否與設定的閾值相符。 | 剛好一個資料欄名稱 | Column.[Column].Sum | 是 | 是 | 否 | 是 | 否 | 是 |
| Uniqueness | 檢查資料集的唯一性是否與閾值相符。 | 剛好一個資料欄名稱 | Column.[Column].Uniqueness | 是 | 是 | 是 | 是 | 否 | 是 |
| UniqueValueRatio | 檢查唯一值定量是否與閥值相符。 | 剛好一個資料欄名稱 | Column.[Column].UniqueValueRatio | 是 | 是 | 是 | 是 | 否 | 是 |
| FileFreshness | 檢查 Amazon S3 中的檔案是否新鮮。 | 檔案或資料夾路徑和閾值。 | `Dataset.*.FileFreshness.Compliance` `Dataset.*.FileCount` | 是 | 否 | 否 | 否 | 否 | 否 |
| FileMatch | 檢查檔案的內容是否符合檢查總和或其他檔案。此規則使用檢查總和來驗證兩個檔案是否相同。 | 來源檔案或資料夾路徑，及目標檔案或資料夾路徑。 | 不會產生統計資料。 | 是 | 否 | 否 | 否 | 否 | 否 |
| FileSize | 檢查檔案大小是否符合指定的條件。 | 檔案或資料夾路徑和閾值。 | `Dataset.*.FileSize.Compliance` `Dataset.*.FileCount` `Dataset.*.MaximumFileSize` `Dataset.*.MinimumFileSize` | 是 | 否 | 否 | 否 | 否 | 否 |
| FileUniqueness | 使用檢查總和檢查檔案是否是唯一的。 | 檔案或資料夾路徑和閾值。 | `Dataset.*.FileUniquenessRatio` `Dataset.*.FileCount` | 是 | 否 | 否 | 否 | 否 | 否 |
**Topics**
+ [AggregateMatch](dqdl-rule-types-AggregateMatch.md)
+ [ColumnCorrelation](dqdl-rule-types-ColumnCorrelation.md)
+ [ColumnCount](dqdl-rule-types-ColumnCount.md)
+ [ColumnDataType](dqdl-rule-types-ColumnDataType.md)
+ [ColumnExists](dqdl-rule-types-ColumnExists.md)
+ [ColumnLength](dqdl-rule-types-ColumnLength.md)
+ [ColumnNamesMatchPattern](dqdl-rule-types-ColumnNamesMatchPattern.md)
+ [ColumnValues](dqdl-rule-types-ColumnValues.md)
+ [完整度](dqdl-rule-types-Completeness.md)
+ [CustomSQL](dqdl-rule-types-CustomSql.md)
+ [DataFreshness](dqdl-rule-types-DataFreshness.md)
+ [DatasetMatch](dqdl-rule-types-DatasetMatch.md)
+ [DistinctValuesCount](dqdl-rule-types-DistinctValuesCount.md)
+ [Entropy](dqdl-rule-types-Entropy.md)
+ [IsComplete](dqdl-rule-types-IsComplete.md)
+ [IsPrimaryKey](dqdl-rule-types-IsPrimaryKey.md)
+ [IsUnique](dqdl-rule-types-IsUnique.md)
+ [Mean](dqdl-rule-types-Mean.md)
+ [ReferentialIntegrity](dqdl-rule-types-ReferentialIntegrity.md)
+ [RowCount](dqdl-rule-types-RowCount.md)
+ [RowCountMatch](dqdl-rule-types-RowCountMatch.md)
+ [StandardDeviation](dqdl-rule-types-StandardDeviation.md)
+ [總和](dqdl-rule-types-Sum.md)
+ [SchemaMatch](dqdl-rule-types-SchemaMatch.md)
+ [唯一性](dqdl-rule-types-Uniqueness.md)
+ [UniqueValueRatio](dqdl-rule-types-UniqueValueRatio.md)
+ [DetectAnomalies](dqdl-rule-types-DetectAnomalies.md)
+ [FileFreshness](dqdl-rule-types-FileFreshness.md)
+ [FileMatch](dqdl-rule-types-FileMatch.md)
+ [FileUniqueness](dqdl-rule-types-FileUniqueness.md)
+ [FileSize](dqdl-rule-types-FileSize.md)
# AggregateMatch
根據指定運算式檢查兩個資料欄彙總的比率。此規則類型適用於多個資料集。系統會評估兩個資料欄彙總，並將第一個資料欄彙總的結果除以第二個資料欄彙總的結果來產生比率。系統會根據提供的運算式檢查比率，以產生布林值回應。
**語法**
**資料欄彙總**
```
AggregateMatch (.)
```
+ **AGG\$1OPERATION**：用於彙總的操作。目前支援 `sum` 和 `avg`。
**支援的資料欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **OPTIONAL\$1REFERENCE\$1ALIAS**：若資料欄來自參考資料集且不是主資料集，則需提供此參數。如果您在 AWS Glue Data Catalog 中使用此規則，您的參考別名必須遵循格式 "..
**支援的資料欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **COL\$1NAME**：要彙總的資料欄名稱。
**支援的資料欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
**範例：平均值**
```
"avg(rating)"
```
**範例：總和**
```
"sum(amount)"
```
**範例：參考資料集中資料欄的平均值**
```
"avg(reference.rating)"
```
**規則**
```
AggregateMatch
```
+ **AGG\$1EXP\$11**：第一個資料欄彙總。
支援的資料欄類型：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
**支援的資料欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **AGG\$1EXP\$12**：第二個資料欄彙總。
支援的資料欄類型：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
**支援的欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：使用總和執行彙總比對**
下列範例規則會檢查 `amount` 資料欄中的值總和是否與 `total_amount` 資料欄中的值總和完全相等。
```
AggregateMatch "sum(amount)" "sum(total_amount)" = 1.0
```
**範例：使用平均值執行彙總比對**
下列範例規則會檢查 `ratings` 資料欄中值的平均值是否至少等於 `reference` 資料集之 `ratings` 資料欄中值的平均值的 90%。參考資料集會提供為 ETL 或資料目錄體驗中的其他資料來源。
在 AWS Glue ETL 中，您可以使用：
```
AggregateMatch "avg(ratings)" "avg(reference.ratings)" >= 0.9
```
在 AWS Glue Data Catalog 中，您可以使用：
```
AggregateMatch "avg(ratings)" "avg(database_name.tablename.ratings)" >= 0.9
```
**Null 行為**
在計算彙總方法 (總和/平均值) 時，`AggregateMatch` 規則會忽略具有 NULL 值的資料列。例如：
```
+---+-----------+
|id |units |
+---+-----------+
|100|0 |
|101|null |
|102|20 |
|103|null |
|104|40 |
+---+-----------+
```
資料欄 `units` 的平均值將為 (0 \$1 20 \$1 40) / 3 = 20。此計算不會考慮資料列 101 和 103。
# ColumnCorrelation
檢查兩個資料欄與指定表達式之間的*關聯*性。 AWS Glue Data Quality 使用 Pearson 關聯係數來測量兩個資料欄之間的線性關聯性。結果為 -1 到 1 之間的數字，用於測量關係的強度和方向。
**語法**
```
ColumnCorrelation
```
+ **COL\$11\$1NAME** – 您要評估資料品質規則的第一欄名稱。
**支援的欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **COL\$12\$1NAME** – 您要評估資料品質規則的第二個資料欄名稱。
**支援的欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：欄關聯性**
下列範例規則會檢查欄 `height` 和 `weight` 之間的關聯性係數是否具有較強的正關聯性 (係數值大於 0.8)。
```
ColumnCorrelation "height" "weight" > 0.8
```
```
ColumnCorrelation "weightinkgs" "Salary" > 0.8 where "weightinkgs > 40"
```
**動態規則範例**
+ `ColumnCorrelation "colA" "colB" between min(last(10)) and max(last(10))`
+ `ColumnCorrelation "colA" "colB" < avg(last(5)) + std(last(5))`
**Null 行為**
`ColumnCorrelation` 規則會忽略計算相互關聯時值為 `NULL` 的資料列。例如：
```
+---+-----------+
|id |units |
+---+-----------+
|100|0 |
|101|null |
|102|20 |
|103|null |
|104|40 |
+---+-----------+
```
資料列 101 和 103 會遭到忽略，而 `ColumnCorrelation` 將為 1.0。
# ColumnCount
根據指定的運算式檢查主資料集的資料欄計數。在該運算式中，您可以使用 `>` 和 `<` 之類的運算子指定資料欄的數量或範圍。
**語法**
```
ColumnCount
```
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：資料欄計數數字檢查**
下列範例規則會檢查資料欄計數是否位於指定範圍內。
```
ColumnCount between 10 and 20
```
**動態規則範例**
+ `ColumnCount >= avg(last(10))`
+ `ColumnCount between min(last(10))-1 and max(last(10))+1`
# ColumnDataType
檢查所指定資料欄中的值是否可以在 Apache Spark 中轉換為提供的類型。接受 `with threshold` 運算式以檢查資料欄中值的子集。
**語法**
```
ColumnDataType =
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
支援的資料欄類型：字串類型
**支援的資料欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **EXPECTED\$1TYPE**：資料欄中值的預期類型。
支援的值：布林值、日期、時間戳記、整數、雙精度浮點數、浮點數、長整數
**支援的資料欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **EXPRESSION**：選用的運算式，用於指定應屬於預期類型之值的百分比。
**支援的資料欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
**範例：使用資料欄資料類型整數作為字串**
下列範例規則會檢查所指定資料欄中的值 (類型為字串) 是否可轉換為整數。
```
ColumnDataType "colA" = "INTEGER"
```
**範例：使用資料欄類型整數作為字串以檢查值的子集**
下列範例規則會檢查所指定資料欄中是否有超過 90% 的值 (類型為字串) 可轉換為整數。
```
ColumnDataType "colA" = "INTEGER" with threshold > 0.9
```
# ColumnExists
檢查欄是否存在。
**語法**
```
ColumnExists
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：任何欄類型
**範例：欄存在**
下列範例規則會檢查名為 `Middle_Name` 的欄是否存在。
```
ColumnExists "Middle_Name"
```
# ColumnLength
檢查欄中的每一列長度是否符合指定的運算式。
**語法**
```
ColumnLength
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：字串
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：欄列長度**
下列範例規則會檢查名為 `Postal_Code` 的欄中每一列的值是否為 5 個字元長。
```
ColumnLength "Postal_Code" = 5
ColumnLength "weightinkgs" = 2 where "weightinkgs > 10"
```
**Null 行為**
`ColumnLength` 規則會將 `NULL` 視為 0 長度字串。對於 `NULL` 資料列：
```
ColumnLength "Postal_Code" > 4 # this will fail
```
```
ColumnLength "Postal_Code" < 6 # this will succeed
```
以下範例複合規則提供了一種明確使 `NULL` 值失敗的方法：
```
(ColumnLength "Postal_Code" > 4) AND (ColumnValues "Postal_Code" != NULL)
```
# ColumnNamesMatchPattern
檢查主資料集中所有資料欄的名稱是否與指定的規則運算式相符。
**語法**
```
ColumnNamesMatchPattern
```
+ **PATTERN**：您要根據其評估資料品質規則的模式。
**支援的資料欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
**範例：資料欄名稱與模式相符**
下列範例規則會檢查是否所有資料欄皆以 "aws\$1" 字首開頭
```
ColumnNamesMatchPattern "aws_.*"
ColumnNamesMatchPattern "aws_.*" where "weightinkgs > 10"
```
# ColumnValues
您可以針對欄中的值執行運算式。
**語法**
```
ColumnValues
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：任何欄類型
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：允許的值**
下列範例規則會檢查指定欄中的每個值是否位於一組允許的值中 (包括 null、空白和僅包含空格的字串)。
```
ColumnValues "Country" in [ "US", "CA", "UK", NULL, EMPTY, WHITESPACES_ONLY ]
ColumnValues "gender" in ["F", "M"] where "weightinkgs < 10"
```
**範例：規則運算式**
下列範例規則會根據規則運算式檢查欄中的值。
```
ColumnValues "First_Name" matches "[a-zA-Z]*"
```
**範例：日期值**
下列範例規則會根據日期運算式檢查日期欄中的值。
```
ColumnValues "Load_Date" > (now() - 3 days)
```
**範例：數值**
下列範例規則會檢查欄值是否符合特定數值限制條件。
```
ColumnValues "Customer_ID" between 1 and 2000
```
**Null 行為**
對於所有 `ColumnValues` 規則 (`!=` 和 `NOT IN` 除外)，`NULL` 資料列將不符合規則。如果規則因 null 值而失敗，則失敗原因會顯示下列項目：
```
Value: NULL does not meet the constraint requirement!
```
下列範例複合規則提供明確允許 `NULL` 值的方法：
```
(ColumnValues "Age" > 21) OR (ColumnValues "Age" = NULL)
```
使用 `!=` 和 `not in` 語法的否定 ColumnValues 規則會傳遞給 `NULL` 資料列。例如：
```
ColumnValues "Age" != 21
```
```
ColumnValues "Age" not in [21, 22, 23]
```
下列範例提供明確使 `NULL` 值失敗的方法
```
(ColumnValues "Age" != 21) AND (ColumnValues "Age" != NULL)
```
```
ColumnValues "Age" not in [21, 22, 23, NULL]
```
# 完整度
根據指定運算式檢查欄中完整 (非空) 值的百分比。
**語法**
```
Completeness
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：任何欄類型
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：空值百分比**
下列範例規則會檢查欄中 95% 以上的值是否已完成。
```
Completeness "First_Name" > 0.95
Completeness "First_Name" > 0.95 where "weightinkgs > 10"
```
**動態規則範例**
+ `Completeness "colA" between min(last(5)) - 1 and max(last(5)) + 1`
+ `Completeness "colA" <= avg(last(10))`
**Null 行為**
CSV 資料格式注意事項：CSV 資料欄上的空白資料列可以顯示多種行為。
+ 如果資料欄是 `String` 類型，則空白資料列將辨識為空白字串，並且不會使 `Completeness` 規則失敗。
+ 如果資料欄屬於其他資料類型 (例如 `Int`)，則空白資料列會辨識為 `NULL`，且會使 `Completeness` 規則失敗。
# CustomSQL
此規則類型已經過延伸，可支援兩種使用案例：
+ 針對資料集執行自訂 SQL 陳述式，並根據指定的運算式檢查傳回值。
+ 執行自訂 SQL 陳述式，其中您可以在 SELECT 陳述式中指定資料欄名稱，以便與某些條件進行比較來取得資料列層級結果。
**語法**
```
CustomSql
```
+ **SQL\$1STATEMENT** – 傳回單一數值的 SQL 陳述式，並以雙引號括住。
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：用於擷取整體規則結果的自訂 SQL**
此範例規則使用 SQL 陳述式來擷取資料集的記錄計數。然後規則會檢查記錄計數是否在 10 到 20 之間。
```
CustomSql "select count(*) from primary" between 10 and 20
```
**範例：用於擷取資料列層級結果的自訂 SQL**
此範例規則使用 SQL 陳述式，其中您可以在 SELECT 陳述式中指定資料欄名稱，以便與某些條件進行比較來取得資料列層級結果。閥值條件運算式定義了導致整個規則失敗的記錄失敗數量閥值。請注意，規則不能同時包含條件和關鍵字。
```
CustomSql "select Name from primary where Age > 18"
```
或
```
CustomSql "select Name from primary where Age > 18" with threshold > 3
```
**重要**
`primary` 別名代表您要評估的資料集名稱。當您在主控台上使用視覺化 ETL 任務時，`primary` 一律代表正在傳遞至 `EvaluateDataQuality.apply()` 轉換的 `DynamicFrame`。當您使用 AWS Glue Data Catalog 對資料表執行資料品質任務時， `primary`代表資料表。
如果您是使用 AWS Glue Data Catalog，則也可以使用實際的資料表名稱：
```
CustomSql "select count(*) from database.table" between 10 and 20
```
您還可以聯結多個資料表來比較不同的資料元素：
```
CustomSql "select count(*) from database.table inner join database.table2 on id1 = id2" between 10 and 20
```
在 AWS Glue ETL 中，CustomSQL 可以識別資料品質檢查失敗的記錄。您需要傳回屬於目前正在評估資料品質的主資料表的記錄，才能使用此功能。作為查詢的一部分傳回的記錄會視為成功，未傳回的記錄則會視為失敗。這可透過將 CustomSQL 查詢的結果與原始資料集聯結來運作。根據 SQL 查詢的複雜性，可能會對效能產生影響。
若要執行此作業：
+ 您需要從主要資料表中選取至少 1 個資料欄。
+ `select count(*) from primary` 是 OVERALL CustomSQL DQ 規則的有效查詢，但不適用於資料列層級自訂 SQL。
+ 此規則會在評估期間擲回錯誤：`The output from CustomSQL must contain at least one column that matches the input dataset for AWS Glue Data Quality to provide row level results. The SQL query is a valid query but the columns from the SQL result are not present in the Input Dataset. Ensure that matching columns are returned from the SQL.`
+ 在 SQL 查詢中，從您的資料表中選取「主索引鍵」，或選取一組組成複合金鑰的資料欄。否則，可能會因相符重複資料列而導致結果不一致並降低效能。
+ 僅從您的主要資料表選取金鑰，而非從您的參考資料表選取金鑰。
下列規則會確保將期限小於 100 的記錄識別為成功，並將超過該數值的記錄標記為失敗。
```
CustomSql "select id from primary where age < 100"
```
若有 50% 的記錄的期限大於 10，此 CustomSQL 規則將通過，且會一併識別失敗的記錄。此 CustomSQL 傳回的記錄將會視為通過，而未傳回的記錄將會視為失敗。
```
CustomSQL "select ID, CustomerID from primary where age > 10" with threshold > 0.5
```
注意：如果您傳回無法在資料集中使用的記錄，CustomSQL 規則將會失敗。
# DataFreshness
評估目前時間與日期欄值之間的差異，以檢查欄中資料的更新狀態。您可以為此規則類型指定以時間為基礎的運算式，確保欄值處於最新狀態。
**語法**
```
DataFreshness
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：日期
+ **EXPRESSION** - 以小時或天為單位的數值運算式。您必須在運算式中指定時間單位。
**範例：資料更新狀態**
下列範例規則會檢查資料更新狀態。
```
DataFreshness "Order_Date" <= 24 hours
DataFreshness "Order_Date" between 2 days and 5 days
```
**Null 行為**
具有 `NULL` 值的資料列的 `DataFreshness` 規則將會失敗。如果規則因 null 值而失敗，則失敗原因會顯示下列項目：
```
80.00 % of rows passed the threshold
```
失敗的資料列中有 20% 包含具有 `NULL` 的資料列。
下列範例複合規則提供明確允許 `NULL` 值的方法：
```
(DataFreshness "Order_Date" <= 24 hours) OR (ColumnValues "Order_Date" = NULL)
```
**Amazon S3 物件的資料新鮮度**
有時，您需要根據 Amazon S3 檔案建立時間來驗證資料的新鮮度。若要這樣做，您可以使用下列程式碼來取得時間戳記，並將其新增至資料框架，然後套用「資料新鮮度」檢查。
```
df = glueContext.create_data_frame.from_catalog(database = "default", table_name = "mytable")
df = df.withColumn("file_ts", df["_metadata.file_modification_time"])
Rules = [
DataFreshness "file_ts" < 24 hours
]
```
# DatasetMatch
檢查主資料集中的資料是否與參考資料集中的資料相符。系統會使用提供的索引鍵資料欄映射來聯結這兩個資料集。若您只想檢查這些資料欄中的資料是否相等，則可提供其他資料欄映射。請注意，為了讓 **DataSetMatch** 順利運作，您的聯結索引鍵應是唯一的，且不得為 NULL (必須為主索引鍵)。如果不滿足這些條件，則會顯示以下錯誤訊息：「提供的索引鍵映射不適合指定的資料框架」。如果您無法擁有唯一的聯結索引鍵，請考慮使用其他規則類型 (例如 **AggregateMatch**) 來比對摘要資料。
**語法**
```
DatasetMatch
```
+ **REFERENCE\$1DATASET\$1ALIAS**：參考資料集的別名，用於比較來自主資料集的資料。
+ **KEY\$1COLUMN\$1MATION**：以逗號分隔的資料欄名稱清單，構成資料集中的索引鍵。如果兩個資料集中的資料欄名稱不相同，您必須使用 `->` 加以分隔
+ **OPTIONAL\$1MATCH\$1COLUMN\$1MAPPINGS**：如果您只想檢查某些資料欄中的資料是否相符，則可提供此參數。它使用與索引鍵資料欄映射相同的語法。如果未提供此參數，則會比對所有剩餘資料欄中的資料。其餘的非索引鍵資料欄在兩個資料集中必須具有相同的名稱。
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：使用 ID 資料欄比對集合資料集**
下列範例規則會使用 "ID" 資料欄聯結兩個資料集，檢查是否有 90% 以上的主資料集與參考資料集相符。該規則會比較這種情況下的所有資料欄。
```
DatasetMatch "reference" "ID" >= 0.9
```
**範例：使用多個索引鍵資料欄比對集合資料集**
在下列範例中，主資料集與參考資料集的索引鍵資料欄名稱各不相同。`ID_1` 和 `ID_2` 會在主資料集中共同形成一個複合索引鍵。`ID_ref1` 和 `ID_ref2` 會在參考資料集中共同形成一個複合索引鍵。在此情況下，您可使用特殊語法來提供資料欄名稱。
```
DatasetMatch "reference" "ID_1->ID_ref1,ID_2->ID_ref2" >= 0.9
```
**範例：使用多個索引鍵資料欄比對集合資料集，並檢查特定資料欄是否相符**
此範例建立在前面的範例之上。我們僅會檢查包含相符數量的資料欄。此資料欄在主資料集中名為 `Amount1`，在參考資料集中名為 `Amount2`。您想要取得完全相符的結果。
```
DatasetMatch "reference" "ID_1->ID_ref1,ID_2->ID_ref2" "Amount1->Amount2" >= 0.9
```
# DistinctValuesCount
根據指定運算式檢查欄中相異值的數目。
**語法**
```
DistinctValuesCount
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：任何欄類型
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：相異欄值計數**
下列範例規則會檢查名為 `State` 的欄是否包含 3 個以上的相異值。
```
DistinctValuesCount "State" > 3
DistinctValuesCount "Customer_ID" < 6 where "Customer_ID < 10"
```
**動態規則範例**
+ `DistinctValuesCount "colA" between avg(last(10))-1 and avg(last(10))+1`
+ `DistinctValuesCount "colA" <= index(last(10),2) + std(last(5))`
# Entropy
檢查欄的*熵*值是否符合指定的運算式。熵會測量訊息中包含的資訊層級。鑑於欄中值的概率分佈，熵描述了識別值所需的位元數。
**語法**
```
Entropy
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：任何欄類型
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：欄熵**
下列範例規則會檢查名為 `Feedback` 的欄熵值是否大於一。
```
Entropy "Star_Rating" > 1
Entropy "First_Name" > 1 where "Customer_ID < 10"
```
**動態規則範例**
+ `Entropy "colA" < max(last(10))`
+ `Entropy "colA" between min(last(10)) and max(last(10))`
# IsComplete
檢查欄中的所有值是否完整 (非空)。
**語法**
```
IsComplete
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：任何欄類型
**範例：空值**
下列範例會檢查名為 `email` 的欄中所有值是否為非空值。
```
IsComplete "email"
IsComplete "Email" where "Customer_ID between 1 and 50"
IsComplete "Customer_ID" where "Customer_ID < 16 and Customer_ID != 12"
IsComplete "passenger_count" where "payment_type<>0"
```
**Null 行為**
CSV 資料格式注意事項：CSV 資料欄上的空白資料列可以顯示多種行為。
+ 如果資料欄是 `String` 類型，則空白資料列將辨識為空白字串，並且不會使 `Completeness` 規則失敗。
+ 如果資料欄屬於其他資料類型 (例如 `Int`)，則空白資料列會辨識為 `NULL`，且會使 `Completeness` 規則失敗。
# IsPrimaryKey
檢查欄是否包含主索引鍵。如果欄中的所有值都是唯一且完整的 (非空)，則欄包含主索引鍵。您也可以檢查具有多個資料欄的主索引鍵。
**語法**
```
IsPrimaryKey
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：任何欄類型
**範例：主索引鍵**
下列範例規則會檢查名為 `Customer_ID` 的欄是否包含主索引鍵。
```
IsPrimaryKey "Customer_ID"
IsPrimaryKey "Customer_ID" where "Customer_ID < 10"
```
**範例：具有多個資料欄的主索引鍵。以下任意範例都有效。**
```
IsPrimaryKey "colA" "colB"
IsPrimaryKey "colA" "colB" "colC"
IsPrimaryKey colA "colB" "colC"
```
# IsUnique
檢查欄中的所有值是否是唯一的，並傳回布林值。
**語法**
```
IsUnique
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：任何欄類型
**範例**
下列範例規則會檢查名為 `email` 的欄中所有值是否是唯一的。
```
IsUnique "email"
IsUnique "Customer_ID" where "Customer_ID < 10"]
```
下列範例規則會檢查多個資料欄。
```
IsUnique "vendorid" "tpep_pickup_datetime"
```
# Mean
檢查欄中所有值的平均值是否符合指定的運算式。
**語法**
```
Mean
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：平均值**
下列範例規則會檢查欄中所有值的平均值是否超過閾值。
```
Mean "Star_Rating" > 3
Mean "Salary" < 6200 where "Customer_ID < 10"
```
**動態規則範例**
+ `Mean "colA" > avg(last(10)) + std(last(2))`
+ `Mean "colA" between min(last(5)) - 1 and max(last(5)) + 1`
**Null 行為**
`Mean` 規則會忽略計算平均值時值為 `NULL` 的資料列。例如：
```
+---+-----------+
|id |units |
+---+-----------+
|100|0 |
|101|null |
|102|20 |
|103|null |
|104|40 |
+---+-----------+
```
資料欄 `units` 的平均值將為 (0 \$1 20 \$1 40) / 3 = 20。此計算不會考慮資料列 101 和 103。
# ReferentialIntegrity
檢查主資料集中資料欄集值在多大程度上為參考資料集中資料欄集的值子集。
**語法**
```
ReferentialIntegrity
```
+ **PRIMARY\$1COLS**：主資料集中以逗號分隔的資料欄名稱清單。
**支援的資料欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **REFERENCE\$1DATASET\$1COLS**：此參數包含以句號分隔的兩個部分。第一部分是參考資料集的別名。第二部分是在以大括號括住的參考資料集中以逗號分隔的資料欄名稱清單。
**支援的欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：檢查郵遞區號資料欄的參照完整性**
下列範例規則會檢查在主資料集的 `zipcode` 資料欄中，是否有超過 90% 的值存在於 `reference` 資料集的 `zipcode` 資料欄中。
```
ReferentialIntegrity "zipcode" "reference.zipcode" >= 0.9
```
**範例：檢查城市和州/省資料欄的參照完整性**
在下列範例中，包含城市和州/省資訊的資料欄存在於主資料集和參考資料集中。這兩個資料集中的資料欄名稱各不相同。該規則會檢查主資料集中的資料欄值集是否與參考資料集中的資料欄值集完全相等。
```
ReferentialIntegrity "city,state" "reference.{ref_city,ref_state}" = 1.0
```
**動態規則範例**
+ `ReferentialIntegrity "city,state" "reference.{ref_city,ref_state}" > avg(last(10))`
+ `ReferentialIntegrity "city,state" "reference.{ref_city,ref_state}" between min(last(10)) - 1 and max(last(10)) + 1`
# RowCount
根據指定的運算式檢查資料集的列計數。在運算式中，您可以使用 `>` 和 `<` 之類的運算子指定列數或列的範圍。
**語法**
```
RowCount
```
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：列計數數字檢查**
下列範例規則會檢查列計數是否在指定範圍內。
```
RowCount between 10 and 100
RowCount between 1 and 50 where "Customer_ID < 10"
```
**動態規則範例**
```
RowCount > avg(last(10)) *0.8
```
# RowCountMatch
根據指定的運算式，檢查主資料集資料欄計數與參考資料集資料列計數的比率。
**語法**
```
RowCountMatch
```
+ **REFERENCE\$1DATASET\$1ALIAS**：比較資料列計數的參考資料集別名。
**支援的欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：針對參考資料集檢查資料列計數**
下列範例規則會檢查主資料集的資料列計數是否至少為參考資料集資料列計數的 90%。
```
RowCountMatch "reference" >= 0.9
```
# StandardDeviation
根據指定運算式檢查欄中所有值的標準差。
**語法**
```
StandardDeviation
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：標準差**
下列範例規則會檢查名為 `colA` 的欄中的值標準差是否小於指定值。
```
StandardDeviation "Star_Rating" < 1.5
StandardDeviation "Salary" < 3500 where "Customer_ID < 10"
```
**動態規則範例**
+ `StandardDeviation "colA" > avg(last(10) + 0.1`
+ `StandardDeviation "colA" between min(last(10)) - 1 and max(last(10)) + 1`
**Null 行為**
`StandardDeviation` 規則會忽略計算標準差時值為 `NULL` 的資料列。例如：
```
+---+-----------+-----------+
|id |units1 |units2 |
+---+-----------+-----------+
|100|0 |0 |
|101|null |0 |
|102|20 |20 |
|103|null |0 |
|104|40 |40 |
+---+-----------+-----------+
```
資料欄 `units1` 的標準差不會考慮資料列 101 和 103，且結果為 16.33。資料欄 `units2` 的標準差會產生 16。
# 總和
根據指定運算式檢查欄中所有值的總和。
**語法**
```
Sum
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：總和**
下列範例規則會檢查欄中所有值的總和是否超過指定的閾值。
```
Sum "transaction_total" > 500000
Sum "Salary" < 55600 where "Customer_ID < 10"
```
**動態規則範例**
+ `Sum "ColA" > avg(last(10))`
+ `Sum "colA" between min(last(10)) - 1 and max(last(10)) + 1`
**Null 行為**
`Sum` 規則會忽略計算總和時值為 `NULL` 的資料列。例如：
```
+---+-----------+
|id |units |
+---+-----------+
|100|0 |
|101|null |
|102|20 |
|103|null |
|104|40 |
+---+-----------+
```
資料欄 `units` 的總和不會考慮資料列 101 和 103，且結果為 (0 \$1 20 \$1 40) = 60。
# SchemaMatch
檢查主資料集的結構描述是否與參考資料集的結構描述相符。結構描述檢查會以逐個資料欄的形式完成。如果名稱與類型皆完全相同，表示兩個資料欄的結構描述相符。資料欄的順序無關緊要。
**語法**
```
SchemaMatch
```
+ **REFERENCE\$1DATASET\$1ALIAS**：比較結構描述的參考資料集別名。
**支援的欄類型**：位元組、小數、雙精度浮點數、浮點數、整數、長整數、短整數
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：SchemaMatch**
下列範例規則會檢查主資料集的結構描述是否與參考資料集的結構描述完全相符。
```
SchemaMatch "reference" = 1.0
```
# 唯一性
根據指定運算式檢查欄中唯一值的百分比。唯一值正好出現一次。
**語法**
```
Uniqueness
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：任何欄類型
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱[表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例**
下列範例規則會檢查欄中唯一值的百分比是否符合特定數值條件。
```
Uniqueness "email" = 1.0
Uniqueness "Customer_ID" != 1.0 where "Customer_ID < 10"
```
下列範例規則會檢查多個資料欄。
```
Uniqueness "vendorid" "tpep_pickup_datetime" = 1
```
**動態規則範例**
+ `Uniqueness "colA" between min(last(10)) and max(last(10))`
+ `Uniqueness "colA" >= avg(last(10))`
# UniqueValueRatio
根據指定運算式檢查欄的*唯一值比率*。唯一值比率是唯一值數目除以欄中所有相異值數目的分數。唯一值正好出現一次，而相異值*至少*出現一次。
例如，集合 `[a, a, b]` 包含一個唯一值 (`b`) 和兩個相異值 (`a` 和 `b`)。所以集合的唯一值比率是 ½ = 0.5。
**語法**
```
UniqueValueRatio
```
+ **COL\$1NAME** – 您要評估資料品質規則的欄名稱。
**支援的欄類型**：任何欄類型
+ **EXPRESSION** – 針對規則類型回應執行的運算式，以產生布林值。如需詳細資訊，請參閱 [表達式](dqdl.md#dqdl-syntax-rule-expressions)。
**範例：唯一值比率**
此範例會根據值範圍來檢查資料欄的唯一值比率。
```
UniqueValueRatio "test_score" between 0 and 0.5
UniqueValueRatio "Customer_ID" between 0 and 0.9 where "Customer_ID < 10"
```
**動態規則範例**
+ `UniqueValueRatio "colA" > avg(last(10))`
+ `UniqueValueRatio "colA" <= index(last(10),2) + std(last(5))`
# DetectAnomalies
偵測所指定資料品質規則的異常。每次執行 DetectAnomalies 規則時，都會為指定規則儲存評估值。當收集到足夠的資料時，異常偵測演算法會擷取該指定規則的所有歷史資料，並執行異常偵測。偵測到異常時，DetectAnomalies 規則失敗。可以從觀察中獲得偵測到的異常的更多資訊。
**語法**
```
DetectAnomalies
```
`RULE_NAME`：您希望評估和偵測異常的規則名稱。支援的規則：
+ "RowCount"
+ "Completeness"
+ "Uniqueness"
+ "Mean"
+ "Sum"
+ "StandardDeviation"
+ "Entropy"
+ "DistinctValuesCount"
+ "UniqueValueRatio"
+ "ColumnLength"
+ "ColumnValues"
+ "ColumnCorrelation"
+ "CustomSQL"
+ "ColumnCount"
`RULE_PARAMETERS`：某些規則需要其他參數才能執行。請參閱指定的規則文件查看所需的參數。
**範例：RowCount 的異常**
例如，如果我們想要偵測 RowCount 異常，則提供 RowCount 作為規則名稱。
```
DetectAnomalies "RowCount"
```
**範例：ColumnLength 的異常**
例如，如果我們想要偵測 ColumnLength 異常，則提供 ColumnLength 作為規則名稱和資料欄名稱。
```
DetectAnomalies "ColumnLength" "id"
```
# FileFreshness
FileFreshness 會根據您提供的條件，確保您的資料檔案是全新的。其使用您檔案的上次修改時間，來確保資料檔案或整個資料夾是最新的。
此規則會收集兩個指標：
+ 根據您所設定規則的 FileFreshness 合規性
+ 規則掃描的檔案數目
```
{"Dataset.*.FileFreshness.Compliance":1,"Dataset.*.FileCount":1}
```
異常偵測不會考慮這些指標。
**檢查檔案新鮮度**
下列規則可確保 tickets.parquet 在過去 24 小時內建立。
```
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/tickets.parquet" > (now() - 24 hours)
```
**檢查資料夾新鮮度**
如果資料夾中的所有檔案都在過去 24 小時內建立或修改，則下列規則會通過。
```
FileFreshness "s3://bucket/" >= (now() -1 days)
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" >= (now() - 24 hours)
```
**使用閾值檢查資料夾或檔案新鮮度**
如果資料夾 "tickets" 中有 10% 的檔案是在過去 10 天內建立或修改的，則下列規則會通過。
```
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" < (now() - 10 days) with threshold > 0.1
```
**檢查具有特定日期的檔案或資料夾**
您可以檢查特定日期的檔案新鮮度。
```
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" > "2020-01-01"
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" between "2023-01-01" and "2024-01-01"
```
**使用時間檢查檔案或資料夾**
您可以使用 FileFreshness 來確保檔案已根據特定時間送達。
```
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" between now() and (now() - 45 minutes)
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" between "9:30 AM" and "9:30 PM"
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" > (now() - 10 minutes)
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" > now()
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" between (now() - 2 hours) and (now() + 15 minutes)
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" between (now() - 3 days) and (now() + 15 minutes)
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" between "2001-02-07" and (now() + 15 minutes)
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" > "21:45""
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" > "2024-01-01"
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" between "02:30" and "04:30"
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" between "9:30 AM" and "22:15"
```
關鍵考量事項：
+ FileFreshness 可以使用天、小時及分鐘單位來評估檔案
+ 有時，其支援上午/下午和 24 小時
+ 除非指定覆寫，否則時間會以 UTC 計算
+ 日期按 UTC 時間 00:00 計算
以時間為基礎的 FileFreshness 運作方式如下：
```
FileFreshness "s3://amzn-s3-demo-bucket/artifacts/file/tickets/" > "21:45"
```
+ 首先，時間 "21:45" 會與 UTC 格式的今天日期合併，以建立日期時間欄位
+ 接下來，日期時間會轉換為您指定的時區
+ 最後，評估規則
**選用的以檔案為基礎的規則標籤：**
標籤可讓您控制規則行為。
**recentFiles**
此標籤會先保留最新的檔案，以限制處理的檔案數目。
```
FileFreshness "s3://amzn-s3-demo-bucket/" between (now() - 100 minutes) and (now() + 10 minutes) with recentFiles = 1
```
**uriRegex**
**注意**
此`uriRegex`標籤可在 AWS Glue 5.0 和更新版本中使用。
此標籤透過將 regex 模式套用至檔案路徑來篩選檔案。只會處理路徑符合模式的檔案。您也可以使用負 lookahead 來排除符合模式的檔案。
```
# Match only files with a .csv extension
FileFreshness "s3://amzn-s3-demo-bucket/" > (now() - 24 hours) with uriRegex = "\.csv$"
# Match Parquet files that contain "orders_" in the path
FileFreshness "s3://amzn-s3-demo-bucket/" > (now() - 24 hours) with uriRegex = ".*orders_.*\.parquet"
# Exclude files ending in .tmp using a negative lookahead
FileFreshness "s3://amzn-s3-demo-bucket/" > (now() - 24 hours) with uriRegex = "(?!.*\.tmp$).*"
```
**filterOrder**
**注意**
此`filterOrder`標籤可在 AWS Glue 5.0 和更新版本中使用。
當您同時使用多個篩選條件標籤，例如 `recentFiles`和 `uriRegex` 時，該`filterOrder`標籤會控制套用它們的順序。預設順序為 `recentFiles` ，然後是 `uriRegex`。
```
FileFreshness "s3://amzn-s3-demo-bucket/" > (now() - 24 hours) with recentFiles = 1 with uriRegex = "inventory_" with filterOrder = ["uriRegex","recentFiles"]
```
在上述範例中，會先套用`uriRegex`篩選條件，只選取符合 "inventory\$1" 的檔案，然後從該篩選集`recentFiles = 1`取得最新的檔案。如果沒有 `filterOrder`，預設行為會先採取單一最新檔案，然後套用 regex，如果最新檔案不符合模式，則可能會導致檔案不相符。
**注意**
`filterOrder` 清單中的所有值都必須參考相同規則上也存在的其他篩選條件標籤 (`recentFiles` 或 `uriRegex`)。非篩選條件標籤，例如 `timeZone`或 `failFast` 在 中無效`filterOrder`。
**failFast**
設為 時`"true"`，規則會在第一個未通過更新條件的檔案上立即傳回失敗，而不是評估所有檔案並計算合規比率。
```
FileFreshness "s3://amzn-s3-demo-bucket/" > (now() - 24 hours) with failFast = "true"
```
**timeZone**
接受的時區覆寫，請參閱[允許的時區](https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html)以了解支援的時區。
```
FileFreshness "s3://path/" > "21:45" with timeZone = "America/New_York"
```
```
FileFreshness "s3://path/" > "21:45" with timeZone = "America/Chicago"
```
```
FileFreshness "s3://path/" > "21:45" with timeZone = "Europe/Paris"
```
```
FileFreshness "s3://path/" > "21:45" with timeZone = "Asia/Shanghai"
```
```
FileFreshness "s3://path/" > "21:45" with timeZone = "Australia/Darwin"
```
**直接從資料框推斷檔案名稱**
您不一定必須提供檔案路徑。例如，當您在 AWS Glue Data Catalog 中編寫規則時，可能很難找到目錄資料表正在使用的資料夾。 AWS Glue Data Quality 可以找到用來填入資料框架的特定資料夾或檔案，並可以偵測它們是否新鮮。
**注意**
此功能只有在檔案成功讀取到 DynamicFrame 或 DataFrame 時才有效。
```
FileFreshness > (now() - 24 hours)
```
此規則會尋找用來填入動態框架或資料框的資料夾路徑或檔案。這適用於 Amazon S3 路徑或 Amazon S3 型 AWS Glue Data Catalog 資料表。有幾個考量：
1. 在 AWS Glue ETL 中，您必須在 Amazon S3 或 Glue Data Catalog 轉換後立即進行 **EvaluateDataQuality** AWS 轉換。
![\[螢幕擷取畫面顯示連線至 Amazon S3 節點的評估資料品質節點。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/data-quality-file-freshness.png)
1. 此規則無法在 AWS Glue 互動式工作階段中運作。
如果您在這兩種情況下嘗試這麼做，或 AWS Glue 找不到檔案時， AWS Glue 會擲回下列錯誤： `“Unable to parse file path from DataFrame”`
# FileMatch
FileMatch 規則可讓您將檔案與其他檔案或檢查總和進行比較。這在幾個案例中很有用：
1. 驗證從外部來源收到的檔案：您可以使用 FileMatch，透過比較檢查總和來確保您已收到來自外部來源的正確檔案。這有助於驗證您正在擷取的資料的完整性。
1. 比較兩個不同資料夾中的資料：FileMatch 可用於比較兩個資料夾之間的檔案。
此規則會收集一個指標：規則掃描的檔案數目。
```
{"Dataset.*.FileCount":1}
```
**使用檢查總和驗證檔案：**
FileMatch 接受檔案和一組檢查總和，以確保至少一個檢查總和與該檔案相符。
```
FileMatch "s3://amzn-s3-demo-bucket/file.json" in ["3ee0d8617ac041793154713e5ef8f319"] with hashAlgorithm = "MD5"
FileMatch "s3://amzn-s3-demo-bucket/file.json" in ["3ee0d8617ac041793154713e5ef8f319"] with hashAlgorithm = "SHA-1"
FileMatch "s3://amzn-s3-demo-bucket/file.json" in ["3ee0d8617ac041793154713e5ef8f319"] with hashAlgorithm = "SHA-256"
FileMatch "s3://amzn-s3-demo-bucket/file.json" in ["3ee0d8617ac041793154713e5ef8f319"]
```
支援下列標準演算法：
+ MD5
+ SHA-1
+ SHA-256
如果您不提供演算法，則預設值為 SHA-256。
**使用一組檢查總和驗證資料夾中的所有檔案：**
```
FileMatch "s3://amzn-s3-demo-bucket /" in ["3ee0d8617ac041793154713e5ef8f319", "7e8617ac041793154713e5ef8f319"] with hashAlgorithm = "MD5"
FileMatch "s3://amzn-s3-demo-bucket /internal-folder/" in ["3ee0d8617ac041793154713e5ef8f319", "7e8617ac041793154713e5ef8f319"]
```
**比較不同資料夾中的檔案**
```
# Compare all files across two buckets
FileMatch "s3://original_bucket/" "s3://archive_bucket/"
# Compare files within specific subfolders
FileMatch "s3://original_bucket/internal-folder/" "s3://original_bucket/other-folder/"
# Compare only .json files across two folders
FileMatch "s3://original_bucket/" "s3://archive_bucket/" with uriRegex = "\.json$"
# Compare only the 5 most recent .csv files
FileMatch "s3://original_bucket/" "s3://archive_bucket/" with recentFiles = 5 with uriRegex = "\.csv$" with filterOrder = ["uriRegex","recentFiles"]
```
FileMatch 會檢查 `original_bucket` 中的檔案內容，並確保其符合 `archive_bucket` 中的內容。如果規則不完全相符，則規則將會失敗。其也可以檢查內部資料夾或個別檔案的內容。
FileMatch 也可以互相檢查個別檔案。
```
FileMatch "s3://amzn-s3-demo-bucket /file_old.json" "s3://amzn-s3-demo-bucket /file_new.json"
```
**直接從資料框推斷檔案名稱**
您不一定必須提供檔案路徑。例如，當您在 AWS Glue Data Catalog (Amazon S3 後端） 中編寫規則時，可能很難找到目錄資料表正在使用的資料夾。 AWS Glue Data Quality 可以找到用來填入資料框架的特定資料夾或檔案。
**注意**
此功能只有在檔案成功讀取到 DynamicFrame 或 DataFrame 時才有效。
```
FileMatch in ["3ee0d8617ac041793154713e5ef8f319"] with hashAlgorithm = "MD5"
FileMatch in ["3ee0d8617ac041793154713e5ef8f319"] with hashAlgorithm = "SHA-1"
FileMatch in ["3ee0d8617ac041793154713e5ef8f319"] with hashAlgorithm = "SHA-256"
FileMatch in ["3ee0d8617ac041793154713e5ef8f319"]
```
如果提供的檢查總和與計算結果不同，FileMatch 會提醒您差異。
![\[螢幕擷取畫面顯示 DQ 狀態為「規則失敗」的規則。FileMatch 說明失敗。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/data-quality-file-match.png)
**選用的以檔案為基礎的規則標籤：**
標籤可讓您控制規則行為。
**recentFiles**
此標籤會先保留最新的檔案，以限制處理的檔案數目。
```
FileMatch "s3://bucket/" in ["3ee0d8617ac04179sam4713e5ef8f319"] with recentFiles = 1
```
**uriRegex**
**注意**
此`uriRegex`標籤可在 AWS Glue 5.0 和更新版本中使用。
此標籤透過將 regex 模式套用至檔案路徑來篩選檔案。只會處理路徑符合模式的檔案。您也可以使用負 lookahead 來排除符合模式的檔案。
```
# Match only files with a .json extension
FileMatch "s3://bucket/" in ["3ee0d8617ac04179sam4713e5ef8f319"] with uriRegex = "\.json$"
# Exclude files ending in .tmp using a negative lookahead
FileMatch "s3://bucket/" in ["3ee0d8617ac04179sam4713e5ef8f319"] with uriRegex = "(?!.*\.tmp$).*"
```
**filterOrder**
**注意**
此`filterOrder`標籤可在 AWS Glue 5.0 和更新版本中使用。
當您同時使用多個篩選條件標籤，例如 `recentFiles`和 `uriRegex` 時，該`filterOrder`標籤會控制套用它們的順序。預設順序為 `recentFiles` ，然後是 `uriRegex`。
```
FileMatch "s3://bucket/" in ["3ee0d8617ac04179sam4713e5ef8f319"] with recentFiles = 1 with uriRegex = "\.json$" with filterOrder = ["uriRegex","recentFiles"]
```
**matchFileName**
此標籤可確保檔案沒有重複的名稱。預設行為為 false。
```
FileMatch "s3://amzn-s3-demo-bucket/file.json" in ["3ee0d8617ac04179sam4713e5ef8f319"] with matchFileName = "true"
```
有幾個考量：
1. 在 AWS Glue ETL 中，您必須在 Amazon S3 或 AWS Glue Data Catalog 轉換後立即進行 **EvaluateDataQuality** 轉換。
![\[螢幕擷取畫面顯示 DQ 狀態為「規則失敗」的規則。FileMatch 說明失敗。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/data-quality-file-match-transform.png)
1. 此規則無法在 AWS Glue 互動式工作階段中運作。
# FileUniqueness
檔案唯一性可讓您確保您從資料生產者收到的資料中沒有重複的檔案。
其會收集下列資料統計資料：
1. 規則掃描的檔案數目
1. 檔案的唯一性比率
```
Dataset.*.FileUniquenessRatio: 1.00, Dataset.*.FileCount: 8.00
```
**尋找資料夾中的重複檔案：**
```
FileUniqueness "s3://bucket/" > 0.5
FileUniqueness "s3://bucket/folder/" = 1
```
**直接從資料框推斷資料夾名稱以偵測重複項目：**
您不一定必須提供檔案路徑。例如，當您在 AWS Glue Data Catalog 中編寫規則時，可能很難找到目錄資料表正在使用的資料夾。 AWS Glue Data Quality 可以找到用來填入資料框架的特定資料夾或檔案。
**注意**
使用推論時，以檔案為基礎的規則只能偵測成功讀取到 DynamicFrame 或 DataFrame 的檔案。
```
FileUniqueness > 0.5
```
**選用的以檔案為基礎的規則標籤：**
標籤可讓您控制規則行為。
**recentFiles**
此標籤會先保留最新的檔案，以限制處理的檔案數目。
```
FileUniqueness "s3://amzn-s3-demo-bucket/" > 0.5 with recentFiles = 1
```
**uriRegex**
**注意**
此`uriRegex`標籤可在 AWS Glue 5.0 和更新版本中使用。
此標籤透過將 regex 模式套用至檔案路徑來篩選檔案。只會處理路徑符合模式的檔案。您也可以使用負 lookahead 來排除符合模式的檔案。
```
# Match only files with a .csv extension
FileUniqueness "s3://bucket/" > 0.5 with uriRegex = "\.csv$"
# Exclude files ending in .tmp using a negative lookahead
FileUniqueness "s3://bucket/" > 0.5 with uriRegex = "(?!.*\.tmp$).*"
```
**filterOrder**
**注意**
此`filterOrder`標籤可在 AWS Glue 5.0 和更新版本中使用。
當您同時使用多個篩選條件標籤，例如 `recentFiles`和 `uriRegex` 時，該`filterOrder`標籤會控制套用它們的順序。預設順序為 `recentFiles` ，然後是 `uriRegex`。
```
FileUniqueness "s3://bucket/" > 0.5 with recentFiles = 5 with uriRegex = "\.csv$" with filterOrder = ["uriRegex","recentFiles"]
```
**matchFileName**
此標籤可確保檔案沒有重複的名稱。預設行為為 false。
```
FileUniqueness "s3://amzn-s3-demo-bucket/" > 0.5 with matchFileName = "true"
```
有幾個考量：
1. 在 AWS Glue ETL 中，您必須在 Amazon S3 或 Glue Data Catalog 轉換後立即進行 **EvaluateDataQuality** AWS 轉換。
1. 此規則無法在 AWS Glue 互動式工作階段中運作。
# FileSize
FileSize 規則類型可讓您確保檔案符合特定的檔案大小條件。這適用於下列使用案例：
1. 確保生產者不會傳送空白或小得多的檔案進行處理。
1. 確保您的目標儲存貯體沒有較小的檔案，這可能會導致效能問題。
FileSize 會收集下列指標：
1. 合規： 傳回符合您已建立的規則閾值的檔案百分比
1. 檔案計數：規則掃描的檔案數目
1. 檔案大小下限 (位元組)
1. 檔案大小上限 (位元組)
```
Dataset.*.FileSize.Compliance: 1.00,
Dataset.*.FileCount: 8.00,
Dataset.*.MaximumFileSize: 327413121.00,
Dataset.*.MinimumFileSize: 204558920.00
```
這些指標不支援異常偵測。
**驗證檔案大小**
在 file.dat 大於 2 MB 時，此規則將通過。
```
FileSize "s3://amzn-s3-demo-bucket/file.dat" > 2 MB
```
支援的單位包括 B (位元組)、MB (百萬位元組)、GB (十億位元組) 和 TB (兆位元組)。
**驗證資料夾中檔案的大小**
```
FileSize "s3://bucket/" > 5 B
FileSize "s3://bucket/" < 2 GB
```
如果 s3://amzn-s3-demo-bucket 中的 70% 檔案介於 2 GB 與 1 TB 之間，則此規則將通過。
```
FileSize "s3://amzn-s3-demo-bucket/" between 2 GB and 1 TB with threshold > 0.7
```
**直接從資料框推斷檔案名稱**
您不一定必須提供檔案路徑。例如，當您在 Data Catalog 中編寫規則時，可能很難找到目錄資料表正在使用的資料夾。 AWS Glue Data Quality 可以找到用來填入資料框架的特定資料夾或檔案。
**注意**
此功能只有在檔案成功讀取到 DynamicFrame 或 DataFrame 時才有效。
```
FileSize < 10 MB with threshold > 0.7
```
**選用的以檔案為基礎的規則標籤：**
標籤可讓您控制規則行為。
**recentFiles**
此標籤會先保留最新的檔案，以限制處理的檔案數目。
```
FileSize "s3://amzn-s3-demo-bucket/" > 5 B with recentFiles = 1
```
**uriRegex**
**注意**
此`uriRegex`標籤可在 AWS Glue 5.0 和更新版本中使用。
此標籤透過將 regex 模式套用至檔案路徑來篩選檔案。只會處理路徑符合模式的檔案。您也可以使用負 lookahead 來排除符合模式的檔案。
```
# Match only files with a .dat extension
FileSize "s3://bucket/" > 5 B with uriRegex = "\.dat$"
# Exclude files ending in .tmp using a negative lookahead
FileSize "s3://bucket/" > 5 B with uriRegex = "(?!.*\.tmp$).*"
```
**filterOrder**
**注意**
此`filterOrder`標籤可在 AWS Glue 5.0 和更新版本中使用。
當您同時使用多個篩選條件標籤，例如 `recentFiles`和 `uriRegex` 時，該`filterOrder`標籤會控制套用它們的順序。預設順序為 `recentFiles` ，然後是 `uriRegex`。
```
FileSize "s3://bucket/" > 5 B with recentFiles = 5 with uriRegex = "\.dat$" with filterOrder = ["uriRegex","recentFiles"]
```
**failFast**
設為 時`"true"`，規則會在第一個未通過大小條件的檔案上立即傳回失敗，而不是評估所有檔案並計算合規比率。
```
FileSize "s3://bucket/" > 2 MB with failFast = "true"
```
有幾個考量：
1. 在 AWS Glue ETL 中，您必須在 Amazon S3 或 Data Catalog 轉換後立即評估 DataQuality 轉換。
1. 此規則無法在 AWS Glue 互動式工作階段中運作。
# 使用 API 測量和管理資料品質
本主題介紹如何使用 API 測量和管理資料品質。
**Contents**
+ [先決條件](#using-apis-prerequisites)
+ [使用 AWS Glue Data Quality 建議](#using-apis-recommendations)
+ [使用 AWS Glue Data Quality 規則集](#using-apis-rulesets)
+ [使用 AWS Glue Data Quality 執行](#using-apis-runs)
+ [使用 AWS Glue Data Quality 結果](#using-apis-results)
## 先決條件
+ 請確定您的 boto3 版本是最新的，以便包含最新的 AWS Glue Data Quality API。
+ 請確定您的 AWS CLI 版本是最新的，以便包含最新的 CLI。
如果您使用 AWS Glue 任務來執行這些 APIs，您可以使用下列選項將 boto3 程式庫更新至最新版本：
```
—additional-python-modules boto3==
```
## 使用 AWS Glue Data Quality 建議
**若要啟動 AWS Glue Data Quality 建議執行：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def start_data_quality_rule_recommendation_run(self, database_name, table_name, role_arn):
"""
Starts a recommendation run that is used to generate rules when you don't know what rules to write. AWS Glue Data Quality
analyzes the data and comes up with recommendations for a potential ruleset. You can then triage the ruleset
and modify the generated ruleset to your liking.
:param database_name: The name of the AWS Glue database which contains the dataset.
:param table_name: The name of the AWS Glue table against which we want a recommendation
:param role_arn: The Amazon Resource Name (ARN) of an AWS Identity and Access Management (IAM) role that grants permission to let AWS Glue access the resources it needs.
"""
try:
response = self.client.start_data_quality_rule_recommendation_run(
DataSource={
'GlueTable': {
'DatabaseName': database_name,
'TableName': table_name
}
},
Role=role_arn
)
except ClientError as err:
logger.error(
"Couldn't start data quality recommendation run %s. Here's why: %s: %s", name,
err.response['Error']['Code'], err.response['Error']['Message'])
raise
else:
return response['RunId']
```
對於建議執行，您可以使用 `pushDownPredicates` 或 `catalogPartitionPredicates` 來改善效能，並僅在目錄來源的特定分割區上執行建議。
```
client.start_data_quality_rule_recommendation_run(
DataSource={
'GlueTable': {
'DatabaseName': database_name,
'TableName': table_name,
'AdditionalOptions': {
'pushDownPredicate': "year=2022"
}
}
},
Role=role_arn,
NumberOfWorkers=2,
CreatedRulesetName=''
)
```
**若要取得 AWS Glue Data Quality 建議執行的結果：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def get_data_quality_rule_recommendation_run(self, run_id):
"""
Gets the specified recommendation run that was used to generate rules.
:param run_id: The id of the data quality recommendation run
"""
try:
response = self.client.get_data_quality_rule_recommendation_run(RunId=run_id)
except ClientError as err:
logger.error(
"Couldn't get data quality recommendation run %. Here's why: %s: %s", run_id,
err.response['Error']['Code'], err.response['Error']['Message'])
raise
else:
return response
```
從上面的回應物件中，您可以擷取執行建議的 RuleSet，以在後續步驟中使用：
```
print(response['RecommendedRuleset'])
Rules = [
RowCount between 2000 and 8000,
IsComplete "col1",
IsComplete "col2",
StandardDeviation "col3" between 58138330.8 and 64258155.09,
ColumnValues "col4" between 1000042965 and 1214474826,
IsComplete "col5"
]
```
**若要取得可篩選並列出之所有建議執行的清單：**
```
response = client.list_data_quality_rule_recommendation_runs(
Filter={
'DataSource': {
'GlueTable': {
'DatabaseName': '',
'TableName': ''
}
}
)
```
**若要取消現有的 AWS Glue Data Quality 建議任務：**
```
response = client.cancel_data_quality_rule_recommendation_run(
RunId='dqrun-d4b6b01957fdd79e59866365bf9cb0e40fxxxxxxx'
)
```
## 使用 AWS Glue Data Quality 規則集
**若要建立 AWS Glue Data Quality 規則集：**
```
response = client.create_data_quality_ruleset(
Name='',
Ruleset='Rules = [IsComplete "col1", IsPrimaryKey "col2", RowCount between 2000 and 8000]',
TargetTable={
'TableName': '',
'DatabaseName': ''
}
)
```
**若要取得資料品質規則集：**
```
response = client.get_data_quality_ruleset(
Name=''
)
print(response)
```
您可以使用此 API 擷取規則集：
```
print(response['Ruleset'])
```
**若要列出資料表的所有資料品質規則集：**
```
response = client.list_data_quality_rulesets()
```
您可以使用 API 中的篩選條件，篩選在特定資料庫或資料表中附加的所有規則集：
```
response = client.list_data_quality_rulesets(
Filter={
'TargetTable': {
'TableName': '',
'DatabaseName': ''
}
},
)
```
**若要更新資料品質規則集：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def update_data_quality_ruleset(self, ruleset_name, ruleset_string):
"""
Update an AWS Glue Data Quality Ruleset
:param ruleset_name: The name of the AWS Glue Data Quality ruleset to update
:param ruleset_string: The DQDL ruleset string to update the ruleset with
"""
try:
response = self.client.update_data_quality_ruleset(
Name=ruleset_name,
Ruleset=ruleset_string
)
except ClientError as err:
logger.error(
"Couldn't update the AWS Glue Data Quality ruleset. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
else:
return response
```
**若要刪除資料品質規則集：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def delete_data_quality_ruleset(self, ruleset_name):
"""
Delete a AWS Glue Data Quality Ruleset
:param ruleset_name: The name of the AWS Glue Data Quality ruleset to delete
"""
try:
response = self.client.delete_data_quality_ruleset(
Name=ruleset_name
)
except ClientError as err:
logger.error(
"Couldn't delete the AWS Glue Data Quality ruleset. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
else:
return response
```
## 使用 AWS Glue Data Quality 執行
**若要啟動 AWS Glue Data Quality 執行：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def start_data_quality_ruleset_evaluation_run(self, database_name, table_name, role_name, ruleset_list):
"""
Start an AWS Glue Data Quality evaluation run
:param database_name: The name of the AWS Glue database which contains the dataset.
:param table_name: The name of the AWS Glue table against which we want to evaluate.
:param role_arn: The Amazon Resource Name (ARN) of an AWS Identity and Access Management (IAM) role that grants permission to let AWS Glue access the resources it needs.
:param ruleset_list: The list of AWS Glue Data Quality ruleset names to evaluate.
"""
try:
response = client.start_data_quality_ruleset_evaluation_run(
DataSource={
'GlueTable': {
'DatabaseName': database_name,
'TableName': table_name
}
},
Role=role_name,
RulesetNames=ruleset_list
)
except ClientError as err:
logger.error(
"Couldn't start the AWS Glue Data Quality Run. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
else:
return response['RunId']
```
請記住，您可以傳遞 `pushDownPredicate` 或 `catalogPartitionPredicate` 參數，以確保資料品質執行只鎖定目錄資料表中的一組特定分割區。例如：
```
response = client.start_data_quality_ruleset_evaluation_run(
DataSource={
'GlueTable': {
'DatabaseName': '',
'TableName': '',
'AdditionalOptions': {
'pushDownPredicate': 'year=2023'
}
}
},
Role='',
NumberOfWorkers=5,
Timeout=123,
AdditionalRunOptions={
'CloudWatchMetricsEnabled': False
},
RulesetNames=[
'',
]
)
```
您也可以設定在 ROW 或 COLUMN 層級，評估規則集中複合規則的方式。如需複合規則運作方式的詳細資訊，請參閱文件中的[複合規則運作方式](dqdl.md#dqdl-syntax-composite-rules)。
如何在請求中設定複合規則評估方法的範例：
```
response = client.start_data_quality_ruleset_evaluation_run(
DataSource={
'GlueTable': {
'DatabaseName': '',
'TableName': '',
'AdditionalOptions': {
'pushDownPredicate': 'year=2023'
}
}
},
Role='',
NumberOfWorkers=5,
Timeout=123,
AdditionalRunOptions={
'CompositeRuleEvaluationMethod':ROW
},
RulesetNames=[
'',
]
)
```
**若要取得 AWS Glue Data Quality 執行的相關資訊：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def get_data_quality_ruleset_evaluation_run(self, run_id):
"""
Get details about an AWS Glue Data Quality Run
:param run_id: The AWS Glue Data Quality run ID to look up
"""
try:
response = self.client.get_data_quality_ruleset_evaluation_run(
RunId=run_id
)
except ClientError as err:
logger.error(
"Couldn't look up the AWS Glue Data Quality run ID. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
else:
return response
```
**若要從 AWS Glue Data Quality 執行取得結果：**
對於指定的 AWS Glue Data Quality 執行，您可以使用下列方法擷取執行評估的結果：
```
response = client.get_data_quality_ruleset_evaluation_run(
RunId='d4b6b01957fdd79e59866365bf9cb0e40fxxxxxxx'
)
resultID = response['ResultIds'][0]
response = client.get_data_quality_result(
ResultId=resultID
)
print(response['RuleResults'])
```
**若要列出所有 AWS Glue Data Quality 執行：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def list_data_quality_ruleset_evaluation_runs(self, database_name, table_name):
"""
Lists all the AWS Glue Data Quality runs against a given table
:param database_name: The name of the database where the data quality runs
:param table_name: The name of the table against which the data quality runs were created
"""
try:
response = self.client.list_data_quality_ruleset_evaluation_runs(
Filter={
'DataSource': {
'GlueTable': {
'DatabaseName': database_name,
'TableName': table_name
}
}
}
)
except ClientError as err:
logger.error(
"Couldn't list the AWS Glue Quality runs. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
else:
return response
```
您可以修改篩選子句，僅顯示特定時間之間或針對特定資料表執行的結果。
**若要停止持續的 AWS Glue Data Quality 執行：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def cancel_data_quality_ruleset_evaluation_run(self, result_id):
"""
Cancels a given AWS Glue Data Quality run
:param result_id: The result id of a AWS Glue Data Quality run to cancel
"""
try:
response = self.client.cancel_data_quality_ruleset_evaluation_run(
ResultId=result_id
)
except ClientError as err:
logger.error(
"Couldn't cancel the AWS Glue Data Quality run. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
else:
return response
```
## 使用 AWS Glue Data Quality 結果
**若要取得 Glue Data Quality AWS 執行結果：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def get_data_quality_result(self, result_id):
"""
Outputs the result of an AWS Glue Data Quality Result
:param result_id: The result id of an AWS Glue Data Quality run
"""
try:
response = self.client.get_data_quality_result(
ResultId=result_id
)
except ClientError as err:
logger.error(
"Couldn't get the AWS Glue Data Quality result. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
else:
return response
```
**檢視為指定資料品質結果收集的統計資料：**
```
import boto3
from botocore.exceptions import ClientError
import logging
logger = logging.getLogger(__name__)
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def get_profile_for_data_quality_result(self, result_id):
"""
Outputs the statistic profile for a AWS Glue Data Quality Result
:param result_id: The result id of a AWS Glue Data Quality run
"""
try:
response = self.glue_client.get_data_quality_result(
ResultId=result_id
)
# the profile contains all statistics gathered for the result
profile_id = response['ProfileId']
profile = self.glue_client.list_data_quality_statistics(
ProfileId = profile_id
)
return profile
except ClientError as err:
logger.error(
"Couldn't retrieve Data Quality profile. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
```
**檢視跨多個資料品質執行收集的統計資料的時間序列：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def get_statistics_for_data_quality_result(self, profile_id):
"""
Outputs an array of datapoints for each statistic in the input result.
:param result_id: The profile id of a AWS Glue Data Quality run
"""
try:
profile = self.glue_client.list_data_quality_statistics(
ProfileId = profile_id
)
statistics = [self.glue_client.list_data_quality_statistics(
StatisticId = s['StatisticId']
) for s in profile['Statistics']]
return statistics
except ClientError as err:
logger.error(
"Couldn't retrieve Data Quality statistics. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
```
**檢視特定統計資料的異常偵測模型：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def get_model_training_result_for_statistic(self, statistic_id, profile_id):
"""
Outputs the details (bounds) of anomaly detection training for the given statistic at the given profile.
:param statistic_id the model's statistic (the timeseries it is tracking)
:param profile_id the profile associated with the model (a point in the timeseries)
"""
try:
model = self.glue_client.get_data_quality_model_result(
ProfileId = profile_id, StatisticId = statistic_id
)
return model
except ClientError as err:
logger.error(
"Couldn't retrieve Data Quality model results. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
```
**從統計資料模型的異常偵測基準中排除資料點：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def apply_exclusions_to_statistic(self, statistic_id, profile_ids):
"""
Annotate some points along a given statistic timeseries.
This example excludes the provided values; INCLUDE can also be used to undo this action.
:param statistic_id the statistic timeseries to annotate
:param profile_id the profiles we want to exclude (points in the timeseries)
"""
try:
response = self.glue_client.batch_put_data_quality_statistic_annotation(
InclusionAnnotations = [
{'ProfileId': prof_id,
'StatisticId': statistic_id,
'InclusionAnnotation': 'EXCLUDE'} for prof_id in profile_ids
]
)
return response['FailedInclusionAnnotations']
except ClientError as err:
logger.error(
"Couldn't store Data Quality annotations. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
```
**檢視特定統計資料的異常偵測模型訓練狀態：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def get_model_training_status_for_statistic(self, statistic_id, profile_id):
"""
Outputs the status of anomaly detection training for the given statistic at the given profile.
:param statistic_id the model's statistic (the timeseries it is tracking)
:param profile_id the profile associated with the model (a point in the timeseries)
"""
try:
model = self.glue_client.get_data_quality_model(
ProfileId = profile_id, StatisticId = statistic_id
)
return model
except ClientError as err:
logger.error(
"Couldn't retrieve Data Quality statistics. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
```
**從異常偵測基準中排除特定資料品質執行的所有結果：**
```
class GlueWrapper:
"""Encapsulates AWS Glue actions."""
def __init__(self, glue_client):
"""
:param glue_client: A Boto3 AWS Glue client.
"""
self.glue_client = glue_client
def apply_exclusions_to_profile(self, profile_id):
"""
Exclude datapoints produced by a run across statistic timeseries.
This example excludes the provided values; INCLUDE can also be used to undo this action.
:param profile_id the profiles we want to exclude (points in the timeseries)
"""
try:
response = self.glue_client.put_data_quality_profile_annotation(
ProfileId = profile_id,
InclusionAnnotation = "EXCLUDE"
)
return response
except ClientError as err:
logger.error(
"Couldn't store Data Quality annotations. Here's why: %s: %s",
err.response['Error']['Code'], err.response['Error']['Message'])
raise
```
**從指定的資料品質執行取得結果並顯示結果：**
透過 AWS Glue Data Quality `runID`，您可以擷取 `resultID` 以取得實際結果，如下所示：
```
response = client.get_data_quality_ruleset_evaluation_run(
RunId='dqrun-abca77ee126abe1378c1da1ae0750d7dxxxx'
)
resultID = response['ResultIds'][0]
response = client.get_data_quality_result(
ResultId=resultID
)
print(resp['RuleResults'])
```
# 設定提醒、部署和排程
本主題說明如何設定 Glue Data Quality AWS 的提醒、部署和排程。
**Contents**
+ [在 Amazon EventBridge 整合中設定提醒和通知](#data-quality-alerts-eventbridge)
+ [事件模式的其他組態選項](#data-quality-alerts-eventbridge-config-options)
+ [將通知格式化為電子郵件](#data-quality-alerts-eventbridge-format-notifications)
+ [在 CloudWatch 整合中設定提醒和通知](#data-quality-alerts-cloudwatch)
+ [查詢資料品質結果以建置儀表板](#data-quality-alerts-querying-results)
+ [使用 AWS CloudFormation 部署資料品質規則](#data-quality-deploy-cfn)
+ [排程資料品質規則](#data-quality-scheduling-rules)
## 在 Amazon EventBridge 整合中設定提醒和通知
AWS Glue Data Quality 支援發佈 EventBridge 事件，這些事件會在 Data Quality 規則集評估執行完成後發出。如此您就可以輕鬆設定資料品質規則失敗時的提醒。
以下是在資料目錄中評估資料品質規則集時的範例事件。有了這些資訊，您就可以檢閱透過 Amazon EventBridge 提供的資料。您可以發出其他 API 呼叫以取得更多詳細資訊。例如，使用結果 ID 呼叫 `get_data_quality_result` API，以取得特定執行的詳細資訊。
```
{
"version":"0",
"id":"abcdef00-1234-5678-9abc-def012345678",
"detail-type":"Data Quality Evaluation Results Available",
"source":"aws.glue-dataquality",
"account":"123456789012",
"time":"2017-09-07T18:57:21Z",
"region":"us-west-2",
"resources":[],
"detail":{
"context": {
"contextType": "GLUE_DATA_CATALOG",
"runId":"dqrun-12334567890",
"databaseName": "db-123",
"tableName": "table-123",
"catalogId": "123456789012"
},
"resultID": "dqresult-12334567890",
"rulesetNames": ["rulset1"],
"state":"SUCCEEDED",
"score": 1.00,
"rulesSucceeded": 100,
"rulesFailed": 0,
"rulesSkipped": 0
}
}
```
以下是當您在 Glue ETL 或 AWS Glue Studio AWS 筆記本中評估資料品質規則集時發佈的範例事件。
```
{
"version":"0",
"id":"abcdef00-1234-5678-9abc-def012345678",
"detail-type":"Data Quality Evaluation Results Available",
"source":"aws.glue-dataquality",
"account":"123456789012",
"time":"2017-09-07T18:57:21Z",
"region":"us-west-2",
"resources":[],
"detail":{
"context": {
"contextType": "GLUE_JOB",
"jobId": "jr-12334567890",
"jobName": "dq-eval-job-1234",
"evaluationContext": "",
}
"resultID": "dqresult-12334567890",
"rulesetNames": ["rulset1"],
"state":"SUCCEEDED",
"score": 1.00
"rulesSucceeded": 100,
"rulesFailed": 0,
"rulesSkipped": 0
}
}
```
若要在 Data Catalog 和 ETL 任務中同時執行資料品質評估，**將指標發布至 Amazon CloudWatch** 選項 (預設已選取) 必須保持選取狀態，EventBridge 發布才能運作。
**設定 EventBridge 通知**
![\[AWS CloudFormation 中的資料品質屬性\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/data-quality-properties-cfn.png)
若要接收發出的事件並定義目標，您必須設定 Amazon EventBridge 規則。若要建立規則：
1. 開啟 Amazon EventBridge 主控台。
1. 在導覽列的**匯流排**區段下選擇**規則**。
1. 選擇 **Create Rule** (建立規則)。
1. 在**定義規則詳細資訊**上：
1. 對於名稱，輸入 `myDQRule`。
1. 輸入描述 (選用)。
1. 對於事件匯流排，請選取您的事件匯流排。如果沒有事件匯流排，請保留其預設值。
1. 對於規則類型，選取**具有事件模式的規則**，然後選擇**下一步**。
1. 在**建置事件模式**上：
1. 對於事件來源，選取 **AWS 事件或 EventBridge 合作夥伴事件**。
1. 略過示範事件區段。
1. 對於建立方法，選取**使用模式表單**。
1. 對於事件模式：
1. 選取事件來源的 **AWS 服務**。
1. 選取 AWS 服務的 **Glue Data Quality**。
1. 對於事件類型，選取**可用的資料品質評估結果**。
1. 對於特定狀態，選取**失敗**。然後您會看到類似以下內容的事件模式：
```
{
"source": ["aws.glue-dataquality"],
"detail-type": ["Data Quality Evaluation Results Available"],
"detail": {
"state": ["FAILED"]
}
}
```
1. 如需更多設定選項，請參閱 [事件模式的其他組態選項](#data-quality-alerts-eventbridge-config-options)。
1. 在**選取目標**上：
1. 對於**目標類型**，選取 **AWS 服務**。
1. 使用**選取目標**下拉式清單，選擇要連線的所需 AWS 服務 (SNS、Lambda、SQS 等），然後選擇**下一步**。
1. 在**設定標籤**上按一下**新增標籤**以新增選用標籤，然後選擇**下一步**。
1. 您會看到所有選取項目的摘要頁面。選擇底部的**建立規則**。
### 事件模式的其他組態選項
除了根據成功或失敗篩選事件之外，您可能還想要根據不同參數進一步篩選事件。
若要這麼做，請前往「事件模式」區段，然後選取**編輯模式**以指定其他參數。請注意，事件模式中的欄位需區分大小寫。以下是設定事件模式的範例。
若要從評估特定規則集的特定資料表擷取事件，請使用此類型的模式：
```
{
"source": ["aws.glue-dataquality"],
"detail-type": ["Data Quality Evaluation Results Available"],
"detail": {
"context": {
"contextType": ["GLUE_DATA_CATALOG"],
"databaseName": "db-123",
"tableName": "table-123",
},
"rulesetNames": ["ruleset1", "ruleset2"]
"state": ["FAILED"]
}
}
```
若要從 ETL 體驗中的特定任務擷取事件，請使用此類型的模式：
```
{
"source": ["aws.glue-dataquality"],
"detail-type": ["Data Quality Evaluation Results Available"],
"detail": {
"context": {
"contextType": ["GLUE_JOB"],
"jobName": ["dq_evaluation_job1", "dq_evaluation_job2"]
},
"state": ["FAILED"]
}
}
```
若要擷取分數低於特定閾值 (例如 70%) 的事件：
```
{
"source": ["aws.glue-dataquality"],
"detail-type": ["Data Quality Evaluation Results Available"],
"detail": {
"score": [{
"numeric": ["<=", 0.7]
}]
}
}
```
### 將通知格式化為電子郵件
您有時需要向業務團隊傳送格式良好的電子郵件通知。您可以使用 Amazon EventBridge 和 AWS Lambda 來達成此目標。
![\[格式化為電子郵件的資料品質通知\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/data_quality_sample_email.png)
下列範例程式碼可用來格式化資料品質通知以產生電子郵件。
```
import boto3
import json
from datetime import datetime
sns_client = boto3.client('sns')
glue_client = boto3.client('glue')
sns_topic_arn = 'arn:aws:sns:::'
def lambda_handler(event, context):
log_metadata = {}
message_text = ""
subject_text = ""
if event['detail']['context']['contextType'] == 'GLUE_DATA_CATALOG':
log_metadata['ruleset_name'] = str(event['detail']['rulesetNames'][0])
log_metadata['tableName'] = str(event['detail']['context']['tableName'])
log_metadata['databaseName'] = str(event['detail']['context']['databaseName'])
log_metadata['runId'] = str(event['detail']['context']['runId'])
log_metadata['resultId'] = str(event['detail']['resultId'])
log_metadata['state'] = str(event['detail']['state'])
log_metadata['score'] = str(event['detail']['score'])
log_metadata['numRulesSucceeded'] = str(event['detail']['numRulesSucceeded'])
log_metadata['numRulesFailed'] = str(event['detail']['numRulesFailed'])
log_metadata['numRulesSkipped'] = str(event['detail']['numRulesSkipped'])
message_text += "Glue Data Quality run details:\n"
message_text += "ruleset_name: {}\n".format(log_metadata['ruleset_name'])
message_text += "glue_table_name: {}\n".format(log_metadata['tableName'])
message_text += "glue_database_name: {}\n".format(log_metadata['databaseName'])
message_text += "run_id: {}\n".format(log_metadata['runId'])
message_text += "result_id: {}\n".format(log_metadata['resultId'])
message_text += "state: {}\n".format(log_metadata['state'])
message_text += "score: {}\n".format(log_metadata['score'])
message_text += "numRulesSucceeded: {}\n".format(log_metadata['numRulesSucceeded'])
message_text += "numRulesFailed: {}\n".format(log_metadata['numRulesFailed'])
message_text += "numRulesSkipped: {}\n".format(log_metadata['numRulesSkipped'])
subject_text = "Glue Data Quality ruleset {} run details".format(log_metadata['ruleset_name'])
else:
log_metadata['ruleset_name'] = str(event['detail']['rulesetNames'][0])
log_metadata['jobName'] = str(event['detail']['context']['jobName'])
log_metadata['jobId'] = str(event['detail']['context']['jobId'])
log_metadata['resultId'] = str(event['detail']['resultId'])
log_metadata['state'] = str(event['detail']['state'])
log_metadata['score'] = str(event['detail']['score'])
log_metadata['numRulesSucceeded'] = str(event['detail']['numRulesSucceeded'])
log_metadata['numRulesFailed'] = str(event['detail']['numRulesFailed'])
log_metadata['numRulesSkipped'] = str(event['detail']['numRulesSkipped'])
message_text += "Glue Data Quality run details:\n"
message_text += "ruleset_name: {}\n".format(log_metadata['ruleset_name'])
message_text += "glue_job_name: {}\n".format(log_metadata['jobName'])
message_text += "job_id: {}\n".format(log_metadata['jobId'])
message_text += "result_id: {}\n".format(log_metadata['resultId'])
message_text += "state: {}\n".format(log_metadata['state'])
message_text += "score: {}\n".format(log_metadata['score'])
message_text += "numRulesSucceeded: {}\n".format(log_metadata['numRulesSucceeded'])
message_text += "numRulesFailed: {}\n".format(log_metadata['numRulesFailed'])
message_text += "numRulesSkipped: {}\n".format(log_metadata['numRulesSkipped'])
subject_text = "Glue Data Quality ruleset {} run details".format(log_metadata['ruleset_name'])
resultID = str(event['detail']['resultId'])
response = glue_client.get_data_quality_result(ResultId=resultID)
RuleResults = response['RuleResults']
message_text += "\n\nruleset details evaluation steps results:\n\n"
subresult_info = []
for dic in RuleResults:
subresult = "Name: {}\t\tResult: {}\t\tDescription: \t{}".format(dic['Name'], dic['Result'], dic['Description'])
if 'EvaluationMessage' in dic:
subresult += "\t\tEvaluationMessage: {}".format(dic['EvaluationMessage'])
subresult_info.append({
'Name': dic['Name'],
'Result': dic['Result'],
'Description': dic['Description'],
'EvaluationMessage': dic.get('EvaluationMessage', '')
})
message_text += "\n" + subresult
log_metadata['resultrun'] = subresult_info
sns_client.publish(
TopicArn=sns_topic_arn,
Message=message_text,
Subject=subject_text
)
return {
'statusCode': 200,
'body': json.dumps('Message published to SNS topic')
}
```
## 在 CloudWatch 整合中設定提醒和通知
我們建議使用 Amazon EventBridge 設定資料品質提醒，因為 Amazon EventBridge 需要一次性設定來提醒客戶。但是，某些客戶偏好 Amazon CloudWatch，因為他們更熟悉此服務。對於這類客戶，我們提供與 Amazon CloudWatch 的整合。
每個 AWS Glue Data Quality 評估都會針對每個資料品質執行發出一對名為 `glue.data.quality.rules.passed`（表示通過的規則數） 和 `glue.data.quality.rules.failed`（表示失敗的規則數） 的指標。您可以使用發出的此指標來建立警示，以在指定的資料品質執行低於閾值時提醒使用者。若要開始設定將透過 Amazon SNS 通知傳送電子郵件的警示，請依照以下步驟操作：
若要開始設定將透過 Amazon SNS 通知傳送電子郵件的警示，請依照以下步驟操作：
1. 開啟 Amazon CloudWatch 主控台。
1. 選擇**指標**下的**所有指標**。您將在標題為 "Glue Data Quality" 的自訂命名空間下看到額外的命名空間。
**注意**
啟動 AWS Glue Data Quality 執行時，請確定已啟用**發佈指標至 Amazon CloudWatch** 核取方塊。否則，該特定執行的指標將不會發布至 Amazon CloudWatch。
在 `Glue Data Quality` 命名空間下，您可以看到每個資料表中依規則集發出的指標。本主題的目的在於，如果此值超過 1 (表示如果我們看到失敗規則評估的數量大於 1，我們希望收到通知)，我們將使用 `glue.data.quality.rules.failed` 規則和警示。
1. 若要建立警示，請選擇**警示**下的**所有警示**。
1. 選擇 **Create alarm** (建立警示)。
1. 選擇 **Select metric** (選取指標)。
1. 選取與您建立之資料表對應的 `glue.data.quality.rules.failed` 指標，然後選擇**選取指標**。
1. 在**指標**區段下的**指定指標和條件**索引標籤下：
1. 在 **Statistic (統計資料)** 中選擇 **Sum (總和)**。
1. 對於**期間**，選擇 **1 分鐘**。
1. 在**條件**區段下：
1. 對於**閾值類型**，選擇**靜態**。
1. 對於**每當 glue.data.quality.rules.failed 為…**，選取**大於/等於**。
1. 對於**比…**，輸入 **1** 作為閾值。
這些選擇意味著，如果 `glue.data.quality.rules.failed` 指標發出的值大於或等於 1，我們將觸發警示。但是，如果沒有資料，我們會將其視為可接受。
1. 選擇**下一步**。
1. 在**設定動作**上：
1. 對於**警示狀態觸發**區段，選擇**警示中**。
1. 對於**將通知傳送至下列 SNS 主題**區段，選擇**建立新主題以透過新的 SNS 主題傳送通知**。
1. 對於**將接收通知的電子郵件端點**，輸入電子郵件地址。然後按一下**建立主題**。
1. 選擇**下一步**。
1. 對於**警示名稱**，輸入 `myFirstDQAlarm`，然後選擇**下一步**。
1. 您會看到所有選取項目的摘要頁面。選擇底部的**建立警示**。
您現在可以從 Amazon CloudWatch 警示儀表板看到正在建立的警示。
## 查詢資料品質結果以建置儀表板
您可能想要建置儀表板以顯示資料品質結果。有兩種方式可以進行：
**使用下列程式碼設定 Amazon EventBridge，以將資料寫入 Amazon S3：**
```
import boto3
import json
from datetime import datetime
s3_client = boto3.client('s3')
glue_client = boto3.client('glue')
s3_bucket = 's3-bucket-name'
def write_logs(log_metadata):
try:
filename = datetime.now().strftime("%m%d%Y%H%M%S") + ".json"
key_opts = {
'year': datetime.now().year,
'month': "{:02d}".format(datetime.now().month),
'day': "{:02d}".format(datetime.now().day),
'filename': filename
}
s3key = "gluedataqualitylogs/year={year}/month={month}/day={day}/{filename}".format(**key_opts)
s3_client.put_object(Bucket=s3_bucket, Key=s3key, Body=json.dumps(log_metadata))
except Exception as e:
print(f'Error writing logs to S3: {e}')
def lambda_handler(event, context):
log_metadata = {}
message_text = ""
subject_text = ""
if event['detail']['context']['contextType'] == 'GLUE_DATA_CATALOG':
log_metadata['ruleset_name'] = str(event['detail']['rulesetNames'][0])
log_metadata['tableName'] = str(event['detail']['context']['tableName'])
log_metadata['databaseName'] = str(event['detail']['context']['databaseName'])
log_metadata['runId'] = str(event['detail']['context']['runId'])
log_metadata['resultId'] = str(event['detail']['resultId'])
log_metadata['state'] = str(event['detail']['state'])
log_metadata['score'] = str(event['detail']['score'])
log_metadata['numRulesSucceeded'] = str(event['detail']['numRulesSucceeded'])
log_metadata['numRulesFailed'] = str(event['detail']['numRulesFailed'])
log_metadata['numRulesSkipped'] = str(event['detail']['numRulesSkipped'])
message_text += "Glue Data Quality run details:\n"
message_text += "ruleset_name: {}\n".format(log_metadata['ruleset_name'])
message_text += "glue_table_name: {}\n".format(log_metadata['tableName'])
message_text += "glue_database_name: {}\n".format(log_metadata['databaseName'])
message_text += "run_id: {}\n".format(log_metadata['runId'])
message_text += "result_id: {}\n".format(log_metadata['resultId'])
message_text += "state: {}\n".format(log_metadata['state'])
message_text += "score: {}\n".format(log_metadata['score'])
message_text += "numRulesSucceeded: {}\n".format(log_metadata['numRulesSucceeded'])
message_text += "numRulesFailed: {}\n".format(log_metadata['numRulesFailed'])
message_text += "numRulesSkipped: {}\n".format(log_metadata['numRulesSkipped'])
subject_text = "Glue Data Quality ruleset {} run details".format(log_metadata['ruleset_name'])
else:
log_metadata['ruleset_name'] = str(event['detail']['rulesetNames'][0])
log_metadata['jobName'] = str(event['detail']['context']['jobName'])
log_metadata['jobId'] = str(event['detail']['context']['jobId'])
log_metadata['resultId'] = str(event['detail']['resultId'])
log_metadata['state'] = str(event['detail']['state'])
log_metadata['score'] = str(event['detail']['score'])
log_metadata['numRulesSucceeded'] = str(event['detail']['numRulesSucceeded'])
log_metadata['numRulesFailed'] = str(event['detail']['numRulesFailed'])
log_metadata['numRulesSkipped'] = str(event['detail']['numRulesSkipped'])
message_text += "Glue Data Quality run details:\n"
message_text += "ruleset_name: {}\n".format(log_metadata['ruleset_name'])
message_text += "glue_job_name: {}\n".format(log_metadata['jobName'])
message_text += "job_id: {}\n".format(log_metadata['jobId'])
message_text += "result_id: {}\n".format(log_metadata['resultId'])
message_text += "state: {}\n".format(log_metadata['state'])
message_text += "score: {}\n".format(log_metadata['score'])
message_text += "numRulesSucceeded: {}\n".format(log_metadata['numRulesSucceeded'])
message_text += "numRulesFailed: {}\n".format(log_metadata['numRulesFailed'])
message_text += "numRulesSkipped: {}\n".format(log_metadata['numRulesSkipped'])
subject_text = "Glue Data Quality ruleset {} run details".format(log_metadata['ruleset_name'])
resultID = str(event['detail']['resultId'])
response = glue_client.get_data_quality_result(ResultId=resultID)
RuleResults = response['RuleResults']
message_text += "\n\nruleset details evaluation steps results:\n\n"
subresult_info = []
for dic in RuleResults:
subresult = "Name: {}\t\tResult: {}\t\tDescription: \t{}".format(dic['Name'], dic['Result'], dic['Description'])
if 'EvaluationMessage' in dic:
subresult += "\t\tEvaluationMessage: {}".format(dic['EvaluationMessage'])
subresult_info.append({
'Name': dic['Name'],
'Result': dic['Result'],
'Description': dic['Description'],
'EvaluationMessage': dic.get('EvaluationMessage', '')
})
message_text += "\n" + subresult
log_metadata['resultrun'] = subresult_info
write_logs(log_metadata)
return {
'statusCode': 200,
'body': json.dumps('Message published to SNS topic')
}
```
寫入 Amazon S3 之後，您可以使用 AWS Glue 爬蟲程式向 Athena 註冊並查詢資料表。
**在資料品質評估期間設定 Amazon S3 位置：**
在 AWS Glue Data Catalog 或 Glue ETL AWS 中執行資料品質任務時，您可以提供 Amazon S3 位置，將資料品質結果寫入 Amazon S3。您可以使用以下語法，透過參考目標以讀取資料品質結果來建立資料表。
請注意，您必須分別執行 `CREATE EXTERNAL TABLE` 和 `MSCK REPAIR TABLE` 查詢。
```
CREATE EXTERNAL TABLE (
catalogid string,
databasename string,
tablename string,
dqrunid string,
evaluationstartedon timestamp,
evaluationcompletedon timestamp,
rule string,
outcome string,
failurereason string,
evaluatedmetrics string)
PARTITIONED BY (
`year` string,
`month` string,
`day` string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'paths'='catalogId,databaseName,dqRunId,evaluatedMetrics,evaluationCompletedOn,evaluationStartedOn,failureReason,outcome,rule,tableName')
STORED AS INPUTFORMAT 'org.apache.hadoop.mapred.TextInputFormat'
OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat'
LOCATION 's3://glue-s3-dq-bucket-us-east-2-results/'
TBLPROPERTIES (
'classification'='json',
'compressionType'='none',
'typeOfData'='file');
```
```
MSCK REPAIR TABLE ;
```
建立上述資料表後，您便可以使用 Amazon Athena 執行分析查詢。
## 使用 AWS CloudFormation 部署資料品質規則
您可以使用 AWS CloudFormation 來建立資料品質規則。如需詳細資訊，請參閱 [AWS CloudFormation for AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/populate-with-cloudformation-templates.html)。
## 排程資料品質規則
您可以使用下列方法排程資料品質規則：
+ 從 Data Catalog 排程資料品質規則：沒有程式碼使用者可以使用此選項來輕鬆排程其資料品質掃描。 AWS Glue Data Quality 將在 Amazon EventBridge 中建立排程。若要排程資料品質規則：
+ 導覽至規則集，然後按一下**執行**。
+ 在**執行頻率**中，選取所需排程並提供**任務名稱**。此任務名稱是 EventBridge 中的排程名稱。
+ 使用 Amazon EventBridge 和 AWS Step Functions 協調資料品質規則的評估和建議。
# Glue Data Quality AWS 的靜態資料加密
AWS Glue Data Quality 預設提供加密，以使用 AWS 擁有的加密金鑰保護靜態敏感客戶資料。
## AWS 擁有的金鑰
AWS Glue Data Quality 使用這些金鑰自動加密客戶的 Data Quality 資產。您無法檢視、管理或使用 AWS 擁有的金鑰，或稽核其使用方式。但是，您不需要採取任何動作或變更任何程式，即可保護加密您資料的金鑰。如需詳細資訊，請參閱《 AWS KMS 開發人員指南》中的[AWS 擁有的金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk)。
依預設加密靜態資料，有助於降低保護敏感資料所涉及的營運開銷和複雜性。同時，其可讓您建置符合嚴格加密合規性和法規要求的安全應用程式。
雖然您無法停用此層加密或選取替代加密類型，但您可以在建立 Data Quality 資源時選擇客戶受管金鑰，在現有 AWS 擁有的加密金鑰上新增第二層加密。
## 客戶自管金鑰
**客戶受管金鑰**： AWS Glue Data Quality 支援使用您建立、擁有和管理的對稱客戶受管金鑰。這會在現有 AWS 擁有的加密上新增第二層加密。由於您可以完全控制此層加密，因此能執行以下任務：
+ 建立和維護金鑰政策
+ 建立和維護 IAM 政策
+ 啟用和停用金鑰政策
+ 輪換金鑰密碼編譯資料
+ 新增 標籤
+ 建立金鑰別名
+ 安排金鑰供刪除
如需詳細資訊，請參閱《 AWS KMS 開發人員指南》中的[客戶受管金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk)。
下表摘要說明 AWS Glue Data Quality 如何加密不同的 Data Quality 資產。
| 資料類型 | AWS 擁有的金鑰加密 | 客戶自管金鑰加密 |
| --- | --- | --- |
| **資料品質規則集** 持續 DQ 規則集所參考的 DQDL 規則集字串。這些持久規則集目前僅用於 AWS Glue Data Catalog 體驗。 | 已啟用 | 已啟用 |
| **Data Quality 規則/分析器結果** 結果成品，其中包含規則集中每個規則的通過/失敗狀態，以及規則和分析器收集的指標。 | 已啟用 | 已啟用 |
| **觀察** 在資料中偵測到異常時，會產生觀察結果。其包含預期上限和下限的資訊，以及基於這些邊界的建議規則。如果產生，其會與 Data Quality 結果一起顯示。 | 已啟用 | 已啟用 |
| **統計資料** 包含評估指定規則集的資料後所收集指標的資訊，例如指標的值 (例如 RowCount、Completeness)、資料欄名稱和其他中繼資料。 | 已啟用 | 已啟用 |
| **異常偵測統計模型** 統計資料模型包含根據先前客戶資料評估所產生指定指標的上限和下限的時間序列。 | 已啟用 | 已啟用 |
**注意**
AWS Data Quality 使用 AWS 擁有的金鑰自動啟用靜態加密，免費保護個人身分識別資料。不過，使用客戶受管金鑰會產生 AWS KMS 費用。如需定價的詳細資訊，請參閱[AWS KMS 定價](https://aws.amazon.com/kms/pricing/)。
如需 的詳細資訊 AWS KMS，請參閱 [AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)。
## 建立客戶自管金鑰
您可以使用 AWS 管理主控台或 AWS KMS APIs 來建立對稱客戶受管金鑰。
**若要建立對稱客戶自管金鑰，請執行以下操作：**
+ 請遵循《 AWS Key Management Service 開發人員指南》中[建立對稱加密 AWS KMS 金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk)的步驟。
### 金鑰政策
金鑰政策會控制客戶受管金鑰的存取權限。每個客戶受管金鑰都必須只有一個金鑰政策，其中包含決定誰可以使用金鑰及其使用方式的陳述式。在建立客戶受管金鑰時，可以指定金鑰政策。如需詳細資訊，請參閱《 AWS Key Management Service 開發人員指南[》中的金鑰中的 AWS KMS 金鑰政策](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)。
若要將客戶自管金鑰與 Data Quality 資源搭配使用，必須在金鑰政策中允許下列 API 操作：
+ [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) – 使用 解密 AWS KMS 金鑰加密的加密文字 `GenerateDataKeyWithoutPlaintext`
+ [https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) – 提供客戶自管金鑰詳細資訊，以讓 Amazon Location 驗證金鑰。
+ [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) – 傳回可在 外部使用的唯一對稱資料金鑰 AWS KMS。此操作會傳回根據您指定的對稱加密 KMS 金鑰加密的資料金鑰。金鑰中的位元組是隨機的；其與發起人或 KMS 金鑰無關。用於減少客戶必須進行的 KMS 呼叫。
+ [https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) – 解密密文，然後完全在 AWS KMS內重新加密。您可以使用此操作來變更加密資料的 KMS 金鑰，例如當您[手動輪換](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotate-keys-manually) KMS 金鑰或變更保護密文的 KMS 金鑰時。您也可以使用其在相同的 KMS 金鑰下重新加密密文，例如變更密文的[加密內容](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context)。
以下是您可以為 Amazon Location 新增的政策聲明範例：
```
"Statement" : [
{
"Sid" : "Allow access to principals authorized to use AWS Glue Data Quality",
"Effect" : "Allow",
"Principal" : {
"AWS": "arn:aws:iam:::role/ExampleRole"
},
"Action" : [
"kms:Decrypt",
"kms:DescribeKey",
"kms:GenerateDataKeyWithoutPlaintext",
"kms:ReEncrypt*"
],
"Resource" : "*",
"Condition" : {
"StringEquals" : {
"kms:ViaService" : "glue.amazonaws.com",
"kms:CallerAccount" : "111122223333"
}
},
{
"Sid": "Allow access for key administrators",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
},
"Action" : [
"kms:*"
],
"Resource": "arn:aws:kms:region:111122223333:key/key_ID"
},
{
"Sid" : "Allow read-only access to key metadata to the account",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:root"
},
"Action" : [
"kms:Describe*",
"kms:Get*",
"kms:List*",
],
"Resource" : "*"
}
]
```
### 在 Glue Data Quality 中使用 KMS AWS 金鑰的注意事項
AWS Glue Data Quality 不支援金鑰轉換。這表示如果您使用金鑰 A 加密 Data Quality 資產，並決定切換到金鑰 B，我們不會重新加密使用金鑰 A 加密的資料，以使用金鑰 B。您仍然可以切換到金鑰 B，但需要維護金鑰 A 的存取權，以存取先前使用金鑰 A 加密的資料。
如需在政策中指定許可的詳細資訊，請參閱《 AWS Key Management Service 開發人員指南》[中的金鑰政策中的 AWS 服務許可](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-services.html)。
如需對金鑰存取進行疑難排解的詳細資訊，請參閱《 AWS Key Management Service 開發人員指南》中的[對金鑰存取進行疑難排解](https://docs.aws.amazon.com/kms/latest/developerguide/policy-evaluation.html)。
## 建立安全組態
在 AWS Glue 中，[安全組態資源](encryption-security-configuration.md)包含寫入加密資料時所需的屬性。
**若要加密資料品質資產，請執行以下操作：**
1. 在**加密設定**中，於**進階設定**下，選擇**啟用 Data Quality 加密**
1. 選取您的 KMS 金鑰或選擇**建立 AWS KMS 金鑰**
![\[螢幕擷取畫面會顯示「新增安全性組態」頁面。已選取「啟用 Data Quality 加密」選項。\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/data-quality-add-security-configuration.png)
## AWS Glue Data Quality 加密內容
[加密內容](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context)是一組選用的金鑰值對，包含資料的其他相關內容資訊。
AWS KMS 使用加密內容做為[額外的已驗證資料](https://docs.aws.amazon.com/crypto/latest/userguide/cryptography-concepts.html#term-aad)，以支援已[驗證的加密。 ](https://docs.aws.amazon.com/crypto/latest/userguide/cryptography-concepts.html#term-aad)當您在加密資料的請求中包含加密內容時， 會將加密內容 AWS KMS 繫結至加密的資料。若要解密資料，您必須在請求中包含相同的加密內容。
### AWS Glue Data Quality 加密內容範例
```
"encryptionContext": {
"kms-arn": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"branch-key-id": "111122223333+arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"hierarchy-version": "1",
"aws-crypto-ec:aws:glue:securityConfiguration": "111122223333:customer-security-configuration-name",
"create-time": "2024-06-07T13:47:23:000861Z",
"tablename": "AwsGlueMlEncryptionKeyStore",
"type": "beacon:ACTIVE"
}
```
### 使用加密內容進行監控
當您使用對稱客戶自管金鑰加密追蹤器或地理柵欄集合時，您也可以在稽核記錄和日誌中使用加密內容，以識別客戶自管金鑰的使用方式。加密內容也會出現在 AWS CloudTrail 或 產生的日誌中 Amazon CloudWatch Logs。
## 監控 Glue Data Quality AWS 的加密金鑰
當您搭配 Glue Data Quality 資源使用 AWS KMS 客戶受管金鑰時，您可以使用 AWS AWS CloudTrail 或 Amazon CloudWatch Logs 來追蹤 AWS Glue Data Quality 傳送給 的請求 AWS KMS。
下列範例是 `GenerateDataKeyWithoutPlainText`和 AWS CloudTrail 的事件`Decrypt`，用於監控 Glue Data Quality AWS 呼叫的 KMS 操作，以存取客戶受管金鑰加密的資料。
**解密**
```
{
"eventVersion": "1.09",
"userIdentity": {
"type": "AssumedRole",
"arn": "arn:aws:sts::111122223333:role/CustomerRole",
"accountId": "111122223333",
"invokedBy": "glue.amazonaws.com"
},
"eventTime": "2024-07-02T20:03:10Z",
"eventSource": "kms.amazonaws.com",
"eventName": "Decrypt",
"awsRegion": "us-east-1",
"sourceIPAddress": "glue.amazonaws.com",
"userAgent": "glue.amazonaws.com",
"requestParameters": {
"keyId": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"encryptionAlgorithm": "SYMMETRIC_DEFAULT",
"encryptionContext": {
"kms-arn": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"branch-key-id": "111122223333+arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"hierarchy-version": "1",
"aws-crypto-ec:aws:glue:securityConfiguration": "111122223333:customer-security-configuration-name",
"create-time": "2024-06-07T13:47:23:000861Z",
"tablename": "AwsGlueMlEncryptionKeyStore",
"type": "branch:ACTIVE",
"version": "branch:version:ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE"
}
},
"responseElements": null,
"requestID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"eventID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"readOnly": true,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "111122223333",
"eventCategory": "Management"
}
```
**GenerateDataKeyWithoutPlaintext**
```
{
"eventVersion": "1.09",
"userIdentity": {
"type": "AssumedRole",
"arn": "arn:aws:sts::111122223333:role/CustomerRole",
"accountId": "111122223333",
"invokedBy": "glue.amazonaws.com"
},
"eventTime": "2024-07-02T20:03:10Z",
"eventSource": "kms.amazonaws.com",
"eventName": "GenerateDataKeyWithoutPlaintext",
"awsRegion": "us-east-1",
"sourceIPAddress": "glue.amazonaws.com",
"userAgent": "glue.amazonaws.com",
"requestParameters": {
"keyId": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"encryptionAlgorithm": "SYMMETRIC_DEFAULT",
"encryptionContext": {
"kms-arn": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"branch-key-id": "111122223333+arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"hierarchy-version": "1",
"aws-crypto-ec:aws:glue:securityConfiguration": "111122223333:customer-security-configuration-name",
"create-time": "2024-06-07T13:47:23:000861Z",
"tablename": "AwsGlueMlEncryptionKeyStore",
"type": "branch:version:ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE"
}
},
"responseElements": null,
"requestID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"eventID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"readOnly": true,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "111122223333",
"eventCategory": "Management"
}
```
**ReEncyrpt**
```
{
"eventVersion": "1.09",
"userIdentity": {
"type": "AssumedRole",
"arn": "arn:aws:sts::111122223333:role/CustomerRole",
"accountId": "111122223333",
"invokedBy": "glue.amazonaws.com"
},
"eventTime": "2024-07-17T21:34:41Z",
"eventSource": "kms.amazonaws.com",
"eventName": "ReEncrypt",
"awsRegion": "us-east-1",
"sourceIPAddress": "glue.amazonaws.com",
"userAgent": "glue.amazonaws.com",
"requestParameters": {
"destinationEncryptionContext": {
"kms-arn": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"branch-key-id": "111122223333+arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"hierarchy-version": "1",
"aws-crypto-ec:aws:glue:securityConfiguration": "111122223333:customer-security-configuration-name",
"create-time": "2024-06-07T13:47:23:000861Z",
"tablename": "AwsGlueMlEncryptionKeyStore",
"type": "branch:ACTIVE"
"version": "branch:version:12345678-SAMPLE"
},
"destinationKeyId": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"sourceAAD": "1234567890-SAMPLE+Z+lqoYOHj7VtWxJLrvh+biUFbliYDAQkobM=",
"sourceKeyId": "arn:aws:kms:ap-southeast-2:585824196334:key/17ca05ca-a8c1-40d7-b7fd-30abb569a53a",
"destinationEncryptionAlgorithm": "SYMMETRIC_DEFAULT",
"sourceEncryptionContext": {
"kms-arn": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"branch-key-id": "111122223333+arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE",
"hierarchy-version": "1",
"aws-crypto-ec:aws:glue:securityConfiguration": "111122223333:customer-security-configuration-name",
"create-time": "2024-06-07T13:47:23:000861Z",
"tablename": "AwsGlueMlEncryptionKeyStore",
"type": "branch:version:ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE"
},
"destinationAAD": "1234567890-SAMPLE",
"sourceEncryptionAlgorithm": "SYMMETRIC_DEFAULT"
},
"responseElements": null,
"requestID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"eventID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE",
"readOnly": true,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE"
},
{
"accountId": "111122223333",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "111122223333",
"eventCategory": "Management"
}
```
## 進一步了解
下列資源會提供有關靜態資料加密的詳細資訊。
+ 如需[AWS Key Management Service 基本概念](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html)的詳細資訊，請參閱 AWS Key Management Service 開發人員指南。
+ 如需 [安全最佳實務的詳細資訊， AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/best-practices.html)請參閱 AWS Key Management Service 開發人員指南。
# 對 AWS Glue Data Quality 錯誤進行故障診斷
如果您在 AWS Glue Data Quality 中遇到錯誤，請使用下列解決方案來協助您尋找問題來源並加以修正。
**Contents**
+ [錯誤：缺少 AWS Glue Data Quality 模組](#data-quality-trouble-error-1)
+ [錯誤： AWS Lake Formation 許可不足](#data-quality-trouble-error-2)
+ [錯誤：規則集的命名不是唯一的](#data-quality-trouble-error-3)
+ [錯誤：資料表具有特殊字元](#data-quality-trouble-error-4)
+ [錯誤：大型規則集的溢位錯誤](#data-quality-trouble-error-5)
+ [錯誤：整體規則狀態為失敗](#data-quality-trouble-error-6)
+ [AnalysisException：無法驗證預設資料庫是否存在](#data-quality-trouble-error-7)
+ [錯誤訊息：提供的索引鍵映射不適合指定的資料框架](#data-quality-trouble-error-8)
+ [使用者類別中的例外狀況：java.lang.RuntimeException：無法擷取資料。檢查 CloudWatch 中的日誌以取得更多詳細資訊](#data-quality-trouble-error-9)
+ [啟動錯誤：從 S3 下載儲存貯體時發生錯誤](#data-quality-trouble-error-10)
+ [InvalidInputException (狀態：400)：無法剖析 DataQuality 規則](#data-quality-trouble-error-11)
+ [錯誤：Eventbridge 不會根據我設定的排程觸發 Glue DQ 任務](#data-quality-trouble-error-12)
+ [CustomSQL 錯誤](#data-quality-trouble-error-13)
+ [動態規則](#data-quality-trouble-error-14)
+ [使用者類別中的例外狀況：org.apache.spark.sql.AnalysisException：org.apache.hadoop.hive.ql.metadata.HiveException](#data-quality-trouble-error-15)
+ [UNCLASSIFIED\$1ERROR；IllegalArgumentException：剖析錯誤：未提供規則或分析器。輸入時沒有可行的替代方案](#data-quality-trouble-error-16)
## 錯誤：缺少 AWS Glue Data Quality 模組
**錯誤訊息**：沒有名為 'awsgluedq' 的模組。
**解決方案**：當您在不支援的版本中執行 AWS Glue Data Quality 時，會發生此錯誤。 AWS Glue Data Quality 僅在 Glue 3.0 版和更新版本中受支援。
## 錯誤： AWS Lake Formation 許可不足
**錯誤訊息**：使用者類別中的例外狀況：`com.amazonaws.services.glue.model.AccessDeniedException`：impact\$1sdg\$1involvement 上的 Lake Formation 許可不足 (服務：AWS Glue；狀態碼：400；錯誤代碼：AccessDeniedException；請求 ID：465ae693-b7ba-4df0-a4e4-6b17xxxxxxxx；代理：Null)。
**解決方案**：您必須在 AWS Lake Formation 中提供足夠的許可。
## 錯誤：規則集的命名不是唯一的
**錯誤訊息**：使用者類別中的例外狀況：...services.glue.model.AlreadyExistsException：已存在另一個同名的規則集。
**解決方案**：規則集是全域的並且必須是唯一的。
## 錯誤：資料表具有特殊字元
**錯誤訊息**：使用者類別中的例外狀況：org.apache.spark.sql.AnalysisException：無法解析 ''C'' 指定的輸入資料欄：[primary.data\$1end\$1time, primary.data\$1start\$1time, primary.end\$1time, primary.last\$1updated, primary.message, primary.process\$1date, primary.rowhash, primary.run\$1by, primary.run\$1id, primary.start\$1time, primary.status]；第 1 行位置 44。
**解決方案**： AWS Glue Data Quality 目前受到限制，無法在具有特殊字元的資料表上執行，例如 "."。
## 錯誤：大型規則集的溢位錯誤
**錯誤訊息**：使用者類別中的例外狀況：java.lang.StackOverflowError。
**解決方案**：如果是大於 2K 規則的大型規則集，則可能會遇到此問題。將規則分解為多個規則集。
## 錯誤：整體規則狀態為失敗
**錯誤條件**：我的規則集成功，但我的整體規則狀態失敗。
**解決方案**：此錯誤最有可能的發生原因，是您在發布時選擇了將指標發布至 Amazon Cloudwatch 的選項。如果資料集位於 VPC 中，則 VPC 可能不允許 AWS Glue 將指標發布至 Amazon CloudWatch。在這種情況下，您必須為 VPC 設定端點才能存取 Amazon CloudWatch。
## AnalysisException：無法驗證預設資料庫是否存在
**錯誤條件**：AnalysisException：無法驗證預設資料庫是否存在：com.amazonaws.services.glue.model.AccessDeniedException：預設情況下 Lake Formation 許可不足 (服務：AWS Glue；狀態碼：400；錯誤代碼：AccessDeniedException；請求 ID：XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX；代理：null)
**解決方案**：在 AWS Glue 任務的目錄整合中，AWS Glue 一律會嘗試檢查預設資料庫是否存在或不使用 AWS Glue `GetDatabase API`。如果未授予 `DESCRIBE` Lake Formation 許可或已授予 `GetDatabase IAM` 許可，則在驗證預設資料庫的存在時，該任務會失敗。
若要解決問題：
1. 在 Lake Formation 中新增預設資料庫的 `DESCRIBE` 許可。
1. 將附加至 AWS Glue 任務的 IAM 角色設定為 Lake Formation 中的資料庫建立者。這會自動建立預設資料庫，並授予角色所需的 Lake Formation 許可。
1. 停用 `--enable-data-catalog` 選項。(在 AWS Glue Studio 中顯示為**使用 Data Catalog 作為 Hive 中繼存放區**)。
如果不需要任務中的 Spark SQL Data Catalog 整合，則可以停用此功能。
## 錯誤訊息：提供的索引鍵映射不適合指定的資料框架
**錯誤條件**：提供的索引鍵映射不適合指定的資料框架。
**解決方案**：您正在使用 **DataSetMatch** 規則類型，並且聯結索引鍵有重複項。聯結索引鍵必須是唯一的，且不得為 NULL。如果您無法擁有唯一的聯結索引鍵，請考慮使用其他規則類型 (例如 **AggregateMatch**) 來比對摘要資料。
## 使用者類別中的例外狀況：java.lang.RuntimeException：無法擷取資料。檢查 CloudWatch 中的日誌以取得更多詳細資訊
**錯誤條件**：使用者類別中的例外狀況：java.lang.RuntimeException：無法擷取資料。檢查 CloudWatch 中的日誌以取得更多詳細資訊。
**解決方案**：當您在與 Amazon RDS 或 比較的 Amazon S3 型資料表上建立 DQ 規則時，就會發生這種情況 Amazon Redshift。在這些情況下，AWS Glue 無法載入連線。反之，請嘗試在 Amazon Redshift 或 Amazon RDS 資料集上設定 DQ 規則。這是已知的錯誤。
## 啟動錯誤：從 S3 下載儲存貯體時發生錯誤
**錯誤條件**：啟動錯誤：從 S3 下載儲存貯體時發生錯誤：`aws-glue-ml-data-quality-assets-us-east-1, key: jars/aws-glue-ml-data-quality-etl.jar.Access Denied (Service: Amazon S3; Status Code: 403; Please refer logs for details) `。
**解決方案**：傳遞給 Glue Data Quality AWS 的角色中的許可必須允許從先前的 Amazon S3 位置讀取。此 IAM 政策應附加至該角色：
```
{
"Sid": "allowS3",
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::aws-glue-ml-data-quality-assets-/*"
}
```
如需詳細許可，請參閱 [Data Quality authorization](https://docs.aws.amazon.com/glue/latest/dg/data-quality-authorization.html)。需要這些程式庫來評估資料集的資料品質。
## InvalidInputException (狀態：400)：無法剖析 DataQuality 規則
**錯誤條件**：InvalidInputException (狀態：400)：無法剖析 DataQuality 規則。
**解決方案**：出現這種錯誤的可能性有很多。一種可能性是規則中可能有單引號。確認規則都由雙引號括住。例如：
```
Rules = [
ColumnValues "tipo_vinculo" in ["CODO", "DOCO", "COCO", "DODO"] AND "categoria" = 'ES"
AND "cod_bandera" = 'CEP'
```
將此規則變更為：
```
Rules = [
(ColumnValues "tipovinculo" in [ "CODO", "DOCO", "COCO", "DODO"]) AND (ColumnValues "categoria" = "ES")
AND (ColumnValues "codbandera" = "CEP")
]
```
## 錯誤：Eventbridge 不會根據我設定的排程觸發 Glue DQ 任務
**錯誤條件**：Eventbridge 不會根據我設定的排程觸發 AWS Glue Data Quality 任務。
**解決方案**：觸發任務的角色可能沒有正確的許可。請確定您用來開始作業的角色具有[排程評估執行所需的 IAM 設定](https://docs.aws.amazon.com/glue/latest/dg/data-quality-authorization.html#data-quality-iam-setup-evaluation-runs)中提到的許可。
## CustomSQL 錯誤
**錯誤條件**：` The output from CustomSQL must contain at least one column that matches the input dataset for AWS Glue Data Quality to provide row level results. The SQL query is a valid query but no columns from the SQL result are present in the Input Dataset. Ensure that matching columns are returned from the SQL`。
**解決方案**：SQL 查詢是有效的，但請確認您從主資料表中選取的只有資料欄。選取像 sum 這樣的彙總函數，對主資料表中的資料欄進行計數可能會導致此錯誤。
**錯誤條件**：` There was a problem when executing your SQL statement: cannot resolve "Col"`。
**解決方案**：主資料表中不存在此資料欄。
**錯誤條件**：` The columns that are returned from the SQL statement should only belong to the primary table. "In this case, some columns ( Col ) belong to reference table"`。
**解決方案**：在 SQL 查詢中，當您將主資料表與其他參考資料表結合時，請確認 select 陳述式只有主資料表中的資料欄名稱，以產生主資料表的資料列層級結果。
## 動態規則
**錯誤條件**`: Dynamic rules require job context, and cannot be evaluated in interactive session or data preview.`。
**原因：**當規則集中存在動態 DQ 規則時，此錯誤訊息可能會出現在資料預覽結果或其他互動式工作階段中。動態規則會參考與特定作業名稱和評估內容相關聯的歷史指標，因此無法在互動式工作階段中評估這些指標。
**解決方案**：執行 AWS Glue 作業會產生歷史指標，可在相同作業的後續作業執行中參考這些指標。
**錯誤條件**：
+ ` [RuleType] rule only supports simple atomic operands in thresholds.`.
+ `Function last not yet implemented for [RuleType] rule.`
**解決方案**：數值表達式中所有 DQDL 規則類型通常都支援動態規則 (請參閱 [DQDL 參考](dqdl.md))。但是，尚不支援部分產生多個指標 (ColumnValues 和 ColumnLength) 的規則。
**錯誤條件**：` Binary expression operands must resolve to a single number.`。
**原因**：動態規則支援 `RowCount > avg(last(5)) * 0.9` 之類的二進制表達式。此處的二進制表達式是 `avg(last(5)) * 0.9`。這個規則是有效的，因為 `avg(last(5))` 和 `0.9` 這兩種運算元都會解析為單一數字。`RowCount > last(5) * 0.9` 是錯誤範例，因為 `last(5)` 產生的清單無法與目前資料列計數進行有意義的比較。
**解決方案**：使用彙總函數，將清單值運算元簡化為單一數字。
**錯誤條件**：
+ `Rule threshold results in list, and a single value is expected. Use aggregation functions to produce a single value. Valid example: sum(last(10)), avg(last(10)).`
+ `Rule threshold results in empty list, and a single value is expected.`
**原因**：動態規則可用於比較資料集的某些特性與其歷史值。如果提供正整數引數，則最後一個函數允許擷取多個歷史值。例如，`last(5)` 會擷取在規則作業執行中觀察到的最近五個值。
**解決方案**：必須使用彙總函數將這些值簡化為單一數字，以便與目前作業執行中觀察到的值進行有意義的比較。
有效的範例：
+ `RowCount >= avg(last(5))`
+ `RowCount > last(1)`
+ `RowCount < last()`
無效的範例：`RowCount > last(5)`。
**錯誤條件**：
+ `Function index used in threshold requires positive integer argument.`
+ `Index argument must be an integer. Valid syntax example: RowCount > index(last(10, 2)), which means RowCount must be greater than third most recent execution from last 10 job runs.`
**解決方案**：編寫動態規則時，您可以使用 `index` 彙總函數從清單中選取一個歷史值。例如 `RowCount > index(last(5)` 1) 會檢查目前作業中觀察到的資料列計數是否嚴格大於作業中觀察到的第二個最近的資料列計數。`index` 從零開始索引。
**錯誤條件**：` IllegalArgumentException: Parsing Error: Rule Type: DetectAnomalies is not valid`。
**解決方案**：異常偵測功能僅適用於 AWS Glue 4.0。
**錯誤條件**：` IllegalArgumentException: Parsing Error: Unexpected condition for rule of type ... no viable alternative at input ...`。
注意：`...` 是動態的。範例：`IllegalArgumentException: Parsing Error: Unexpected condition for rule of type RowCount with number return type, line 4:19 no viable alternative at input '>last'`。
**解決方案**：異常偵測功能僅適用於 AWS Glue 4.0。
## 使用者類別中的例外狀況：org.apache.spark.sql.AnalysisException：org.apache.hadoop.hive.ql.metadata.HiveException
**錯誤條件**`: Exception in User Class: org.apache.spark.sql.AnalysisException: org.apache.hadoop.hive.ql.metadata.HiveException: Unable to fetch table mailpiece_submitted. StorageDescriptor#InputFormat cannot be null for table: mailpiece_submitted (Service: null; Status Code: 0; Error Code: null; Request ID: null; Proxy: null)`
**原因：**您在 Glue Data Catalog AWS 中使用 Apache Iceberg，而 AWS Glue Data Catalog 中的輸入格式屬性為空白。
**解決方案**：當您在 DQ 規則中使用 CustomSQL 規則類型時，會發生此問題。修正此問題的一種方法是使用「主要」或將目錄名稱 `glue_catalog.` 新增至 `. in Custom ruletype`。
## UNCLASSIFIED\$1ERROR；IllegalArgumentException：剖析錯誤：未提供規則或分析器。輸入時沒有可行的替代方案
**錯誤條件**`: UNCLASSIFIED_ERROR; IllegalArgumentException: Parsing Error: No rules or analyzers provided., no viable alternative at input`
**解決方案**：DQDL 無法剖析。有幾種情況會導致這種情況發生。如果您使用的是複合規則，請確保其具有正確的括號。
```
(RowCount >= avg(last(10)) * 0.6) and (RowCount <= avg(last(10)) * 1.4) instead of
RowCount >= avg(last(10)) * 0.6 and RowCount <= avg(last(10)) * 1.4
```