diff --git a/airbyte-config/init/src/main/resources/seed/source_definitions.yaml b/airbyte-config/init/src/main/resources/seed/source_definitions.yaml index 80cdcb24ab34..14f30e824b39 100644 --- a/airbyte-config/init/src/main/resources/seed/source_definitions.yaml +++ b/airbyte-config/init/src/main/resources/seed/source_definitions.yaml @@ -266,7 +266,7 @@ - name: Google Ads sourceDefinitionId: 253487c0-2246-43ba-a21f-5116b20a2c50 dockerRepository: airbyte/source-google-ads - dockerImageTag: 0.1.30 + dockerImageTag: 0.1.31 documentationUrl: https://docs.airbyte.io/integrations/sources/google-ads icon: google-adwords.svg sourceType: api diff --git a/airbyte-config/init/src/main/resources/seed/source_specs.yaml b/airbyte-config/init/src/main/resources/seed/source_specs.yaml index 11f5ef8b06fd..9793433c2bf7 100644 --- a/airbyte-config/init/src/main/resources/seed/source_specs.yaml +++ b/airbyte-config/init/src/main/resources/seed/source_specs.yaml @@ -2530,7 +2530,7 @@ supportsNormalization: false supportsDBT: false supported_destination_sync_modes: [] -- dockerImage: "airbyte/source-google-ads:0.1.30" +- dockerImage: "airbyte/source-google-ads:0.1.31" spec: documentationUrl: "https://docs.airbyte.com/integrations/sources/google-ads" connectionSpecification: @@ -2545,6 +2545,7 @@ properties: credentials: type: "object" + description: "" title: "Google Credentials" order: 0 required: @@ -2610,7 +2611,7 @@ order: 2 end_date: type: "string" - title: "End Date" + title: "End Date (Optional)" description: "UTC date and time in the format 2017-01-25. Any data after\ \ this date will not be replicated." pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" @@ -2620,6 +2621,7 @@ custom_queries: type: "array" title: "Custom GAQL Queries (Optional)" + description: "" order: 3 items: type: "object" @@ -2628,8 +2630,9 @@ type: "string" title: "Custom Query" description: "A custom defined GAQL query for building the report.\ - \ Should not contain segments.date expression as it used by incremental\ - \ streams" + \ Should not contain segments.date expression because it is used\ + \ by incremental streams. See Google's query builder for more information." examples: - "SELECT segments.ad_destination_type, campaign.advertising_channel_sub_type\ \ FROM campaign WHERE campaign.status = 'PAUSED'" @@ -2655,7 +2658,9 @@ type: "integer" description: "A conversion window is the period of time after an ad interaction\ \ (such as an ad click or video view) during which a conversion, such\ - \ as a purchase, is recorded in Google Ads." + \ as a purchase, is recorded in Google Ads. For more information, see\ + \ Google's documentation." minimum: 0 maximum: 1095 default: 14 diff --git a/airbyte-integrations/connectors/source-google-ads/Dockerfile b/airbyte-integrations/connectors/source-google-ads/Dockerfile index e5c2ce2822aa..4a40dbdc7ff1 100644 --- a/airbyte-integrations/connectors/source-google-ads/Dockerfile +++ b/airbyte-integrations/connectors/source-google-ads/Dockerfile @@ -13,5 +13,5 @@ RUN pip install . ENTRYPOINT ["python", "/airbyte/integration_code/main.py"] -LABEL io.airbyte.version=0.1.30 +LABEL io.airbyte.version=0.1.31 LABEL io.airbyte.name=airbyte/source-google-ads diff --git a/airbyte-integrations/connectors/source-google-ads/source_google_ads/spec.json b/airbyte-integrations/connectors/source-google-ads/source_google_ads/spec.json index 8a9304e1f8d8..c9b0c87b9253 100644 --- a/airbyte-integrations/connectors/source-google-ads/source_google_ads/spec.json +++ b/airbyte-integrations/connectors/source-google-ads/source_google_ads/spec.json @@ -9,6 +9,7 @@ "properties": { "credentials": { "type": "object", + "description": "", "title": "Google Credentials", "order": 0, "required": [ @@ -67,7 +68,7 @@ }, "end_date": { "type": "string", - "title": "End Date", + "title": "End Date (Optional)", "description": "UTC date and time in the format 2017-01-25. Any data after this date will not be replicated.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "examples": ["2017-01-30"], @@ -76,6 +77,7 @@ "custom_queries": { "type": "array", "title": "Custom GAQL Queries (Optional)", + "description": "", "order": 3, "items": { "type": "object", @@ -83,7 +85,7 @@ "query": { "type": "string", "title": "Custom Query", - "description": "A custom defined GAQL query for building the report. Should not contain segments.date expression as it used by incremental streams", + "description": "A custom defined GAQL query for building the report. Should not contain segments.date expression because it is used by incremental streams. See Google's query builder for more information.", "examples": [ "SELECT segments.ad_destination_type, campaign.advertising_channel_sub_type FROM campaign WHERE campaign.status = 'PAUSED'" ] @@ -107,7 +109,7 @@ "conversion_window_days": { "title": "Conversion Window (Optional)", "type": "integer", - "description": "A conversion window is the period of time after an ad interaction (such as an ad click or video view) during which a conversion, such as a purchase, is recorded in Google Ads.", + "description": "A conversion window is the period of time after an ad interaction (such as an ad click or video view) during which a conversion, such as a purchase, is recorded in Google Ads. For more information, see Google's documentation.", "minimum": 0, "maximum": 1095, "default": 14, diff --git a/docs/integrations/sources/google-ads.md b/docs/integrations/sources/google-ads.md index 4b7fa71748e3..14570b2f9f08 100644 --- a/docs/integrations/sources/google-ads.md +++ b/docs/integrations/sources/google-ads.md @@ -17,7 +17,7 @@ If you don't already have a developer token from Google Ads, make sure you follo This source is capable of syncing the following tables and their data: -#### Main Tables +### Main Tables * [accounts](https://developers.google.com/google-ads/api/fields/v8/customer) * [ad\_group\_ads](https://developers.google.com/google-ads/api/fields/v8/ad_group_ad) @@ -32,17 +32,18 @@ This source is capable of syncing the following tables and their data: Note that `ad_groups`, `ad_group_ads`, and `campaigns` contain a `labels` field, which should be joined against their respective `*_labels` streams if you want to view the actual labels. For example, the `ad_groups` stream contains an `ad_group.labels` field, which you would join against the `ad_group_labels` stream's `label.resource_name` field. -#### Report Tables +### Report Tables * [account\_performance\_report](https://developers.google.com/google-ads/api/docs/migration/mapping#account_performance) * [ad\_group\_ad\_report](https://developers.google.com/google-ads/api/docs/migration/mapping#ad_performance) * [display\_keyword\_report](https://developers.google.com/google-ads/api/docs/migration/mapping#display_keyword_performance) * [display\_topics\_report](https://developers.google.com/google-ads/api/docs/migration/mapping#display_topics_performance) * [shopping\_performance\_report](https://developers.google.com/google-ads/api/docs/migration/mapping#shopping_performance) +* [user_location_report](https://developers.google.com/google-ads/api/fields/v8/user_location_view) **Note**: Due to constraints from the Google Ads API, the `click_view` stream retrieves data one day at a time and can only retrieve data newer than 90 days ago -**Note**: Due to constraints from the Google Ads API, [metrics](https://developers.google.com/google-ads/api/fields/v8/metrics) cannot be requested for a manager account. Therefore, report streams are only available when pulling data from a non-manager account. +**Note**: Due to constraints from the Google Ads API, [metrics](https://developers.google.com/google-ads/api/fields/v8/metrics) cannot be requested for a manager account. Therefore, report streams are only available when pulling data from a non-manager account. **Note**: For incremental streams data is synced up to the previous day using your Google Ads account time zone. The reason is that Google Ads can filter data only by [date](https://developers.google.com/google-ads/api/fields/v8/ad_group_ad#segments.date) without time. Also, some report cannot load data in real time due to Google Ads [limitations](https://support.google.com/google-ads/answer/2544985?hl=en). @@ -56,10 +57,11 @@ Note that `ad_groups`, `ad_group_ads`, and `campaigns` contain a `labels` field, ## Getting Started \(Airbyte Open-Source\) -#### Requirements +### Requirements -Google Ads Account with an approved Developer Token \(note: In order to get API access to Google Ads, you must have a "manager" account. This must be created separately from your standard account. You can find more information about this distinction in the [google ads docs](https://ads.google.com/home/tools/manager-accounts/).\) +Google Ads Account with an approved Developer Token. \(note: In order to get API access to Google Ads, you must have a "manager" account; standard accounts cannot generate a Developer Token. This manager account must be created separately from your standard account. You can find more information about this distinction in the [Google Ads docs](https://support.google.com/google-ads/answer/6139186).\) +You'll need to find these values. See the [setup guide](#setup-guide) for instructions. * developer\_token * client\_id * client\_secret @@ -68,7 +70,7 @@ Google Ads Account with an approved Developer Token \(note: In order to get API * customer\_id * login\_customer\_id \(you can find more information about this field in [Google Ads docs](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid)\) -#### Setup guide +### Setup guide This guide will provide information as if starting from scratch. Please skip over any steps you have already completed. @@ -92,11 +94,9 @@ When you apply for a token, you need to mention: * That you have full access to the code base \(because we're open source\) * That you have full access to the server running the code \(because you're self-hosting Airbyte\) -If for any reason the request gets denied, let us know and we will be able to unblock you. - #### Understanding Google Ads Query Language -The Google Ads Query Language can query the Google Ads API. Check out [Google Ads Query Language](https://developers.google.com/google-ads/api/docs/query/overview) +The Google Ads Query Language can query the Google Ads API. Check out [Google Ads Query Language](https://developers.google.com/google-ads/api/docs/query/overview) and the [query builder](https://developers.google.com/google-ads/api/docs/query/overview). You can add these as custom queries when configuring the Google Ads source. ## Rate Limiting & Performance Considerations \(Airbyte Open Source\) @@ -106,6 +106,7 @@ This source is constrained by whatever API limits are set for the Google Ads tha | Version | Date | Pull Request | Subject | |:---------|:-----------| :--- |:---------------------------------------------------------------------------------------------| +| `0.1.31` | 2022-03-23 | [11301](https://github.com/airbytehq/airbyte/pull/11301) | Update docs and spec to clarify usage | | `0.1.30` | 2022-03-23 | [11221](https://github.com/airbytehq/airbyte/pull/11221) | Add `*_labels` streams to fetch the label text rather than their IDs | | `0.1.29` | 2022-03-22 | [10919](https://github.com/airbytehq/airbyte/pull/10919) | Fix user location report schema and add to acceptance tests | | `0.1.28` | 2022-02-25 | [10372](https://github.com/airbytehq/airbyte/pull/10372) | Add network fields to click view stream | @@ -134,4 +135,3 @@ This source is constrained by whatever API limits are set for the Google Ads tha | `0.1.3` | 2021-07-23 | [\#4788](https://github.com/airbytehq/airbyte/pull/4788) | Support main streams, fix bug with exception `DATE_RANGE_TOO_NARROW` for incremental streams | | `0.1.2` | 2021-07-06 | [\#4539](https://github.com/airbytehq/airbyte/pull/4539) | Add `AIRBYTE_ENTRYPOINT` for Kubernetes support | | `0.1.1` | 2021-06-23 | [\#4288](https://github.com/airbytehq/airbyte/pull/4288) | `Bugfix: Correctly declare required parameters` | -