Skip to content

Latest commit

 

History

History
143 lines (104 loc) · 8.2 KB

amazon-ads.md

File metadata and controls

143 lines (104 loc) · 8.2 KB

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:

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:

  1. Complete the Amazon Ads API onboarding process.

  2. Retrieve your client ID and client secret.

  3. Retrieve a refresh token.

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
       {}