Skip to main content

Bing Ads

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

Setup guide​

Step 1: Set up Bing Ads​

  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.

  1. Get your Microsoft developer token.
  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 in to 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 your source.
  5. For Tenant ID, enter the custom tenant or use the common tenant.
  6. Add the developer token from Step 1.
  7. For 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.
  8. 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, let it with 0 default value.
  9. Click Authenticate your Bing Ads account.
  10. Log in and authorize the Bing Ads account.
  11. Click Set up source.

For Airbyte Open Source:

  1. Log in to your Airbyte Open Source 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 your source.
  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 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.
  8. 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, let it with 0 default value.
  9. 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​

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.

Performance considerations​

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

Build instructions​

Build your own connector image​

This connector is built using our dynamic built process. The base image used to build it is defined within the metadata.yaml file under the connectorBuildOptions. The build logic is defined using Dagger here. It does not rely on a Dockerfile.

If you would like to patch our connector and build your own a simple approach would be:

  1. Create your own Dockerfile based on the latest version of the connector image.
FROM airbyte/source-bing-ads:latest

COPY . ./airbyte/integration_code
RUN pip install ./airbyte/integration_code

# The entrypoint and default env vars are already set in the base image
# ENV AIRBYTE_ENTRYPOINT "python /airbyte/integration_code/main.py"
# ENTRYPOINT ["python", "/airbyte/integration_code/main.py"]

Please use this as an example. This is not optimized.

  1. Build your image:
docker build -t airbyte/source-bing-ads:dev .
# Running the spec command against your patched connector
docker run airbyte/source-bing-ads:dev spec

Customizing our build process​

When contributing on our connector you might need to customize the build process to add a system dependency or set an env var. You can customize our build process by adding a build_customization.py module to your connector. This module should contain a pre_connector_install and post_connector_install async function that will mutate the base image and the connector container respectively. It will be imported at runtime by our build process and the functions will be called if they exist.

Here is an example of a build_customization.py module:

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    # Feel free to check the dagger documentation for more information on the Container object and its methods.
    # https://dagger-io.readthedocs.io/en/sdk-python-v0.6.4/
    from dagger import Container


async def pre_connector_install(base_image_container: Container) -> Container:
    return await base_image_container.with_env_variable("MY_PRE_BUILD_ENV_VAR", "my_pre_build_env_var_value")

async def post_connector_install(connector_container: Container) -> Container:
    return await connector_container.with_env_variable("MY_POST_BUILD_ENV_VAR", "my_post_build_env_var_value")

Changelog​

VersionDatePull RequestSubject
1.0.12023-10-1331377Use our base image and remove Dockerfile
1.0.02023-10-1131277Remove primary keys from the geographic performance reports.
0.2.32023-09-2830834Wrap auth error with the config error.
0.2.22023-09-2730791Fix missing fields for geographic performance reports.
0.2.12023-09-0430128Add increasing download timeout if ReportingDownloadException occurs
0.2.02023-08-1727619Add Geographic Performance Report
0.1.242023-06-2227619Retry request after facing temporary name resolution error.
0.1.232023-05-1125996Implement a retry logic if SSL certificate validation fails.
0.1.222023-05-0824223Add CampaignLabels report column in campaign performance report
0.1.212023-04-2825668Add undeclared fields to accounts, campaigns, campaign_performance_report, keyword_performance_report and account_performance_report streams
0.1.202023-03-0923663Add lookback window for performance reports in incremental mode
0.1.192023-03-0823868Add dimensional-type columns for reports.
0.1.182023-01-3022073Fix null values in the Keyword column of keyword_performance_report streams
0.1.172022-12-1020005Add Keyword to keyword_performance_report stream
0.1.162022-10-1217873Fix: added missing campaign types in (Audience, Shopping and DynamicSearchAds) in campaigns stream
0.1.152022-10-0317505Fix: limit cache size for ServiceClient instances
0.1.142022-09-2917403Fix: limit cache size for ReportingServiceManager instances
0.1.132022-09-2917386Migrate to per-stream states.
0.1.122022-09-0516335Added backoff for socket.timeout
0.1.112022-08-2515684 (published in 15987)Fixed log messages being unreadable
0.1.102022-08-1215602Fixed bug caused Hourly Reports to crash due to invalid fields set
0.1.92022-08-0214862Added missing columns
0.1.82022-06-1513801All reports hourly/daily/weekly/monthly will be generated by default, these options are removed from input configuration
0.1.72022-05-1712937Added OAuth2.0 authentication method, removed redirect_uri from input configuration
0.1.62022-04-3012500Improve input configuration copy
0.1.52022-01-0111652Rebump attempt after DockerHub failure at registring the 0.1.4
0.1.42022-03-2211311Added optional Redirect URI & Tenant ID to spec
0.1.32022-01-149510Fixed broken dependency that blocked connector's operations
0.1.22021-12-148429Update titles and descriptions
0.1.12021-08-315750Added reporting streams)
0.1.02021-07-224911Initial release supported core streams (Accounts, Campaigns, Ads, AdGroups)
Was this page helpful?