### Development Setup Commands (Shell)

Source: https://github.com/keboola/ex-google-ads/blob/master/README.md

These shell commands guide you through cloning the repository, setting up the development environment using Docker Compose, and installing dependencies.

```shell
git clone https://github.com/keboola/ex-google-ads.git
cd ex-google-ads
docker-compose build
docker-compose run --rm dev composer install --no-scripts
```

--------------------------------

### Docker Development Setup (Bash)

Source: https://context7.com/keboola/ex-google-ads/llms.txt

Commands to set up the development environment for the Google Ads Extractor using Docker Compose. Includes cloning the repository, building the image, installing dependencies, and configuring environment variables.

```bash
# Clone the repository
git clone https://github.com/keboola/ex-google-ads.git
cd ex-google-ads

# Build the Docker image
docker-compose build

# Install dependencies
docker-compose run --rm dev composer install --no-scripts

# Set up environment variables
cp .env.dist .env
# Edit .env file with your credentials:
# CUSTOMER_ID=111222333
# DEVELOPER_TOKEN=your-developer-token
# API_DATA={"refresh_token": "your-refresh-token"}
# CLIENT_SECRET=your-client-secret
# CLIENT_ID=your-client-id

```

--------------------------------

### GAQL Query Examples (SQL)

Source: https://context7.com/keboola/ex-google-ads/llms.txt

Examples of Google Ads Query Language (GAQL) queries for retrieving various metrics and dimensions, such as basic campaign performance, ad group details, keyword performance, and geographic data.

```sql
-- Basic campaign metrics
SELECT
  campaign.id,
  campaign.name,
  metrics.clicks,
  metrics.impressions
FROM campaign

-- Ad group performance with conversions
SELECT
  campaign.id,
  campaign.name,
  ad_group.id,
  ad_group.name,
  metrics.clicks,
  metrics.impressions,
  metrics.conversions,
  metrics.cost_micros
FROM ad_group

-- Keyword performance report
SELECT
  campaign.id,
  ad_group.id,
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  metrics.clicks,
  metrics.impressions,
  metrics.average_cpc
FROM keyword_view

-- Geographic performance
SELECT
  campaign.id,
  geographic_view.country_criterion_id,
  metrics.clicks,
  metrics.impressions,
  metrics.cost_micros
FROM geographic_view
```

--------------------------------

### Date Filtering Configuration Examples

Source: https://context7.com/keboola/ex-google-ads/llms.txt

This section demonstrates how to configure date ranges for data extraction using both relative date expressions (e.g., '-7 days') and absolute dates. The `since` and `until` parameters are key for filtering data based on the `segments.date` field in GAQL queries. An example for extracting all campaigns, including removed ones by leaving `since` and `until` empty, is also provided.

```json
{
  "parameters": {
    "customerId": "111222333",
    "name": "weekly-report",
    "query": "SELECT campaign.id, metrics.clicks FROM campaign",
    "since": "-7 days",
    "until": "-1 day"
  }
}
```

```json
// Alternative with absolute dates
{
  "parameters": {
    "customerId": "111222333",
    "name": "january-report",
    "query": "SELECT campaign.id, metrics.clicks FROM campaign",
    "since": "2024-01-01",
    "until": "2024-01-31"
  }
}
```

```json
// Extract all campaigns including removed (no date filter)
{
  "parameters": {
    "customerId": "111222333",
    "name": "all-campaigns",
    "query": "SELECT campaign.id, campaign.name, campaign.status FROM campaign",
    "since": "",
    "until": "",
    "onlyEnabledCustomers": false
  }
}
```

--------------------------------

### Run Composer Tests with Docker Compose

Source: https://context7.com/keboola/ex-google-ads/llms.txt

These commands utilize docker-compose to run various test suites for the project. They are essential for verifying the integrity of the codebase before deployment or after changes. Ensure Docker and docker-compose are installed and configured.

```bash
docker-compose run --rm dev composer tests
docker-compose run --rm dev composer tests-phpunit
docker-compose run --rm dev composer tests-datadir
```

--------------------------------

### Output Table Structure and Examples

Source: https://context7.com/keboola/ex-google-ads/llms.txt

The extractor generates CSV files for customer, campaign, and custom reports, each accompanied by a manifest file. The manifest defines primary keys and columns, crucial for Keboola's data handling. Examples show the expected CSV and manifest formats.

```bash
# Output directory structure
data/out/tables/
├── customer.csv              # Customer account information
├── customer.csv.manifest     # Manifest with primary keys and columns
├── campaign.csv              # Campaign data for all customers
├── campaign.csv.manifest     # Campaign manifest
└── report-{name}.csv         # Custom GAQL report results
└── report-{name}.csv.manifest
```

```csv
# Example customer.csv content
"id","descriptiveName","currencyCode","timeZone"
"1234567890","My Company Account","USD","America/New_York"
```

```csv
# Example campaign.csv content
"customerId","id","name","status","servingStatus","advertisingChannelType","startDate","endDate"
"1234567890","111222333","Brand Campaign","ENABLED","SERVING","SEARCH","2024-01-01","2024-12-31"
```

```json
# Example manifest structure
{
  "incremental": true,
  "primary_key": ["id"],
  "columns": ["id", "descriptiveName", "currencyCode", "timeZone"]
}
```

--------------------------------

### Configure Google Ads Extractor for Run Action (JSON)

Source: https://context7.com/keboola/ex-google-ads/llms.txt

Example configuration for the 'run' action, specifying multiple customer IDs and a GAQL query for ad group performance. Includes developer token and OAuth credentials.

```json
{
  "parameters": {
    "customerId": ["111222333", "444555666"],
    "name": "clicks-impressions-report",
    "query": "SELECT campaign.id, campaign.name, ad_group.id, ad_group.name, metrics.clicks, metrics.impressions, metrics.conversions FROM ad_group",
    "primary": ["campaignId", "adGroupId"],
    "since": "2024-01-01",
    "until": "2024-01-31",
    "onlyEnabledCustomers": true
  },
  "image_parameters": {
    "#developer_token": "ABC123developerToken"
  },
  "authorization": {
    "oauth_api": {
      "credentials": {
        "#data": "{\"refresh_token\": \"1//0xxx-refresh-token\"}",
        "#appSecret": "GOCSPX-secret",
        "appKey": "123456789.apps.googleusercontent.com"
      }
    }
  }
}
```

--------------------------------

### Example Google Ads Extractor Configuration (JSON)

Source: https://github.com/keboola/ex-google-ads/blob/master/README.md

This JSON configuration defines the parameters for the Google Ads Extractor. It includes the customer ID, report name, a Google Ads Query Language (GAQL) query, developer token, and OAuth API credentials.

```json
{
  "parameters": {
    "customerId": "111111111",
    "name": "test-report",
    "query": "SELECT campaign.id, campaign.name, metrics.clicks, metrics.impressions FROM campaign"
  },
  "image_parameters": {
    "#developer_token": "developertoken"
  },
  "authorization": {
    "oauth_api": {
      "credentials": {
        "#data": "{\"access_token\": ...}",
        "#appSecret": "appsecret",
        "appKey": "appkey"
      }
    }
  }
}
```

--------------------------------

### Environment Configuration (Shell)

Source: https://github.com/keboola/ex-google-ads/blob/master/README.md

This command copies the distribution environment file to a new file, allowing you to configure your local development environment with specific settings and credentials.

```shell
cp .env.dist .env
```

--------------------------------

### Running Test Suite (Shell)

Source: https://github.com/keboola/ex-google-ads/blob/master/README.md

This command executes the test suite for the Google Ads Extractor within the Dockerized development environment, ensuring the component functions as expected.

```shell
docker-compose run --rm dev composer tests
```

--------------------------------

### Configure Google Ads Extractor for Data Extraction (JSON)

Source: https://context7.com/keboola/ex-google-ads/llms.txt

Configuration for the default 'run' action of the Google Ads Extractor. Specifies customer IDs, GAQL query, date range, and OAuth credentials for data extraction.

```json
{
  "parameters": {
    "customerId": "111222333",
    "name": "campaign-performance-report",
    "query": "SELECT campaign.id, campaign.name, metrics.clicks, metrics.impressions, metrics.cost_micros FROM campaign",
    "primary": ["campaignId", "campaignName"],
    "since": "-7 days",
    "until": "-1 day",
    "onlyEnabledCustomers": true,
    "#developerToken": "your-developer-token"
  },
  "image_parameters": {
    "#developer_token": "your-developer-token"
  },
  "authorization": {
    "oauth_api": {
      "credentials": {
        "#data": "{\"access_token\": \"ya29.xxx\", \"refresh_token\": \"1//xxx\", \"token_type\": \"Bearer\"}",
        "#appSecret": "your-client-secret",
        "appKey": "your-client-id"
      }
    }
  }
}
```

--------------------------------

### Configure Google Ads Extractor for List Accounts Action (JSON)

Source: https://context7.com/keboola/ex-google-ads/llms.txt

Configuration for the 'listAccounts' action, used to retrieve the hierarchy of accessible Google Ads accounts. Includes developer token and OAuth credentials.

```json
{
  "action": "listAccounts",
  "parameters": {
    "getAccountChildren": true
  },
  "image_parameters": {
    "#developer_token": "ABC123developerToken"
  },
  "authorization": {
    "oauth_api": {
      "credentials": {
        "#data": "{\"refresh_token\": \"1//0xxx-refresh-token\"}",
        "#appSecret": "GOCSPX-secret",
        "appKey": "123456789.apps.googleusercontent.com"
      }
    }
  }
}
```

--------------------------------

### PHP Error Handling and Retry Logic

Source: https://context7.com/keboola/ex-google-ads/llms.txt

The component implements structured error handling for common Google Ads API issues. `UserException` is thrown for configuration and authentication problems. API errors are mapped to `UserException` with status codes. Transient errors trigger automatic retries with exponential backoff, up to 5 attempts with a total timeout of 300 minutes, specifically for internal server errors.

```php
<?php
// UserException thrown for configuration and authentication issues
// - OAuth Credentials is not set.
// - Developer token doesn't set.
// - Date {name} in configuration is invalid.
// - Primary keys "{keys}" are not valid. Expected keys: "{columns}"

// ApiException mapped to UserException with status code
// Example error response:
// "INVALID_ARGUMENT: Request contains an invalid argument."
// "PERMISSION_DENIED: User does not have permission to access this resource."
// "UNAUTHENTICATED: Request had invalid authentication credentials."

// Retry behavior for transient errors
// - Automatic retry with exponential backoff (5 attempts max)
// - Total timeout: 300 minutes
// - Retryable codes: INTERNAL server errors
?>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.