airflow.providers.google.cloud.utils.field_validator¶
用於驗證透過 Google Cloud API 傳送的 body 欄位的驗證器。
此驗證器執行 body（欄位字典）的驗證，該 body 通常透過 googleclient API 在 API 請求中傳送至 Google Cloud。
背景¶
此規範主要著重於在開發階段協助 Airflow DAG 開發人員。您可以建立自己的 Google Cloud 操作器（例如 GcfDeployOperator），其中可以針對特定 API 具有內建的驗證規範。當開發人員在 DAG 開發的初始階段嘗試使用不同的欄位及其值時，這非常有用。大多數 Google Cloud API 會在伺服器端執行自己的驗證，但大多數請求是非同步的，您需要等待操作結果。這會花費寶貴的時間並減慢 API 的迭代速度。BodyFieldValidator 旨在在用戶端使用，因此應針對拼字錯誤或錯誤類型的參數向開發人員提供即時回饋。
應在 “execute()” 方法呼叫中執行驗證，以便在執行驗證之前擴展範本參數。
欄位類型¶
規範是字典陣列 - 每個字典描述一個欄位、其類型、驗證、可選性、支援的 api_version 和巢狀欄位（用於聯合和字典）。
通常（為了清晰起見並為了幫助語法高亮顯示），字典陣列應定義為一系列 dict() 執行。範例規範片段可能如下所示
SPECIFICATION =[
dict(name="an_union", type="union", optional=True, fields=[
dict(name="variant_1", type="dict"),
dict(name="variant_2", regexp=r'^.+$', api_version='v1beta2'),
),
dict(name="an_union", type="dict", fields=[
dict(name="field_1", type="dict"),
dict(name="field_2", regexp=r'^.+$'),
),
...
]
每個欄位都應具有 key = “name”，表示欄位名稱。欄位可以是以下類型之一
字典欄位：（key = “type”，value=”dict”）：此類型的欄位應包含巢狀欄位，形式為字典陣列。然後預期陣列中的每個欄位（除非標記為可選）並遞迴驗證。如果字典中存在額外欄位，則會在日誌檔案中列印警告（但驗證成功 - 請參閱向前相容性注意事項）
列表欄位：（key = “type”，value=”list”）：此類型的欄位應為列表。僅驗證類型正確性。列表的內容不受驗證。
聯合欄位（key = “type”，value=”union”）：此類型的欄位應包含巢狀欄位，形式為字典陣列。應存在其中一個欄位（且僅一個）（除非聯合標記為可選）。如果存在多個聯合欄位，則會引發 FieldValidationException。如果沒有聯合欄位存在 - 警告會列印在日誌中（請參閱下面的向前相容性注意事項）。
針對非空驗證的欄位：（key = “allow_empty”） - 這僅適用於值為字串的欄位，並且允許檢查欄位是否為非空（allow_empty=False）。
Regexp 驗證的欄位：（key = “regexp”） - 此類型的欄位假定為字串，並使用指定的 regexp 進行驗證。請記住，regexp 理想情況下應在開頭包含 ^，在結尾包含 $，以確保驗證整個欄位內容。通常應謹慎且少量地使用此類 regexp 驗證（請參閱下面的向前相容性注意事項）。
自訂驗證的欄位：（key = “custom_validation”） - 此類型的欄位使用透過 custom_validation 欄位指定的方法進行驗證。自訂驗證中拋出的任何例外都將轉換為 FieldValidationException，並導致驗證失敗。此類自訂驗證可用於檢查數值欄位（包括值範圍）、布林值或任何其他類型的欄位。
API 版本：（key=”api_version”）如果指定了 API 版本，則僅當在欄位驗證器初始化時使用的 api_version 與指定的版本完全匹配時，才會驗證該欄位。如果您想宣告在多個 API 版本中可用的欄位，則應宣告該欄位與應支援的 API 版本一樣多次（每次使用不同的 API 版本）。
如果沒有任何 key（“type”、“regexp”、“custom_validation” - 則不驗證欄位
您可以在 EXAMPLE_VALIDATION_SPECIFICATION 中看到一些欄位範例。
向前相容性注意事項¶
某些決策對於允許用戶端 API 也適用於未來 API 版本至關重要。由於附加的 body 會傳遞到 API 的呼叫，因此完全有可能在 body 中傳遞任何新欄位（對於未來 API 版本） - 儘管沒有在用戶端進行驗證 - 它們通常仍然可以在伺服器端進行驗證。
以下是您應遵循的指導方針，以使驗證向前相容
大多數欄位未針對其內容進行驗證。可以在保證未來不會變更的某些特定情況下使用 regexp，但對於大多數欄位，regexp 驗證應為 r’^.+$’，表示檢查是否為非空
api_version 未驗證 - 使用者可以在此處傳遞任何未來版本的 api。API 版本僅用於篩選標記為在此 api 版本中存在的參數 任何新的（規範中不存在的）body 欄位都是允許的（未驗證） 對於字典，未來的呼叫可以將新欄位新增至字典。但是，如果在字典中新增了未知欄位，用戶端會記錄警告（但驗證仍然成功）。這是防止名稱中錯字的非常好的功能。
對於聯合，未來的呼叫可以新增新新增的聯合變體，它們將通過驗證，但是不會驗證這些欄位的內容或存在。這表示可以將新的未驗證聯合欄位與舊的已驗證欄位一起傳送，並且用戶端不會偵測到此問題。在這種情況下，將列印警告。
當您將驗證器新增至操作器時，您還應將
validate_body參數（預設值 = True）新增至此類操作器的 __init__ - 當設定為 False 時，不應執行驗證。這是針對 API 中有時可能發生的完全無法預測且向後不相容的變更的保護措施。
模組內容¶
類別¶
根據規範驗證請求 body 的正確性。 |
屬性¶
- airflow.providers.google.cloud.utils.field_validator.COMPOSITE_FIELD_TYPES = ['union', 'dict', 'list'][原始碼]¶
- exception airflow.providers.google.cloud.utils.field_validator.GcpFieldValidationException[原始碼]¶
基底：
airflow.exceptions.AirflowException當驗證發現字典欄位根據規範無效時拋出。
- exception airflow.providers.google.cloud.utils.field_validator.GcpValidationSpecificationException[原始碼]¶
基底：
airflow.exceptions.AirflowException當驗證規範錯誤時拋出。
- 這應該只在開發期間發生，因為理想情況下
規範本身不應無效 ;) 。
- class airflow.providers.google.cloud.utils.field_validator.GcpBodyFieldValidator(validation_specs, api_version)[原始碼]¶
基底：
airflow.utils.log.logging_mixin.LoggingMixin根據規範驗證請求 body 的正確性。
此規範可以描述各種欄位類型，包括自訂驗證和欄位聯合。此驗證器可由各種操作器重複使用。請參閱 EXAMPLE_VALIDATION_SPECIFICATION 以取得一些範例和有關如何建立規範的說明。
- 參數
validation_specs (collections.abc.Sequence[dict]) – 描述驗證規範的字典
api_version (str) – 使用的 api 版本（例如 v1）