search a ads

2026-06-18 12:43:42 +02:00
parent 9cd5c8011b
commit 125b112967
12 changed files with 748 additions and 191 deletions
@@ -0,0 +1,73 @@
+# Google Ads
+
+Proxy over the Google Ads API `GoogleAdsService` (GAQL search / searchStream),
+which covers virtually all Google Ads reporting. Bodies are forwarded as-is.
+
+The API version is in an env var (`GOOGLE_ADS_API_VERSION`, default `v19`)
+because Google deprecates versions roughly yearly — bump it without a code
+change. Base URL: `https://googleads.googleapis.com/{version}`.
+
+## Credentials
+
+Google Ads needs more than a Bearer token:
+
+| Header | Required | Meaning |
+| --- | --- | --- |
+| `X-GAds-Developer-Token` | **yes** | Developer token from a Google Ads manager account → `developer-token`. |
+| `X-GAds-Access-Token` | one of these | Ready OAuth2 access token (Bearer). |
+| `X-GAds-Credentials` | one of these | Base64 service-account JSON (scope `adwords`); needs domain-wide delegation. |
+| `X-GAds-Login-Customer-Id` | no | Manager (MCC) id → `login-customer-id`. Digits only. |
+| `X-GAds-Quota-Project` | no | GCP project id → `x-goog-user-project`. |
+
+> For Google Ads a service account works only with **domain-wide delegation**;
+> in practice the simplest path is a ready OAuth2 access token (obtained from a
+> refresh token with scope `https://www.googleapis.com/auth/adwords`) in
+> `X-GAds-Access-Token`.
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| POST | `/googleads/customers/{customer_id}/search` | GAQL query, paginated. |
+| POST | `/googleads/customers/{customer_id}/searchStream` | GAQL query, whole result set in one streamed response. |
+| GET | `/googleads/customers:listAccessibleCustomers` | Customer ids the credentials can access. |
+
+`customer_id` is the 10-digit account id (dashes are stripped for you).
+
+### Query body (GAQL)
+
+```json
+{
+  "query": "SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS"
+}
+```
+
+GAQL reference:
+<https://developers.google.com/google-ads/api/docs/query/overview>.
+
+## Kde získat údaje (návod pro klienta)
+
+- **Developer token**: v Google Ads **manager (MCC) účtu → Tools → API Center**.
+  Token musí mít schválený (approved) přístup, jinak vrací jen test účty.
+- **customer_id**: 10místné číslo účtu (vpravo nahoře v Google Ads, bez pomlček).
+- **login-customer-id**: ID manager účtu, přes který přistupujete (volitelné).
+- **Access token**: vygenerujte z refresh tokenu se scope
+  `https://www.googleapis.com/auth/adwords` (např. OAuth Playground) → hlavička
+  `X-GAds-Access-Token`.
+
+## Errors
+
+Upstream errors keep the Google Ads status and body (often a detailed
+`GoogleAdsFailure`) in `upstream_body`. A common one: developer token not
+approved, or `login-customer-id` required for manager access.
+
+## curl example
+
+```bash
+curl -X POST "https://services.csbot.cz/apps/analytics/googleads/customers/1234567890/searchStream" \
+  -H "X-GAds-Developer-Token: <DEV_TOKEN>" \
+  -H "X-GAds-Access-Token: ya29...." \
+  -H "X-GAds-Login-Customer-Id: 9876543210" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS"}'
+```