airflow.providers.google.cloud.utils.field_validator

用於驗證透過 Google Cloud API 傳送的主體欄位。

驗證器執行對傳送到 Google Cloud（通常透過 googleclient API）的 API 請求中的主體（一個欄位字典）的驗證。

背景

本規範主要旨在幫助 Airflow DAG 開發者在開發階段進行開發。您可以構建自己的 Google Cloud operator（例如 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'^.+$'),
   ),
   ...
]

每個欄位都應具有鍵 = “name”，表示欄位名。欄位可以是以下型別之一：

  • 字典欄位：（鍵 = “type”，值 = “dict”）：此型別的欄位應包含一個字典陣列形式的巢狀欄位。陣列中的每個欄位（除非標記為可選）都被期望存在並進行遞迴驗證。如果在字典中存在額外欄位，則在日誌檔案中列印警告（但驗證成功 - 請參閱前向相容性說明）

  • 列表欄位：（鍵 = “type”，值 = “list”）：此型別的欄位應為一個列表。僅驗證型別正確性。列表的內容不進行驗證。

  • 聯合欄位（鍵 = “type”，值 = “union”）：此型別的欄位應包含一個字典陣列形式的巢狀欄位。其中一個欄位（且僅一個）應該存在（除非聯合標記為可選）。如果存在多個聯合欄位，則丟擲 FieldValidationException。如果聯合欄位都不存在，則在日誌中列印警告（請參閱下面的前向相容性說明）。

  • 驗證非空的欄位：（鍵 = “allow_empty”） - 這僅適用於值為字串的欄位，它允許檢查欄位是否非空（allow_empty=False）。

  • 正則表示式驗證欄位：（鍵 = “regexp”） - 此型別的欄位假定為字串，並使用指定的 regexp 進行驗證。請記住，正則表示式最好在開頭包含 ^ 並在結尾包含 $，以確保驗證整個欄位內容。通常應謹慎且少量使用此類正則表示式驗證（請參閱下面的前向相容性說明）。

  • 自定義驗證欄位：（鍵 = “custom_validation”） - 此型別的欄位使用 custom_validation 欄位指定的方法進行驗證。自定義驗證中丟擲的任何異常都將轉為 FieldValidationException 並導致驗證失敗。此類自定義驗證可用於檢查數字欄位（包括值範圍）、布林值或任何其他型別的欄位。

  • API 版本：（鍵 = “api_version”）如果指定了 API 版本，則僅當欄位驗證器初始化時使用的 api_version 與指定的版本完全匹配時，才會驗證該欄位。如果您想宣告在多個 API 版本中可用的欄位，則應宣告該欄位多次，支援多少個 API 版本就宣告多少次（每次使用不同的 API 版本）。

  • 如果 None 的鍵（“type”，“regexp”，“custom_validation”） - 該欄位不進行驗證

您可以在 EXAMPLE_VALIDATION_SPECIFICATION 中看到一些欄位示例。

前向相容性說明

某些決策對於使客戶端 API 也能與未來的 API 版本一起工作至關重要。由於附加的主體被傳遞給 API 呼叫，因此完全有可能在主體中傳遞任何新欄位（用於未來的 API 版本） - 儘管在客戶端沒有驗證 - 它們通常仍然可以在伺服器端進行驗證。

以下是您應該遵循的指導原則，以使驗證具有前向相容性：

  • 大多數字段的內容不進行驗證。在某些特定情況下，可以使用正則表示式，這些情況保證將來不會改變，但對於大多數字段，正則表示式驗證應為 r’^.+$’，表示檢查非空。

  • api_version 不進行驗證 - 使用者可以在此處傳遞任何未來版本的 api。API 版本僅用於過濾標記為在此 api 版本中存在的引數。主體中任何新的（規範中不存在的）欄位都是允許的（不驗證）。對於字典，未來的呼叫可以向字典新增新欄位。但是，如果在字典中添加了未知欄位，客戶端會記錄一個警告（但驗證仍然成功）。這是一個很好的功能，可以防止名稱中的拼寫錯誤。

  • 對於聯合，未來的呼叫可以新增新的聯合變體，它們將透過驗證，但這些欄位的內容或存在性將不進行驗證。這意味著可能將一個新的未驗證的聯合欄位與一箇舊的已驗證欄位一起傳送，並且客戶端不會檢測到此問題。在這種情況下，將列印警告。

  • 當您向 operator 新增驗證器時，您還應該向此類 operator 的 __init__ 新增 validate_body 引數（預設 = True） - 當其設定為 False 時，不應執行任何驗證。這是針對有時可能在 API 中發生的完全不可預測和向後不相容的更改的保障。

屬性

COMPOSITE_FIELD_TYPES

EXAMPLE_VALIDATION_SPECIFICATION

異常

GcpFieldValidationException

當驗證發現字典欄位不符合規範時丟擲。

GcpValidationSpecificationException

當驗證規範錯誤時丟擲。

類

GcpBodyFieldValidator

根據規範驗證請求主體的正確性。

模組內容

airflow.providers.google.cloud.utils.field_validator.COMPOSITE_FIELD_TYPES = ['union', 'dict', 'list'][source]
exception airflow.providers.google.cloud.utils.field_validator.GcpFieldValidationException[source]

基類：airflow.exceptions.AirflowException

當驗證發現字典欄位不符合規範時丟擲。

exception airflow.providers.google.cloud.utils.field_validator.GcpValidationSpecificationException[source]

基類：airflow.exceptions.AirflowException

當驗證規範錯誤時丟擲。

這應該只在開發過程中發生，因為理想情況下

規範本身不應該是無效的 😉。

airflow.providers.google.cloud.utils.field_validator.EXAMPLE_VALIDATION_SPECIFICATION[source]
class airflow.providers.google.cloud.utils.field_validator.GcpBodyFieldValidator(validation_specs, api_version)[source]

基類：airflow.utils.log.logging_mixin.LoggingMixin

根據規範驗證請求主體的正確性。

該規範可以描述各種型別的欄位，包括自定義驗證和欄位的聯合。此驗證器可被各種 operator 重複使用。有關如何建立規範的一些示例和解釋，請參閱 EXAMPLE_VALIDATION_SPECIFICATION。

引數:
validate(body_to_validate)[source]

驗證主體（字典）是否遵循例項化驗證器時使用的規範。

在規範存在問題或主體不符合規範的情況下，分別丟擲 ValidationSpecificationException 或 ValidationFieldException。

引數:

body_to_validate (dict) – 必須遵循規範的主體

返回:

None

返回型別:

None

此條目有幫助嗎？