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

此条目有帮助吗？