`airflow.providers.google.cloud.utils.field_validator`¶

通过 Google Cloud API 发送的请求体字段的验证器。

该验证器执行通过 API 请求发送到 Google Cloud 的请求体（字段字典）的验证（通常是通过 googleclient API）。

背景¶

该规范主要侧重于在开发阶段帮助 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)。
正则表达式验证字段：(key = “regexp”) - 此类型的字段假定为字符串，并使用指定的正则表达式进行验证。请记住，正则表达式理想情况下应在开头包含 ^，在结尾包含 $，以确保验证整个字段内容。通常，此类正则表达式验证应谨慎使用（请参阅下面的向前兼容性说明）。
自定义验证字段：(key = “custom_validation”) - 此类型的字段使用通过 custom_validation 字段指定的方法进行验证。自定义验证中引发的任何异常都将转换为 FieldValidationException，并导致验证失败。此类自定义验证可用于检查数值字段（包括值范围）、布尔值或任何其他类型的字段。
API 版本：(key=”api_version”) 如果指定了 API 版本，则仅当在字段验证器初始化时使用的 api_version 与指定的版本完全匹配时，才会验证该字段。如果要声明在多个 API 版本中可用的字段，则应指定字段多次（与应支持的 API 版本一样多）（每次都使用不同的 API 版本）。
如果没有键 (“type”、“regexp”、“custom_validation”)，则不会验证该字段

您可以在 EXAMPLE_VALIDATION_SPECIFICATION 中看到一些字段示例。

向前兼容性说明¶

某些决策对于允许客户端 API 也与未来的 API 版本一起工作至关重要。由于附加的请求体被传递给 API 的调用，因此完全可以在请求体中传递任何新字段（对于未来的 API 版本） - 尽管在客户端没有验证 - 它们仍然可以在服务器端进行验证。

以下是您应遵循的使验证向前兼容的准则

大多数字段的内容未经过验证。可以在某些保证将来不会更改的特定情况下使用正则表达式，但是对于大多数字段，正则表达式验证应为 r'^.+$'，表示检查是否为空
api_version 未经过验证 - 用户可以在此处传递任何未来的 API 版本。API 版本仅用于筛选标记为在此 API 版本中存在的参数，允许请求体中的任何新的（规范中不存在的）字段（未验证）。对于字典，可以通过将来的调用将新字段添加到字典中。但是，如果在字典中添加了未知字段，客户端会记录警告（但验证仍然成功）。这是一个很好的功能，可以防止名称中的拼写错误。
对于联合，可以通过将来的调用添加新添加的联合变体，并且它们将通过验证，但是这些字段的内容或存在不会经过验证。这意味着可以发送一个新的未经验证的联合字段以及旧的经过验证的字段，并且客户端不会检测到此问题。在这种情况下，将打印警告。
将验证器添加到操作符时，还应向此类操作符的 __init__ 添加 validate_body 参数（默认值 = True） - 当设置为 False 时，不应执行验证。这是对 API 中可能偶尔发生完全不可预测且向后不兼容的更改的保护。

模块内容¶

类¶

GcpBodyFieldValidator

根据规范验证请求体的正确性。

属性¶

`COMPOSITE_FIELD_TYPES`
`EXAMPLE_VALIDATION_SPECIFICATION`

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

当验证规范错误时抛出。

这只应在开发期间发生，因为理想情况下: 规范本身不应无效 ;) 。

airflow.providers.google.cloud.utils.field_validator.EXAMPLE_VALIDATION_SPECIFICATION[来源]¶

class airflow.providers.google.cloud.utils.field_validator.GcpBodyFieldValidator(validation_specs, api_version)[来源]¶

基类: airflow.utils.log.logging_mixin.LoggingMixin

根据规范验证请求体的正确性。

该规范可以描述各种类型的字段，包括自定义验证和字段的联合。此验证器可由各种运算符重用。有关如何创建规范的一些示例和说明，请参阅 EXAMPLE_VALIDATION_SPECIFICATION。

参数

validation_specs (collections.abc.Sequence[dict]) – 描述验证规范的字典
api_version (str) – 使用的 API 版本（例如 v1）

validate(body_to_validate)[源代码]¶

验证主体（字典）是否遵循验证器实例化的规范。

如果规范存在问题或主体不符合规范，则分别引发 ValidationSpecificationException 或 ValidationFieldException。

参数: body_to_validate (dict) – 必须遵循规范的主体
返回: 无
返回类型: 无

airflow.providers.google.cloud.utils.field_validator¶

背景¶

字段类型¶

向前兼容性说明¶

模块内容¶

类¶

属性¶

`airflow.providers.google.cloud.utils.field_validator`¶