Amazon Ads
This connector captures data from Amazon Ads into Flow collections via the Amazon Ads API.
It is available for use in the Flow web application. For local development or open-source workflows, ghcr.io/estuary/source-amazon-ads:dev
provides the latest version of the connector as a Docker image. You can also follow the link in your browser to see past image versions.
This connector is based on an open-source connector from a third party, with modifications for performance in the Flow system.
Supported data resources
The following data resources are supported:
- Profiles
- Sponsored brands ad groups
- Sponsored brands campaigns
- Sponsored brands keywords
- Sponsored brands report stream
- Sponsored brands video report stream
- Sponsored display ad groups
- Sponsored display ad campaigns
- Sponsored display product ads
- Sponsored display report stream
- Sponsored display targetings
- Sponsored product ad groups
- Sponsored product ads
- Sponsored product campaigns
- Sponsored product keywords
- Sponsored product negative keywords
- Sponsored product targetings
- Sponsored product report stream
By default, each resource is mapped to a Flow collection through a separate binding.
Prerequisites
This connector uses OAuth2 to authenticate with Amazon. You can do this in the Flow web app, or configure manually if you're using the flowctl CLI.
Using OAuth2 to authenticate with Amazon in the Flow web app
You'll need an Amazon user account with access to the Amazon Ads account from which you wish to capture data.
You'll use these credentials to sign in.
Authenticating manually using the CLI
When you configure this connector manually, you provide the same credentials that OAuth2 would automatically fetch if you used the web app. These are:
- Client ID
- Client secret
- Refresh token
To obtain these credentials:
-
Complete the Amazon Ads API onboarding process.
Selecting data region and profiles
When you configure the endpoint for this connector, you must choose an Amazon region from which to capture data. Optionally, you may also select profiles from which to capture data.
The region must be one of:
- NA (North America)
- EU (European Union)
- FE (Far East)
These represent the three URL endpoints provided by Amazon through which you can access the marketing API. Each region encompasses multiple Amazon marketplaces, which are broken down by country. See the Amazon docs for details.
If you run your Amazon ads in multiple marketplaces, you may have separate profiles for each. If this is the case, you can specify the profiles from which you wish to capture data by supplying their profile IDs. Be sure to specify only profiles that correspond to marketplaces within the region you chose.
Configuration
You configure connectors either in the Flow web app, or by directly editing the catalog specification file. See connectors to learn more about using connectors. The values and specification sample below provide configuration details specific to the Amazon Ads source connector.
Properties
Endpoint
The properties in the table below reflect the manual authentication method. If you're working in the Flow web app, you'll use OAuth2, so many of these properties aren't required.
Property | Title | Description | Type | Required/Default |
---|---|---|---|---|
/credentials | object | Required | ||
/credentials/auth_type | Auth Type | Set to oauth2.0 for manual integration (in this method, you're re-creating the same credentials of the OAuth user interface, but doing so manually) | string | |
/credentials/client_id | Client ID | The client ID of your Amazon Ads developer application. | string | Required |
/credentials/client_secret | Client Secret | The client secret of your Amazon Ads developer application. | string | Required |
/credentials/refresh_token | Refresh Token | Amazon Ads refresh token. | string | Required |
/profiles | Profile IDs (Optional) | Profile IDs you want to fetch data for. | array | |
/region | Region * | Region to pull data from (EU/NA/FE). | string | "NA" |
/report_generation_max_retries | Report Generation Maximum Retries * | Maximum retries the connector will attempt for fetching report data. | integer | 5 |
/report_wait_timeout | Report Wait Timeout * | Timeout duration in minutes for reports. | integer | 60 |
/start_date | Start Date (Optional) | The start date for collecting reports, in YYYY-MM-DD format. This should not be more than 60 days in the past. | string |
Bindings
Property | Title | Description | Type | Required/Default |
---|---|---|---|---|
/stream | Stream | Amazon Ads resource from which a collection is captured. | string | Required |
/syncMode | Sync Mode | Connection method. | string | Required |
Sample
This sample specification reflects the manual authentication method.
captures:
${PREFIX}/${CAPTURE_NAME}:
endpoint:
connector:
image: ghcr.io/estuary/source-amazon-ads:dev
config:
credentials:
auth_type: oauth2.0
client_id: amzn1.application-oa2-client.XXXXXXXXX
client_secret: <secret>
refresh_token: Atzr|XXXXXXXXXXXX
region: NA
report_generation_max_retries: 5
report_wait_timeout: 60
start_date: 2022-03-01
bindings:
- resource:
stream: profiles
syncMode: full_refresh
target: ${PREFIX}/profiles
{}