tap-amazon-ads

This is a Singer tap that produces JSON-formatted data following the Singer spec.

This tap:

• Pulls raw data from the [Amazon_Ads API].

• Extracts the following resources:

  • Invoices

  • Portfolios

  • Profiles

  • SponsoredBrandsAdCreatives

  • SponsoredBrandsAdGroups

  • SponsoredBrandsAds

  • SponsoredBrandsBidRecommendations

  • SponsoredBrandsBudgetRulesCampaigns

  • SponsoredBrandsBudgetRules

  • SponsoredBrandsCampaignsBudgetRules

  • SponsoredBrandsCampaigns

  • SponsoredBrandsKeywords

  • SponsoredBrandsNegativeKeywords

  • SponsoredBrandsNegativeTargets

  • SponsoredBrandsProductTargets

  • SponsoredBrandsStoreAssets

  • SponsoredDisplayAdGroups

  • SponsoredDisplayBrandSafetyList

  • SponsoredDisplayBudgetRulesCampaigns

  • SponsoredDisplayBudgetRules

  • SponsoredDisplayCampaignsBudgetRules

  • SponsoredDisplayCampaigns

  • SponsoredDisplayCreatives

  • SponsoredDisplayNegativeTargetingClauses

  • SponsoredDisplayProductAds

  • SponsoredDisplayTargetings

  • SponsoredProductsAdGroups

  • SponsoredProductsAds

  • SponsoredProductsBudgetRules

  • SponsoredProductsCampaigns

  • SponsoredProductsKeywords

  • SponsoredProductsNegativeKeywords

• Outputs the schema for each resource

• Incrementally pulls data based on the input state

Streams

** invoices**

• Data Key = invoiceSummaries
• Primary keys: ['id']
• Replication strategy: INCREMENTAL

** portfolios**

• Data Key = portfolios
• Primary keys: ['portfolioId']
• Replication strategy: INCREMENTAL

** profiles**

• Primary keys: ['profileId']
• Replication strategy: FULL_TABLE

** sponsored_brands_ad_creatives**

• Data Key = creatives
• Primary keys: ['adId']
• Replication strategy: INCREMENTAL

** sponsored_brands_ad_groups**

• Data Key = adGroups
• Primary keys: ['adGroupId']
• Replication strategy: INCREMENTAL

** sponsored_brands_ads**

• Data Key = ads
• Primary keys: ['adId']
• Replication strategy: INCREMENTAL

** sponsored_brands_bid_recommendations**

• Primary keys: ['recommendationId']
• Replication strategy: FULL_TABLE

** sponsored_brands_budget_rules_campaigns**

• Data Key = associatedCampaigns
• Primary keys: ['campaignId']
• Replication strategy: FULL_TABLE

** sponsored_brands_budget_rules**

• Data Key = budgetRulesForAdvertiserResponse
• Primary keys: ['ruleId']
• Replication strategy: INCREMENTAL

** sponsored_brands_campaigns_budget_rules**

• Data Key = associatedRules
• Primary keys: ['ruleId']
• Replication strategy: INCREMENTAL

** sponsored_brands_campaigns**

• Data Key = campaigns
• Primary keys: ['campaignId']
• Replication strategy: INCREMENTAL

** sponsored_brands_keywords**

• Primary keys: ['keywordId']
• Replication strategy: FULL_TABLE

** sponsored_brands_negative_keywords**

• Primary keys: ['keywordId']
• Replication strategy: FULL_TABLE

** sponsored_brands_negative_targets**

• Data Key = negativeTargets
• Primary keys: ['targetId']
• Replication strategy: FULL_TABLE

** sponsored_brands_product_targets**

• Primary keys: ['targetId']
• Replication strategy: FULL_TABLE

** sponsored_brands_store_assets**

• Primary keys: ['assetID']
• Replication strategy: FULL_TABLE

** sponsored_display_ad_groups**

• Primary keys: ['adGroupId']
• Replication strategy: INCREMENTAL

** sponsored_display_brand_safety_list**

• Data Key = requestStatusList
• Primary keys: ['requestId']
• Replication strategy: FULL_TABLE

** sponsored_display_budget_rules_campaigns**

• Data Key = associatedCampaigns
• Primary keys: ['campaignId']
• Replication strategy: FULL_TABLE

** sponsored_display_budget_rules**

• Data Key = budgetRulesForAdvertiserResponse
• Primary keys: ['ruleId']
• Replication strategy: INCREMENTAL

** sponsored_display_campaigns_budget_rules**

• Data Key = associatedRules
• Primary keys: ['ruleId']
• Replication strategy: INCREMENTAL

** sponsored_display_campaigns**

• Primary keys: ['campaignId']
• Replication strategy: INCREMENTAL

** sponsored_display_creatives**

• Primary keys: ['creativeId']
• Replication strategy: FULL_TABLE

** sponsored_display_negative_targeting_clauses**

• Primary keys: ['targetId']
• Replication strategy: INCREMENTAL

** sponsored_display_product_ads**

• Primary keys: ['adId']
• Replication strategy: INCREMENTAL

** sponsored_display_targetings**

• Primary keys: ['targetId']
• Replication strategy: INCREMENTAL

** sponsored_products_ad_groups**

• Data Key = adGroups
• Primary keys: ['adGroupId']
• Replication strategy: INCREMENTAL

** sponsored_products_ads**

• Data Key = productAds
• Primary keys: ['adId']
• Replication strategy: INCREMENTAL

** sponsored_products_budget_rules**

• Data Key = budgetRulesForAdvertiserResponse
• Primary keys: ['ruleId']
• Replication strategy: INCREMENTAL

** sponsored_products_campaigns**

• Data Key = campaigns
• Primary keys: ['campaignId']
• Replication strategy: INCREMENTAL

** sponsored_products_keywords**

• Data Key = keywords
• Primary keys: ['keywordId']
• Replication strategy: INCREMENTAL

** sponsored_products_negative_keywords**

• Data Key = negativeKeywords
• Primary keys: ['keywordId']
• Replication strategy: INCREMENTAL

Authentication

Quick Start

1. Install

   Clone this repository, and then install using setup.py. We recommend using a virtualenv:

   > virtualenv -p python3 venv
   > source venv/bin/activate
   > python setup.py install
   OR
   > cd .../tap-amazon-ads
   > pip install -e .

2. Dependent libraries. The following dependent libraries were installed.

   > pip install singer-python
   > pip install target-stitch
   > pip install target-json
   

   • singer-tools
   • target-stitch

3. Create your tap's config.json file. The tap config file for this tap should include these entries:

   • start_date - the default value to use if no bookmark exists for an endpoint (rfc3339 date string)
   • user_agent (string, optional): Process and email for API logging purposes. Example: tap-amazon-ads <api_user_email@your_company.com>
   • request_timeout (integer, 300): Max time for which request should wait to get a response. Default request_timeout is 300 seconds.

   {
       ""
       "client_id": "the_client_id",
       "client_secret": "the_client_secret",
       "refresh_token": "the_refresh_token",
       "profiles": "0123456789",
       "start_date": "2019-01-01T00:00:00Z",
       "user_agent": "tap-amazon-ads <api_user_email@your_company.com>",
       "request_timeout": 300
   }

   Optionally, also create a state.json file. currently_syncing is an optional attribute used for identifying the last object to be synced in case the job is interrupted mid-stream. The next run would begin where the last job left off.

   {
       "currently_syncing": "engage",
       "bookmarks": {
           "export": "2019-09-27T22:34:39.000000Z",
           "funnels": "2019-09-28T15:30:26.000000Z",
           "revenue": "2019-09-28T18:23:53Z"
       }
   }

4. Run the Tap in Discovery Mode This creates a catalog.json for selecting objects/fields to integrate:

   tap-amazon-ads --config config.json --discover > catalog.json

   See the Singer docs on discovery mode here.

5. Run the Tap in Sync Mode (with catalog) and write out to state file.

   For Sync mode:

   > tap-amazon-ads --config tap_config.json --catalog catalog.json > state.json
   > tail -1 state.json > state.json.tmp && mv state.json.tmp state.json

   To load to json files to verify outputs:

   > tap-amazon-ads --config tap_config.json --catalog catalog.json | target-json > state.json
   > tail -1 state.json > state.json.tmp && mv state.json.tmp state.json

   To pseudo-load to Stitch Import API with dry run:

   > tap-amazon-ads --config tap_config.json --catalog catalog.json | target-stitch --config target_config.json --dry-run > state.json
   > tail -1 state.json > state.json.tmp && mv state.json.tmp state.json

6. Test the Tap

   While developing the amazon_ads tap, the following utilities were run in accordance with Singer.io best practices: Pylint to improve code quality.

   > pylint tap-amazon-ads -d missing-docstring -d logging-format-interpolation -d too-many-locals -d too-many-arguments

   Pylint test resulted in the following score:

   Your code has been rated at 9.67/10

   To check the tap.

   > tap-amazon-ads --config tap_config.json --catalog catalog.json | singer-check-tap > state.json
   > tail -1 state.json > state.json.tmp && mv state.json.tmp state.json

   Unit Tests

   Unit tests may be run with the following.

   python -m pytest --verbose
   

   Note, you may need to install test dependencies.

   pip install -e .'[dev]'
   

---

Copyright © 2019 Stitch