ClaireLytt opened a new pull request, #12275:
URL: https://github.com/apache/seatunnel/pull/12275
### Purpose of this pull request
Add a new Connector-V2 source connector for **Facebook Ads** (Meta Marketing
API), subtask of the API-source umbrella issue #10753.
The connector reads ad account edges (`campaigns`, `adsets`, `ads`,
`insights`, etc.) from the Facebook Graph API as a bounded source, modeled on
the Google Ads source connector (#12230):
- Cursor-based pagination following `paging.next` / `paging.cursors.after`
- Authentication via long-lived access token sent as `Authorization: Bearer`
header (never in the query string)
- Rate-limit-aware retries with exponential backoff: transient HTTP errors
(429/5xx) and Facebook rate-limit error codes (4, 17, 32, 613) are retried up
to `max_retries`; 401 fails fast with an auth error, other 4xx fail fast
surfacing the Graph API error message
- Two modes: single `resource` mode, or `tables_configs` multi-table mode
with per-table `ad_account_id` override
- All columns are produced as STRING (the Graph API has no field metadata
service and returns insights metrics as strings); nested objects/arrays are
serialized as JSON text; the CatalogTable is built locally, so no network call
happens at job compile time
- Config validation: resource/field name patterns, reserved query params,
`act_` prefix normalization of ad account ids, duplicate/malformed `table_path`
detection
### Does this PR introduce _any_ user-facing change?
Yes. It adds a new source connector `FacebookAds` with its options
(`access_token`, `ad_account_id`, `resource`/`tables_configs`, `fields`,
`filtering`, `params`, `api_version`, `page_size`, retry options, etc.), plus
new documentation:
- `docs/en/connector-v2/source/FacebookAds.md`
- `docs/zh/connector-v2/source/FacebookAds.md`
No change to any existing connector or released behavior.
### How was this patch tested?
26 unit tests added, all passing (`./mvnw -pl
seatunnel-connectors-v2/connector-facebook-ads test`):
- `FacebookAdsSourceFactoryTest` (9): option rule validation — required
options, `resource`/`tables_configs` exclusivity, missing-mode and
missing-required rejection
- `FacebookAdsSourceTest` (11): config resolution — all-STRING schema in
field order, table id generation, field/resource/ad_account_id validation,
reserved param rejection, `act_` prefix stripping, multi-table build with
per-table ad account fallback, duplicate and malformed `table_path` rejection
- `FacebookAdsClientTest` (6): HTTP behavior against an embedded
`com.sun.net.httpserver.HttpServer` (no mock libraries) — cursor pagination
across pages, Bearer header and query param encoding, 401 fail-fast, transient
503 retry count, rate-limit-400 (code 4) retry, plain-400 fail-fast surfacing
the API error
E2E tests are not included because the Facebook Graph API requires a real ad
account and access token; the HTTP contract is covered by the embedded-server
client tests instead (same approach as the Google Ads connector).
### Check list
* [x] If any new Jar binary package adding in your PR, please add License
Notice according
[New License
Guide](https://github.com/apache/seatunnel/blob/dev/docs/en/developer/new-license.md)
— no new dependencies; reuses `httpclient`/`jackson`/`commons-lang3` already
used by connector-google-ads
* [x] If necessary, please update the documentation to describe the new
feature. https://github.com/apache/seatunnel/tree/dev/docs
* [x] If necessary, please update `incompatible-changes.md` to describe the
incompatibility caused by this PR. — not needed, purely additive
* [x] If you are contributing the connector code, please check that the
following files are updated:
1. Update
[plugin-mapping.properties](https://github.com/apache/seatunnel/blob/dev/plugin-mapping.properties)
and add new connector information in it — done
2. Update the pom file of
[seatunnel-dist](https://github.com/apache/seatunnel/blob/dev/seatunnel-dist/pom.xml)
— done
3. Add ci label in
[label-scope-conf](https://github.com/apache/seatunnel/blob/dev/.github/workflows/labeler/label-scope-conf.yml)
— done
4. Add e2e testcase in
[seatunnel-e2e](https://github.com/apache/seatunnel/tree/dev/seatunnel-e2e/seatunnel-connector-v2-e2e/)
— not added; requires a real Facebook ad account/token (see testing section)
5. Update connector
[plugin_config](https://github.com/apache/seatunnel/blob/dev/config/plugin_config)
— done
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
