📚 Source Google Ads: Update documentation and clarify spec descriptio…

…ns (#11301)
airbytehq · Mar 24, 2022 · 89e0e78 · 89e0e78
1 parent 05b816d
commit 89e0e78
Show file tree

Hide file tree

Showing 5 changed files with 27 additions and 20 deletions.
diff --git 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
@@ -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 <a href=\"https://developers.google.com/google-ads/api/fields/v8/overview_query_builder\"\
+                  >query builder</a> 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 <a href=\"https://support.google.com/google-ads/answer/3123169?hl=en\"\
+            >documentation</a>."
           minimum: 0
           maximum: 1095
           default: 14

diff --git 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
@@ -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,14 +77,15 @@
       "custom_queries": {
         "type": "array",
         "title": "Custom GAQL Queries (Optional)",
+        "description": "",
         "order": 3,
         "items": {
           "type": "object",
           "properties": {
             "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 <a href=\"https://developers.google.com/google-ads/api/fields/v8/overview_query_builder\">query builder</a> 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 <a href=\"https://support.google.com/google-ads/answer/3123169?hl=en\">documentation</a>.",
         "minimum": 0,
         "maximum": 1095,
         "default": 14,

diff --git 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`                                              |
-