# Amazon Ads Import Integration DSP Report This feature is in BETA version. For more information, contact your Customer Success Representative. This integration enables the configuration of Amazon Ads reports and allows you to ingest the content of those reports directly into Treasure Data. ## Prerequisites - Basic Knowledge of Treasure Data - Basic knowledge of Amazon Ads ## Requirements and Limitations - Amazon Ads report metrics and data are controlled by Amazon Ads. - This integration only triggers a report that is already configured in Amazon Ads. ## Static IP Address of Treasure Data The static IP address of Treasure Data is the access point and source of the linkage for this Integration. To determine the static IP address, contact your Customer Success representative or technical support. ## Import Amazon Ads reports via TD Console ### Create Authentication Your first step is to create a new authentication with a set of credentials. 1. Select **Integrations Hub**. 2. Select **Catalog**. ![](/assets/integrationshub-catalog2.e33c0a4c7d81c40cc83dd056c2143b97b1406220e213cab14ef349d69412ffef.eedebb45.png) 3. Search for your Amazon Ads in the Catalog; hover your mouse over the icon and select **Create Authentication**. ![](/assets/amazonadsreports.47e35c37addff2c44770ce8d6cba7ff45bff6e86a1aca99db90913b4d340c61e.eedebb45.png) 4. Ensure that the **Credentials** tab is selected and then enter the OAuth connection credential for the integration. 5. Select **Continue**. 6. Enter a name for your authentication, and then select **Done**. ### Create a Source After the authentication becomes available on the console, configure your import job. 1. Open TD Console. 2. Navigate to **Integrations** **Hub > Authentications**. 3. Locate your Amazon Ads authentication and select **New Source**. #### Connection Details | Parameter | Description | | --- | --- | | Data Transfer Name | Enter a name for your transfer. | | Authentication | The name of the authentication that will be used for a transfer. | #### Source Table | Parameter | Description | | --- | --- | | Data Type | Select DSP Report. Additional types may be available in the future. | | Profile Marketplace | Enter the two-character country code of the advertiser marketplace. | | Advertiser ID(s) | Enter a comma separated list of advertiser IDs for advertisers that you want to request data from. At least one ID must be specified. | | Report Type | From the drop-down menu, select a Report Type. For a description of report types see [Amazon Ads Report Types](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/overview). | | Group By | Enter a comma separated list of dimensions that your report should be grouped by. At least one dimension must be specified. The following dimensions are currently supported:- [campaign](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#group-by-campaign-5) - [ad](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#group-by-ad) - [creative](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#group-by-creative) | | Report Period | Select a predefined Report Period, or select **Custom** and enter start and end dates for the report. Start dates cannot be older than 90 days, and end date cannot be more than 31 days from the start date. For report period limitations see the Amazon DSP Column of the [Campaign Reports Configurations Table](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#configurations) for Amazon Ads. | | Time Unit | Select **Daily** or **Summary** depends on Report Type. The Daily option is only available if you have selected report type Campaign. | | Base Metric | Select the checkbox to include all the base metrics of the selected report type. List of base metrics is subject to change by Amazon Ads. TD attempts to keep the list updated, but TD cannot guarantee the latest set of metrics will be included. If you encounter an error with base metrics, use Custom Metrics. | | Custom Metrics | List of comma separated values that you can copy directly from [Amazon](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#base-metrics-5). If Amazon has exposed new metrics, you can specify those metrics here without having to perform a software update. For additional information see Amazon DSP [Base Metrics](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#base-metrics-5). This field can also be used in situations where you don't need all of the base metrics, but only want to specify particular metrics. | 1. Select **Next**. ![](/assets/screen-shot-2024-08-20-at-10.14.20.2165eb1e00483ed20dcc78b9765afbb080d06671dc87f7780534e2dd85d115d1.eedebb45.png) ### Data Preview You can see a [preview](/products/customer-data-platform/integration-hub/batch/import/previewing-your-source-data) of your data before running the import by selecting Generate Preview. Data preview is optional and you can safely skip to the next page of the dialog if you choose to. 1. Select **Next**. The Data Preview page opens. 2. If you want to preview your data, select **Generate Preview**. 3. Verify the data. ### Data Placement For data placement, select the target database and table where you want your data placed and indicate how often the import should run. 1. Select **Next.** Under Storage, you will create a new or select an existing database and create a new or select an existing table for where you want to place the imported data. 2. Select a **Database** > **Select an existing** or **Create New Database**. 3. Optionally, type a database name. 4. Select a **Table**> **Select an existing** or **Create New Table**. 5. Optionally, type a table name. 6. Choose the method for importing the data. - **Append** (default)-Data import results are appended to the table. If the table does not exist, it will be created. - **Always Replace**-Replaces the entire content of an existing table with the result output of the query. If the table does not exist, a new table is created. - **Replace on New Data**-Only replace the entire content of an existing table with the result output when there is new data. 7. Select the **Timestamp-based Partition Key** column. If you want to set a different partition key seed than the default key, you can specify the long or timestamp column as the partitioning time. As a default time column, it uses upload_time with the add_time filter. 8. Select the **Timezone** for your data storage. 9. Under **Schedule**, you can choose when and how often you want to run this query. #### Run once 1. Select **Off**. 2. Select **Scheduling Timezone**. 3. Select **Create & Run Now**. #### Repeat Regularly 1. Select **On**. 2. Select the **Schedule**. The UI provides these four options: *@hourly*, *@daily* and *@monthly* or custom *cron*. 3. You can also select **Delay Transfer** and add a delay of execution time. 4. Select **Scheduling Timezone**. 5. Select **Create & Run Now**. After your transfer has run, you can see the results of your transfer in **Data Workbench** > **Databases.** ## Import from Amazon Ads reports via Workflow You can import data from Amazon Ads reports via workflow using td_load>: src_id. If you have already created a source, you can run it; if you don't want to create a source, you can import it using a .yml file. ### Using a Source or YML File #### Using a Source 1. Select **Integrations Hub > Sources**. 2. On the Filters pane, select **Amazon Ads** from the Integration Type drop-down menu. 3. Select the ••• icon, and then select **Copy Unique ID**. ![](/assets/26617502.09d9b84b0f1f752c7c95b0bc1c2d8e8b7302e5b91c6a3cb5f01309dadf53a604.25ec5a77.png) 1. Define a workflow task using td_load>: sourceId ```yaml +load: td_load>: unique_id_of_your_source database: ${td.dest_db} table: ${td.dest_table} ``` 1. Run a workflow. #### Using a yml/yaml file 1. Identify your yml file. If you need to create the yml/yaml file, use the instructions found in [Create Seed Config File (seed.yml)](/int/amazon-s3-import-integration-v2#AmazonS3ImportIntegrationv2-CreateSeedConfigFile(seed.yml)) as a reference. 2. Define a workflow task using td_load>: <.yml file> ```yaml +load: td_load>: config/daily_load.yml database: ${td.dest_db} table: ${td.dest_table} ``` 1. Run a workflow. ### Sample Workflow Code Visit [Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td_load/s3) for a sample workflow code. ### Import from Amazon Ads via CLI (Toolbelt) Before setting up the integration, install the latest version of the [TD Toolbelt](https://toolbelt.treasuredata.com/). #### Create Seed Configuration File (seed.yml) ```yaml in: type: "amazon_ads" td_authentication_id: data_type: "DSP_REPORT" profile_marketplace: "US" advertiser_ids: "advertiser_id_comma_separated_values" report_type: "CAMPAIGN" group_by: "campaign, ad, creative" time_unit: "SUMMARY" report_period: CUSTOM start_date: "2024-05-05" end_date: "2024-05-31" base_metrics: true out: mode: append ``` #### Parameters Reference | Name | Description | Value | Default Value | Required | | --- | --- | --- | --- | --- | | type | The source of the import. | "amazon_ads" | | Yes | | td_authentication_id | The authentication ID for the Amazon Ads authentication in TD. Console. See [Getting the Authentication ID](/int/amazon-ads-export-integration#h4_66958132) for information on how to determine the value for this ID. | | | Yes | | profile_marketplace | The two-character country code of the advertiser marketplace specified in ISO 3166-1 alpha-2 format. | | | No | | advertiser_ids | A comma separated list of advertiser IDs for advertisers that you want to request data from. | | | Yes | | report_type | The report type to generate. | enums ["CAMPAIGN", "INVENTORY", "AUDIENCE", "PRODUCT", "TECHNOLOGY", "GEOGRAPHY", "AUDIO_AND_VIDEO"] | CAMPAIGN | Yes | | group_by | List of metrics your report should be grouped by. Allowable values depend on report type. | | | Yes | | time_unit | The time unit to be used when a report type is "CAMPAIGN". | enums ["DAILY", "SUMMARY"] | DAILY | Yes, if report_type is "CAMPAIGN" | | time_unit_summary | Report time unit, to be used when report type is not "CAMPAIGN". | enums ["SUMMARY"] SUMMARY | SUMMARY | Yes, if report_type is not "CAMPAIGN" | | report_period | The time frame for the report. | enums ["PREVIOUS_DAY", "PREVIOUS_7_DAYS", "CURRENT_WEEK", "PREVIOUS_WEEK", "PREVIOUS_30_DAYS", "CURRENT_MONTH", "PREVIOUS_MONTH", "CUSTOM"] | PREVIOUS DAY | Yes | | start_date | The start date of the report. | String. Format: yyyy-MM-dd | | Yes, if report_type is "CUSTOM". | | end_date | The end date of the report. | String. Format: yyyy-MM-dd | | Yes, if report_type is "CUSTOM". | | base_metrics | Specifies whether to include [base metrics](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#base-metrics-5) for each report_type. | TRUE/FALSE | TRUE | Yes | | custom_metrics | Custom metrics are listed as comma separated values. They can be copied directly from the [Amazon](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign#base-metrics-5). If Amazon has exposed new metrics, you can specify those metrics here without having to perform a software update. | | | | #### Generate load.yml Use connector:guess to generate the load.yml file. This command automatically reads the source files and makes a best guess at the file format and its fields and columns. ``` $ td connector:guess seed.yml -o load.yml ``` You can open the load.yml to review the file format definitions including file formats, encodings, column names, and types. #### Example load.yml ```yaml in: type: amazon_ads data_type: DSP_REPORT profile_marketplace: US advertiser_ids: '123123123123123' report_type: CAMPAIGN group_by: campaign, ad, creative time_unit: SUMMARY report_period: CUSTOM start_date: '2024-07-05' end_date: '2024-07-31' base_metrics: true td_authentication_id: out: {mode: append} exec: {}filters: - rules: - {rule: upper_to_lower} - pass_types: - a-z - 0-9 pass_characters: _ replace: _ rule: character_types - pass_types: - a-z pass_characters: _ prefix: _ rule: first_character_types - {rule: unique_number_suffix, max_length: 128} type: rename - from_value: {mode: upload_time} to_column: {name: time} type: add_time ``` To preview the data, use the `td connector:preview` command. ```bash td connector:preview ``` ### Execute the Load Job It might take a couple of hours, depending on the size of the data. Be sure to specify the Treasure Data database and table where the data should be stored.  Treasure Data also recommends specifying the --time-column option because Treasure Data’s storage is partitioned by time (see [data partitioning](https://docs.treasuredata.com/smart/project-product-documentation/data-partitioning-in-treasure-data)). If this option is not provided, the data connector chooses the first long or timestamp column as the partitioning time. The type of the column specified by --time-column must be either of long and timestamp type. If your data doesn’t have a time column, you can add a time column by using the *add_time* filter option. For more details see the documentation for the [add_time Filter Function](https://docs.treasuredata.com/smart/project-product-documentation/add_time-filter-function). ``` $ td connector:issue load.yml --database td_sample_db --table td_sample_table \--time-column created_at ``` The connector:issue command assumes that you have already created a database(td_sample_db) and a table(td_sample_table). If the database or the table does not exist in TD, this command fails. Create the database and table manually or use --auto-create-table option with td connector:issue command to auto-create the database and table. ``` $ td connector:issue load.yml --database td_sample_db --table td_sample_table--time-column created_at --auto-create-table ``` The data connector does not sort records on the server side. To use time-based partitioning effectively, sort records in files beforehand. If you have a field called time, you don’t have to specify the --time-column option. ``` $ td connector:issue load.yml --database td_sample_db --table td_sample_table ``` ### Import Modes Specify the file import mode in the out: section of the load.yml file. The out: section controls how data is imported into a Treasure Data table. For example, you may choose to append data or replace data in an existing table. | **Mode** | **Description** | **Examples** | | --- | --- | --- | | Append | Records are appended to the target table. | in:   ... out:   mode: append | | Always Replace | Replaces data in the target table. Any manual schema changes made to the target table remain intact. | in:   ... out:   mode: replace | | Replace on new data | Replaces data in the target table only when there is new data to import. | in:   ... out:   mode: replace_on_new_data | ## See Also For additional information about Amazon Ads Report V3, refer to the following Amazon documentation: - [Amazon Ads Report Types](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/overview) - [Amazon Ads API Reference Creating a Report Request](https://advertising.amazon.com/API/docs/en-us/offline-report-prod-3p#tag/Asynchronous-Reports/operation/createAsyncReport)