jprdonnelly/airbyte
1
0
Fork 0
mirror of synced 2025-12-21 11:01:41 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
baf4633ab8b51a55276115ea083837d8632fe217
airbyte/docs/integrations/sources/bing-ads.md

36 KiB
Raw Blame History

Bing Ads

This page contains the setup guide and reference information for the Bing Ads source connector.

Prerequisites

  • Microsoft Advertising account
  • Microsoft Developer Token

Setup guide

For Airbyte Open Source set up your application to get Client ID, Client Secret, Refresh Token

  1. Register your application in the Azure portal.
  2. Request user consent to get the authorization code.
  3. Use the authorization code to get a refresh token.

:::note

The refresh token expires in 90 days. Repeat the authorization process to get a new refresh token. The full authentication process described here. Please be sure to authenticate with the email (personal or work) that you used to sign in to the Bing ads/Microsoft ads platform. :::

Step 1: Set up Bing Ads

  1. Get your Microsoft developer token. To use Bing Ads APIs, you must have a developer token and valid user credentials. See Microsoft Advertising docs for more info.

    1. Sign in with Super Admin credentials at the Microsoft Advertising Developer Portal account tab.
    2. Choose the user that you want associated with the developer token. Typically an application only needs one universal token regardless how many users will be supported.
    3. Click on the Request Token button.

  2. If your OAuth app has a custom tenant, and you cannot use Microsoft’s recommended common tenant, use the custom tenant in the Tenant ID field when you set up the connector.

:::info

The tenant is used in the authentication URL, for example: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize

:::

Step 2: Set up the source connector in Airbyte

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Bing Ads from the Source type dropdown.
  4. Enter a name for the Bing Ads connector.
  5. For Tenant ID, enter the custom tenant or use the common tenant.
  6. Add the developer token from Step 1.
  7. For Account Names Predicates - see predicates in bing ads docs. Will be used to filter your accounts by specified operator and account name. You can use multiple predicates pairs. The Operator is a one of Contains or Equals. The Account Name is a value to compare Accounts Name field in rows by specified operator. For example, for operator=Contains and name=Dev, all accounts where name contains dev will be replicated. And for operator=Equals and name=Airbyte, all accounts where name is equal to Airbyte will be replicated. Account Name value is not case-sensitive.
  8. For Reports Replication Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data from previous and current calendar years.
  9. For Lookback window (also known as attribution or conversion window) enter the number of days to look into the past. If your conversion window has an hours/minutes granularity, round it up to the number of days exceeding. If you're not using performance report streams in incremental mode and Reports Start Date is not provided, let it with 0 default value.
  10. For Custom Reports - see custom reports section, list of custom reports object:
  11. For Report Name enter the name that you want for your custom report.
  12. For Reporting Data Object add the Bing Ads Reporting Object that you want to sync in the custom report.
  13. For Columns add list columns of Reporting Data Object that you want to see in the custom report.
  14. For Aggregation add time aggregation. See report aggregation section.
  15. Click Authenticate your Bing Ads account.
  16. Log in and authorize the Bing Ads account.
  17. Click Set up source.

For Airbyte Open Source:

  1. Navigate to the Airbyte Open Source dashboard.

  2. Click Sources and then click + New source.

  3. On the Set up the source page, select Bing Ads from the Source type dropdown.

  4. Enter a name for the Bing Ads connector.

  5. For Tenant ID, enter the custom tenant or use the common tenant.

  6. Enter the Client ID, Client Secret, Refresh Token, and Developer Token from Step 1.

  7. For Account Names Predicates - see predicates in bing ads docs. Will be used to filter your accounts by specified operator and account name. You can use multiple predicates pairs. The Operator is a one of Contains or Equals. The Account Name is a value to compare Accounts Name field in rows by specified operator. For example, for operator=Contains and name=Dev, all accounts where name contains dev will be replicated. And for operator=Equals and name=Airbyte, all accounts where name is equal to Airbyte will be replicated. Account Name value is not case-sensitive.

  8. For Reports Replication Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data from previous and current calendar years.

  9. For Lookback window (also known as attribution or conversion window) enter the number of days to look into the past. If your conversion window has an hours/minutes granularity, round it up to the number of days exceeding. If you're not using performance report streams in incremental mode and Reports Start Date is not provided, let it with 0 default value.

  10. For Custom Reports - see custom reports section:

  11. For Report Name enter the name that you want for your custom report.

  12. For Reporting Data Object add the Bing Ads Reporting Object that you want to sync in the custom report.

  13. For Columns add columns of Reporting Data Object that you want to see in the custom report.

  14. For Aggregation select time aggregation. See report aggregation section.

  15. Click Set up source.

Supported sync modes

The Bing Ads source connector supports the following sync modes:

Supported Streams

The Bing Ads source connector supports the following streams. For more information, see the Bing Ads API.

Basic streams

Report Streams

:::note

Be careful with removing fields that you don't want to sync in the Replication Stream Settings. Report will be generated by request with all fields in the Stream Schema. Removing fields from in the setting does not affect actual request for the report. The results of such a report can be not accurate due to not visible values in removed fields. If you faced this issue please use custom report, where you can define only that fields that you want to see in the report, and no other fields will be used in the request. :::

:::info

Ad Group Impression Performance Report, Geographic Performance Report, Account Impression Performance Report have user-defined primary key. This means that you can define your own primary key in Replication tab in your connection for these streams.

Example pk: Ad Group Impression Performance Report: composite pk - [AdGroupId, Status, TimePeriod, AccountId] Geographic Performance Report: composite pk - [AdGroupId, Country, State, MetroArea, City] Account Impression Performance Report: composite pk - [AccountName, AccountNumber, AccountId, TimePeriod]

Note: These are just examples, and you should consider your own data and needs in order to correctly define the primary key.

See more info about user-defined pk here.

:::

Entity-Relationship Diagram (ERD)

Custom Reports

You can build your own report by providing:

  • Report Name - name of the stream
  • Reporting Data Object - Bing Ads reporting data object that you can find here. All data object with ending ReportRequest can be used as data object in custom reports.
  • Columns - Reporting object columns that you want to sync. You can find it on ReportRequest data object page by clicking the ...ReportColumn link in Bing Ads docs. The report must include the Required Columns (you can find it under list of all columns of reporting object) at a minimum. As a general rule, each report must include at least one attribute column and at least one non-impression share performance statistics column. Be careful you can't add extra columns that not specified in Bing Ads docs and not all fields can be skipped.
  • Aggregation - Hourly, Daily, Weekly, Monthly, DayOfWeek, HourOfDay, WeeklyStartingMonday, Summary. See report aggregation.

Report aggregation

All reports synced by this connector can be aggregated using hourly, daily, weekly, or monthly time windows.

For example, if you select a report with daily aggregation, the report will contain a row for each day for the duration of the report. Each row will indicate the number of impressions recorded on that day.

A report's aggregation window is indicated in its name. For example, account_performance_report_hourly is the Account Performance Reported aggregated using an hourly window.

Limitations & Troubleshooting

Expand to see details about Bing Ads connector limitations and troubleshooting.

Connector limitations

Rate limiting

The Bing Ads API limits the number of requests for all Microsoft Advertising clients. You can find detailed info here.

Troubleshooting

  • Check out common troubleshooting issues for the Bing Ads source connector on our Airbyte Forum.

Changelog

Expand to review
Version Date Pull Request Subject
2.8.1 2024-10-28 47093 Update dependencies
2.8.0 2024-10-21 46991 Update CDK to v5
2.7.9 2024-10-12 46847 Update dependencies
2.7.8 2024-10-05 46504 Update dependencies
2.7.7 2024-09-28 46151 Update dependencies
2.7.6 2024-09-21 45512 Update dependencies
2.7.5 2024-09-07 45246 Update dependencies
2.7.4 2024-08-31 44276 Update dependencies
2.7.3 2024-08-12 43742 Update dependencies
2.7.2 2024-08-10 43591 Update dependencies
2.7.1 2024-08-03 43245 Update dependencies
2.7.0 2024-07-31 42548 Migrate to CDK v4.1.0
2.6.12 2024-07-27 42812 Update dependencies
2.6.11 2024-07-20 42360 Update dependencies
2.6.10 2024-07-13 41875 Update dependencies
2.6.9 2024-07-10 41383 Update dependencies
2.6.8 2024-07-09 41314 Update dependencies
2.6.7 2024-07-06 40906 Update dependencies
2.6.6 2024-07-05 34966 Add support for Performance Max campaigns.
2.6.5 2024-06-27 40585 Replaced deprecated AirbyteLogger with logging.Logger
2.6.4 2024-06-25 40457 Update dependencies
2.6.3 2024-06-22 40006 Update dependencies
2.6.2 2024-06-06 39177 [autopull] Upgrade base image to v1.2.2
2.6.1 2024-05-02 36632 Schema descriptions
2.6.0 2024-04-25 35878 Add missing fields in keyword_performance_report
2.5.0 2024-03-21 35891 Accounts stream: add TaxCertificate field to schema
2.4.0 2024-03-19 36267 Pin airbyte-cdk version to ^0
2.3.0 2024-03-05 35812 New streams: Audience Performance Report, Goals And Funnels Report, Product Dimension Performance Report.
2.2.0 2024-02-13 35201 New streams: Budget and Product Dimension Performance.
2.1.4 2024-02-12 35179 Manage dependencies with Poetry
2.1.3 2024-01-31 34712 Fix duplicated records for report-based streams
2.1.2 2024-01-09 34045 Speed up record transformation
2.1.1 2023-12-15 33500 Fix state setter when state was provided
2.1.0 2023-12-05 33095 Add account filtering
2.0.1 2023-11-16 32597 Fix start date parsing from stream state
2.0.0 2023-11-07 31995 Schema update for Accounts, Campaigns and Search Query Performance Report streams. Convert date and date-time fields to standard RFC3339
1.13.0 2023-11-13 32306 Add Custom reports and decrease backoff max tries number
1.12.1 2023-11-10 32422 Normalize numeric values in reports
1.12.0 2023-11-09 32340 Remove default start date in favor of Time Period - Last Year and This Year, if start date is not provided
1.11.0 2023-11-06 32201 Skip broken CSV report files
1.10.0 2023-11-06 32148 Add new fields to stream Ads: "BusinessName", "CallToAction", "Headline", "Images", "Videos", "Text"
1.9.0 2023-11-03 32131 Add "CampaignId", "AccountId", "CustomerId" fields to Ad Groups, Ads and Campaigns streams.
1.8.0 2023-11-02 32059 Add new streams CampaignImpressionPerformanceReport (daily, hourly, weekly, monthly)
1.7.1 2023-11-02 32088 Raise config error when user does not have accounts
1.7.0 2023-11-01 32027 Add new streams AdGroupImpressionPerformanceReport
1.6.0 2023-10-31 32008 Add new streams Keywords
1.5.0 2023-10-30 31952 Add new streams Labels, App install ads, Keyword Labels, Campaign Labels, App Install Ad Labels, Ad Group Labels
1.4.0 2023-10-27 31885 Add new stream: AccountImpressionPerformanceReport (daily, hourly, weekly, monthly)
1.3.0 2023-10-26 31837 Add new stream: UserLocationPerformanceReport (daily, hourly, weekly, monthly)
1.2.0 2023-10-24 31783 Add new stream: SearchQueryPerformanceReport (daily, hourly, weekly, monthly)
1.1.0 2023-10-24 31712 Add new stream: AgeGenderAudienceReport (daily, hourly, weekly, monthly)
1.0.2 2023-10-19 31599 Base image migration: remove Dockerfile and use the python-connector-base image
1.0.1 2023-10-16 31432 Remove primary keys from the geographic performance reports - complete what was missed in version 1.0.0
1.0.0 2023-10-11 31277 Remove primary keys from the geographic performance reports
0.2.3 2023-09-28 30834 Wrap auth error with the config error
0.2.2 2023-09-27 30791 Fix missing fields for geographic performance reports
0.2.1 2023-09-04 30128 Add increasing download timeout if ReportingDownloadException occurs
0.2.0 2023-08-17 27619 Add Geographic Performance Report
0.1.24 2023-06-22 27619 Retry request after facing temporary name resolution error
0.1.23 2023-05-11 25996 Implement a retry logic if SSL certificate validation fails
0.1.22 2023-05-08 24223 Add CampaignLabels report column in campaign performance report
0.1.21 2023-04-28 25668 Add undeclared fields to accounts, campaigns, campaign_performance_report, keyword_performance_report and account_performance_report streams
0.1.20 2023-03-09 23663 Add lookback window for performance reports in incremental mode
0.1.19 2023-03-08 23868 Add dimensional-type columns for reports
0.1.18 2023-01-30 22073 Fix null values in the Keyword column of keyword_performance_report streams
0.1.17 2022-12-10 20005 Add Keyword to keyword_performance_report stream
0.1.16 2022-10-12 17873 Fix: added missing campaign types in (Audience, Shopping and DynamicSearchAds) in campaigns stream
0.1.15 2022-10-03 17505 Fix: limit cache size for ServiceClient instances
0.1.14 2022-09-29 17403 Fix: limit cache size for ReportingServiceManager instances
0.1.13 2022-09-29 17386 Migrate to per-stream states
0.1.12 2022-09-05 16335 Added backoff for socket.timeout
0.1.11 2022-08-25 15684 (published in 15987) Fixed log messages being unreadable
0.1.10 2022-08-12 15602 Fixed bug caused Hourly Reports to crash due to invalid fields set
0.1.9 2022-08-02 14862 Added missing columns
0.1.8 2022-06-15 13801 All reports hourly/daily/weekly/monthly will be generated by default, these options are removed from input configuration
0.1.7 2022-05-17 12937 Added OAuth2.0 authentication method, removed redirect_uri from input configuration
0.1.6 2022-04-30 12500 Improve input configuration copy
0.1.5 2022-01-01 11652 Rebump attempt after DockerHub failure at registring the 0.1.4
0.1.4 2022-03-22 11311 Added optional Redirect URI & Tenant ID to spec
0.1.3 2022-01-14 9510 Fixed broken dependency that blocked connector's operations
0.1.2 2021-12-14 8429 Update titles and descriptions
0.1.1 2021-08-31 5750 Added reporting streams
0.1.0 2021-07-22 4911 Initial release supported core streams (Accounts, Campaigns, Ads, AdGroups)
Reference in New Issue View Git Blame Copy Permalink