Airbyte Criteo Marketing 声明式源详解:Low-Code CDK 清单、OAuth 认证与增量同步实现
Airbyte Criteo Marketing 声明式源详解:Low-Code CDK 清单、OAuth 认证与增量同步实现
Airbyte 中的 source-criteo-marketing 是一个典型的声明式(Declarative)数据源连接器,它不依赖任何 Python/Java 运行时代码,而是完全由一份 YAML 清单(manifest.yaml)描述认证、请求、记录抽取、模式与增量逻辑。本文以该连接器的 README 及其同目录下的清单文件为主体,逐层拆解其配置参数、OAuth client_credentials 认证链、两个数据流(ad_spend_daily 与 adsets)的实现细节以及限流与验收测试策略,帮助你在阅读类似 Low-Code CDK 连接器或自行构建声明式源时获得可直接对照的实践参考。
连接器目录结构与定位
从 README.md 可以看到,该连接器是使用 Airbyte Connector Builder 构建的声明式连接器,其 YAML 清单格式遵循 Low-Code CDK 规范;README 同时指出,连接器若有专属的排障与测试指引,会记录在该目录下的 CONTRIBUTING.md 中(当前该连接器目录下尚未包含此文件)。整个目录仅由少量文件构成,这正体现了声明式连接器的特点:
| 文件 | 作用 |
|---|---|
| README.md | 声明式连接器模板说明,指向 Connector Builder 与本地开发文档 |
| manifest.yaml | 连接器的全部技术实现:spec、check、streams、限流策略 |
| metadata.yaml | 发布元数据:Docker 镜像、版本、支持级别、标签 |
| acceptance-test-config.yml | 验收测试配置 |
| icon.svg | 连接器图标 |
metadata.yaml 进一步确认了它的定位:连接器名为 Criteo Marketing,类型为 source、子类型为 api,标签为 language:manifest-only 与 cdk:low-code,即"纯清单、无代码";发布状态为 alpha,支持级别为 community,许可证为 ELv2,当前 Docker 镜像为 airbyte/source-criteo-marketing,镜像标签 0.0.17,构建基镜像为 airbyte/source-declarative-manifest:7.28.4(带固定摘要),OSS 与 Cloud 双渠道均启用。
连接配置(spec):四个必填项与两个机密字段
清单末尾的 spec 段定义了连接规范(connection_specification),用户配置连接时可见的字段及其约束如下(manifest.yaml 第 408 行起):
| 配置项 | 类型 | 必填 | 说明 | 约束 |
|---|---|---|---|---|
client_id |
string | 是 | OAuth Client ID | airbyte_secret: true,界面显示为密文 |
client_secret |
string | 是 | OAuth Client Secret | airbyte_secret: true,界面显示为密文 |
start_date |
string | 是 | 报表起始日期 | format: date,正则 ^[0-9]{4}-[0-9]{2}-[0-9]{2}$(即 YYYY-MM-DD) |
currency |
string | 是 | 报表使用的币种 | — |
end_date |
string | 否 | 报表结束日期 | 同样受 YYYY-MM-DD 正则约束,缺省时运行时回退为"当前 UTC 日期" |
spec 还声明了 documentation_url 指向 Criteo Marketing Solutions 的 API 参考文档。additionalProperties: true 保留了扩展空间。各字段通过 order 属性(0~4)控制界面展示顺序:client_id → client_secret → start_date → end_date → currency。
连接检查(check):CheckStream 策略
清单中的 check 段采用 CheckStream 类型,仅探测 ad_spend_daily 这一个流(manifest.yaml 第 10 行起):
check:
type: CheckStream
stream_names:
- ad_spend_daily
这意味着用户在 Airbyte 中点击"测试连接"时,底层会实际发起一次 ad_spend_daily 流的请求(走 OAuth 取 token + 报表接口),以此同时验证凭据有效性与日期配置可用性,而不会去请求 adsets 流。
流一:ad_spend_daily —— 按天增量拉取广告花费报表
请求构造:Jinja 模板化请求体
ad_spend_daily 流通过 SimpleRetriever 向 Criteo 统计报表接口发起 POST 请求:
url: https://api.criteo.com/2025-10/statistics/report
http_method: POST
请求体(RequestBodyJsonObject)是一个 JSON 对象,其中日期字段使用 Jinja 表达式动态生成(manifest.yaml 第 16~36 行的共享定义):
| 请求体字段 | 取值逻辑 |
|---|---|
endDate |
增量模式下取 stream_interval.end_time;否则取 config['end_date'],再否则回退为当前 UTC 日期(%Y-%m-%d) |
startDate |
增量模式下取 stream_interval.start_time;否则取 config['start_date'] |
metrics |
固定为 [AdvertiserCost],即只拉取广告主花费这一指标 |
dimensions |
固定为 [day, AdvertiserId, CampaignId, AdSetId],即按"天 + 广告主 + 活动 + 广告组"维度聚合 |
currency |
直接透传用户配置的 {{ config.currency }} |
值得注意的是,请求体、认证器与错误处理器都定义在 definitions.linked 中,流内通过 $ref: "#/definitions/linked/HttpRequester/request_body" 引用,这是清单复用(linked definitions)的标准写法。
增量同步:DatetimeBasedCursor 与 3 天回溯窗口
该流是清单中唯一支持增量同步的流,游标配置如下:
incremental_sync:
type: DatetimeBasedCursor
cursor_field: Day
start_datetime: "{{ config['start_date'] }}"
end_datetime: "{{ config.get('end_date') or now_utc().strftime('%Y-%m-%d') }}"
datetime_format: "%Y-%m-%d"
lookback_window: P3D
cursor_datetime_formats:
- "%Y-%m-%d"
要点解读:
- 游标字段是记录中的
Day(字符串日期,格式%Y-%m-%d),首次同步起点由用户配置的start_date决定; lookback_window: P3D表示每次增量同步都会向前多回看 3 天,用于覆盖源端延迟入账/补数的报表数据,避免漏数;end_datetime在end_date未配置时动态取当前 UTC 日期,因此全量(full refresh)与增量(incremental)两种同步模式都能工作——官方流表格中标注该流同时支持 Full Sync 与 Incremental;- 主键为复合主键
AdvertiserId + CampaignId + Day,保证同一天同一广告组的花费记录在目标端可被唯一去重更新。
记录抽取与内联 Schema
响应经 JsonDecoder 解码后,由 RecordSelector + DpathExtractor 从 Rows 字段抽取记录:
record_selector:
type: RecordSelector
extractor:
type: DpathExtractor
field_path:
- Rows
模式采用 InlineSchemaLoader 手工内联声明(autoImportSchema 对 ad_spend_daily 为 false,即不从响应自动导入),字段包括 Day、Campaign、Currency、Advertiser、CampaignId、AdvertiserId、AdvertiserCost,其中 AdvertiserId、CampaignId、Day 为 required,additionalProperties: true 允许携带未声明字段。
流二:adsets —— 全量拉取广告组元数据
adsets 流调用营销方案(marketing solutions)的搜索接口:
url: https://api.criteo.com/2026-01/marketing-solutions/ad-sets/search
http_method: POST
request_body:
type: RequestBodyJsonObject
value:
filters: {}
请求体为空过滤条件(filters: {}),即无条件下拉取;记录从响应的 data 字段抽取,主键为 id。与 ad_spend_daily 不同,该流没有 incremental_sync 段,因此只支持全量刷新(full refresh);同时 autoImportSchema 对 adsets 为 true,说明其内联 schema 曾借助自动导入能力生成,再由人工维护。
内联 schema 完整描述了广告组对象的嵌套结构(manifest.yaml 第 178~405 行),核心层级为:
- 顶层:
id(required)、type、attributes; attributes下包含:- 基础信息:
name、advertiserId、datasetId、campaignId、destinationEnvironment、objective、mediaType; schedule:排期对象,含startDate.value、endDate、activationStatus、deliveryStatus;bidding:出价对象,含bidAmount(number)、costController;targeting:定向对象,含deliveryLimitations(environments/devices/operatingSystems三个字符串数组)、geoLocation(countries/subdivisions/zipCodes,值为{operand, values[]}结构)、frequencyCapping(frequency、maximumImpressions);budget:预算对象,含budgetStrategy、budgetRenewal、budgetDeliverySmoothing、budgetDeliveryWeek、budgetAmount(number);attributionConfiguration.attributionMethod:归因方式。
- 基础信息:
这类结构对下游数仓的价值在于:ad_spend_daily 提供"每天花了多少钱",adsets 提供"广告组长什么样、定向与预算如何配置",两者可通过 AdvertiserId/CampaignId 与 adsets.attributes.campaignId 关联,构成广告花费与广告组元数据的完整分析数据集。
认证:OAuth client_credentials 全字段映射
两个流使用完全相同的 OAuthAuthenticator 配置(ad_spend_daily 流中直接内联,adsets 流中完整复制),关键字段如下:
authenticator:
type: OAuthAuthenticator
grant_type: client_credentials
client_id: "{{ config[\"client_id\"] }}"
client_secret: "{{ config[\"client_secret\"] }}"
token_refresh_endpoint: https://api.criteo.com/oauth2/token
client_id_name: client_id
expires_in_name: expires_in
grant_type_name: grant_type
access_token_name: access_token
client_secret_name: client_secret
refresh_token_name: refresh_token
use_profile_assertion: false
实现层面可以读出三点:
- 采用
client_credentials授权类型,即"客户端自身身份换 token",无需用户授权跳转,适合 API 对 API 的服务端集成; - 各
*_name字段声明了 token 响应中字段名的映射约定(expires_in、access_token等),Low-Code CDK 据此解析并缓存 token、在过期前经token_refresh_endpoint刷新; use_profile_assertion: false表示不启用 profile assertion 扩展流程。
错误处理与重试:两个流不同的退避因子
错误处理通过共享定义 #/definitions/linked/HttpRequester/error_handler 复用:
error_handler:
type: DefaultErrorHandler
max_retries: 5
backoff_strategies:
- type: ExponentialBackoffStrategy
factor: 3
ad_spend_daily流复用该定义,最大重试 5 次、指数退避因子为 3;adsets流则内联了自己的错误处理器,同样是max_retries: 5,但退避因子为 2,即重试节奏更快(manifest.yaml 第 165~170 行)。
从源码结构看,这种"共享定义 + 流内覆写"的组合正是 Low-Code CDK 清单表达差异化行为的惯用手段。
API 预算:固定窗口限流策略
清单顶层的 api_budget 段声明了连接器的 API 预算,属于 HTTPAPIBudget 类型:
api_budget:
type: HTTPAPIBudget
policies:
- type: FixedWindowCallRatePolicy
period: PT1M
matchers: []
call_limit: 250
ratelimit_reset_header: ratelimit-reset
ratelimit_remaining_header: x-ratelimit-remaining
status_codes_for_ratelimit_hit:
- 429
含义:在任意 1 分钟固定窗口内,客户端最多主动发起 250 次调用;同时监听响应头 x-ratelimit-remaining 与 ratelimit-reset 以感知服务端剩余配额,遇到 HTTP 429 即判定触发限流并按策略等待。由于该连接器无分页、请求次数受控(报表按日窗口、adsets 为单请求),这一预算主要起防御性保护作用。
验收测试与当前限制
acceptance-test-config.yml 显示:
- 使用镜像
airbyte/source-criteo-marketing:dev; spec测试启用,spec_path指向manifest.yaml,即对清单本身做 spec 契约校验;connection、discovery、basic_read、incremental、full_refresh五类测试均以bypass_reason跳过,原因是"builder contribution(Connector Builder 社区贡献),暂时无真实密钥"。
这意味着当前 CI 只保证清单结构与 spec 的正确性;涉及真实凭据的端到端同步路径需要用户在本地补齐密钥后自行验证。这也与 metadata.yaml 中 releaseStage: alpha 的发布状态一致:该连接器仍处于社区支持的 alpha 阶段。
元数据中记录的流健康度
清单尾部 metadata 段还保存了两类 CI 辅助信息:
testedStreams:记录两条流最近一次自动化验证结果——hasRecords: true、hasResponse: true、primaryKeysAreUnique: true、primaryKeysArePresent: true、responsesAreSuccessful: true、isStale: false,并附带streamHash,用于检测清单变更导致的历史验证结果失效;autoImportSchema:adsets: true、ad_spend_daily: false,与上文两流的 schema 维护方式对应。
这些字段不属于运行时行为,而是 CI 与清单维护的元信息,可作为判断"该清单是否长期被自动化验证"的依据。
本地开发与验证路径
按照 README.md 的指引,本地开发与测试遵循 Airbyte 统一的本地连接器开发流程(README 链接指向 Airbyte 官方文档的 Local Connector Development 章节)。落到本连接器目录,可操作的验证路径是:
- 查看 manifest.yaml 与 metadata.yaml 之外的元数据文件,确认
dockerRepository、dockerImageTag与基镜像版本,以便按source-declarative-manifest基镜像本地构建调试镜像; - 配置连接时按 spec 填写
client_id、client_secret(Criteo OAuth 应用凭据)、start_date与currency,日期必须严格为YYYY-MM-DD格式,否则会在 schema 校验阶段被 pattern 规则拒绝; - 增量模式下观察
ad_spend_daily的同步窗口:起点由上次游标(Day)回退 3 天决定,终点为stream_interval结束时间或当前 UTC 日期。
小结
source-criteo-marketing 是一个以 manifest.yaml 为全部实现的 Low-Code CDK 声明式源:
- 配置层:4 个必填项(OAuth 凭据、起始日期、币种)+ 1 个可选结束日期,机密字段自动遮蔽;
- 数据层:
ad_spend_daily按天增量(Day游标、3 天回溯窗口、复合主键),adsets全量刷新广告组元数据; - 运行时:OAuth client_credentials 令牌自动刷新、
DefaultErrorHandler指数退避重试(因子分别为 3 与 2)、250 次/分钟的固定窗口 API 预算; - 工程层:spec 契约测试入 CI,其余验收测试因缺密钥而 bypass,发布状态为 alpha、社区支持。
对于希望理解 Airbyte 声明式连接器的开发者,这份清单几乎涵盖了 check、definitions/$ref 复用、RequestBodyJsonObject 模板化请求体、DatetimeBasedCursor 增量、内联 schema、OAuthAuthenticator 字段映射与 HTTPAPIBudget 限流的全部典型构件,可直接作为阅读同类 manifest-only 连接器的参照样本。