Changes for release v0_3. (#2)

ChangeLog

@@ -1,2 +1,5 @@
+* 0.2.0:
+- Google Ads v0_3 release.
+
 * 0.1.0:
 - Initial release with support for Google Ads API v0.

examples/v0/advanced_operations/add_ad_group_bid_modifiers.py

@@ -0,0 +1,87 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""This demonstrates how to add an ad group bid modifier for mobile devices.
+
+To get ad group bid modifiers, run get_ad_group_bid_modifiers.py
+"""
+
+from __future__ import absolute_import
+
+import argparse
+import six
+import sys
+
+import google.ads.google_ads.client
+
+
+def main(client, customer_id, ad_group_id, bid_modifier_value):
+    ad_group_service = client.get_service('AdGroupService')
+    ad_group_bm_service = client.get_service('AdGroupBidModifierService')
+
+    # Create ad group bid modifier for mobile devices with the specified ad
+    # group ID and bid modifier value.
+    ad_group_bid_modifier_operation = client.get_type(
+        'AdGroupBidModifierOperation')
+    ad_group_bid_modifier = ad_group_bid_modifier_operation.create
+
+    # Set the ad group.
+    ad_group_bid_modifier.ad_group.value = ad_group_service.ad_group_path(
+        customer_id, ad_group_id)
+
+    # Set the bid modifier.
+    ad_group_bid_modifier.bid_modifier.value = bid_modifier_value
+
+    # Sets the device.
+    ad_group_bid_modifier.device.type = client.get_type('DeviceEnum').MOBILE
+
+    # Add the ad group bid modifier.
+    try:
+        ad_group_bm_response = (
+            ad_group_bm_service.mutate_ad_group_bid_modifiers(
+                customer_id, [ad_group_bid_modifier_operation]))
+    except google.ads.google_ads.errors.GoogleAdsException as ex:
+        print('Request with ID "%s" failed with status "%s" and includes the '
+              'following errors:' % (ex.request_id, ex.error.code().name))
+        for error in ex.failure.errors:
+            print('\tError with message "%s".' % error.message)
+            if error.location:
+                for field_path_element in error.location.field_path_elements:
+                    print('\t\tOn field: %s' % field_path_element.field_name)
+        sys.exit(1)
+
+    print('Created ad group bid modifier: %s.'
+          % ad_group_bm_response.results[0].resource_name)
+
+
+if __name__ == '__main__':
+    # GoogleAdsClient will read a google-ads.yaml configuration file in the
+    # home directory if none is specified.
+    google_ads_client = (google.ads.google_ads.client.GoogleAdsClient
+                         .load_from_storage())
+
+    parser = argparse.ArgumentParser(
+        description=('Adds an ad group bid modifier to the specified ad group '
+                     'ID, for the given customer ID.'))
+    # The following argument(s) should be provided to run the example.
+    parser.add_argument('-c', '--customer_id', type=six.text_type,
+                        required=True, help='The AdWords customer ID.')
+    parser.add_argument('-a', '--ad_group_id', type=six.text_type,
+                        required=True, help='The ad group ID.')
+    parser.add_argument('-b', '--bid_modifier_value', type=float,
+                        required=False, default=1.5,
+                        help='The bid modifier value.')
+    args = parser.parse_args()
+
+    main(google_ads_client, args.customer_id, args.ad_group_id,
+         args.bid_modifier_value)

examples/v0/advanced_operations/create_and_attach_shared_keyword_sets.py

@@ -0,0 +1,125 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Demonstrates how to create a shared list of negative broad match keywords.
+
+Note that the keywords will be attached to the specified campaign.
+"""
+
+from __future__ import absolute_import
+
+import argparse
+import six
+import sys
+import uuid
+
+import google.ads.google_ads.client
+
+
+def main(client, customer_id, campaign_id):
+    campaign_service = client.get_service('CampaignService')
+    shared_set_service = client.get_service('SharedSetService')
+    shared_criterion_service = client.get_service('SharedCriterionService')
+    campaign_shared_set_service = client.get_service('CampaignSharedSetService')
+
+    # Create shared negative keyword set.
+    shared_set_operation = client.get_type('SharedSetOperation')
+    shared_set = shared_set_operation.create
+    shared_set.name.value = 'API Negative keyword list - %s' % uuid.uuid4()
+    shared_set.type = client.get_type('SharedSetTypeEnum').NEGATIVE_KEYWORDS
+
+    try:
+        shared_set_resource_name = shared_set_service.mutate_shared_sets(
+            customer_id, [shared_set_operation]).results[0].resource_name
+    except google.ads.google_ads.errors.GoogleAdsException as ex:
+        print('Request with ID "%s" failed with status "%s" and includes the '
+              'following errors:' % (ex.request_id, ex.error.code().name))
+        for error in ex.failure.errors:
+            print('\tError with message "%s".' % error.message)
+            if error.location:
+                for field_path_element in error.location.field_path_elements:
+                    print('\t\tOn field: %s' % field_path_element.field_name)
+        sys.exit(1)
+
+    print('Created shared set "%s".' % shared_set_resource_name)
+
+    # Keywords to create a shared set of.
+    keywords = ['mars cruise', 'mars hotels']
+
+    shared_criteria_operations = []
+    for keyword in keywords:
+        shared_criterion_operation = client.get_type('SharedCriterionOperation')
+        shared_criterion = shared_criterion_operation.create
+        keyword_info = shared_criterion.keyword
+        keyword_info.text.value = keyword
+        keyword_info.match_type = client.get_type('KeywordMatchTypeEnum').BROAD
+        shared_criterion.shared_set.value = shared_set_resource_name
+        shared_criteria_operations.append(shared_criterion_operation)
+
+    try:
+        response = shared_criterion_service.mutate_shared_criteria(
+            customer_id, shared_criteria_operations)
+    except google.ads.google_ads.errors.GoogleAdsException as ex:
+        print('Request with ID "%s" failed with status "%s" and includes the '
+              'following errors:' % (ex.request_id, ex.error.code().name))
+        for error in ex.failure.errors:
+            print('\tError with message "%s".' % error.message)
+            if error.location:
+                for field_path_element in error.location.field_path_elements:
+                    print('\t\tOn field: %s' % field_path_element.field_name)
+        sys.exit(1)
+
+    for shared_criterion in response.results:
+        print('Created shared criterion "%s".' % shared_criterion.resource_name)
+
+    campaign_set_operation = client.get_type('CampaignSharedSetOperation')
+    campaign_set = campaign_set_operation.create
+    campaign_set.campaign.value = campaign_service.campaign_path(
+        customer_id, campaign_id)
+    campaign_set.shared_set.value = shared_set_resource_name
+
+    try:
+        campaign_shared_set_resource_name = (
+            campaign_shared_set_service.mutate_campaign_shared_sets(
+                customer_id, [campaign_set_operation]).results[0].resource_name)
+    except google.ads.google_ads.errors.GoogleAdsException as ex:
+        print('Request with ID "%s" failed with status "%s" and includes the '
+              'following errors:' % (ex.request_id, ex.error.code().name))
+        for error in ex.failure.errors:
+            print('\tError with message "%s".' % error.message)
+            if error.location:
+                for field_path_element in error.location.field_path_elements:
+                    print('\t\tOn field: %s' % field_path_element.field_name)
+        sys.exit(1)
+
+    print('Created campaign shared set "%s".'
+          % campaign_shared_set_resource_name)
+
+
+if __name__ == '__main__':
+    # GoogleAdsClient will read a google-ads.yaml configuration file in the
+    # home directory if none is specified.
+    google_ads_client = (google.ads.google_ads.client.GoogleAdsClient
+                         .load_from_storage())
+
+    parser = argparse.ArgumentParser(
+        description=('Adds a list of negative broad match keywords to the '
+                     'provided campaign, for the specified customer.'))
+    # The following argument(s) should be provided to run the example.
+    parser.add_argument('-c', '--customer_id', type=six.text_type,
+                        required=True, help='The AdWords customer ID.')
+    parser.add_argument('-i', '--campaign_id', type=six.text_type,
+                        required=True, help='The campaign ID.')
+    args = parser.parse_args()
+
+    main(google_ads_client, args.customer_id, args.campaign_id)

examples/v0/advanced_operations/find_and_remove_criteria_from_shared_set.py

@@ -0,0 +1,137 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Demonstrates how to find and remove shared sets, and shared set criteria."""
+
+from __future__ import absolute_import
+
+import argparse
+import six
+import sys
+
+import google.ads.google_ads.client
+
+
+_DEFAULT_PAGE_SIZE = 1000
+
+
+def main(client, customer_id, page_size, campaign_id):
+    ga_service = client.get_service('GoogleAdsService')
+    shared_criterion_service = client.get_service('SharedCriterionService')
+
+    # First, retrieve all shared sets associated with the campaign.
+    shared_sets_query = (
+        'SELECT shared_set.id, shared_set.name FROM campaign_shared_set '
+        'WHERE campaign.id = %s' % campaign_id)
+
+    try:
+        shared_set_response = ga_service.search(
+            customer_id, query=shared_sets_query, page_size=page_size)
+    except google.ads.google_ads.errors.GoogleAdsException as ex:
+        print('Request with ID "%s" failed with status "%s" and includes the '
+              'following errors:' % (ex.request_id, ex.error.code().name))
+        for error in ex.failure.errors:
+            print('\tError with message "%s".' % error.message)
+            if error.location:
+                for field_path_element in error.location.field_path_elements:
+                    print('\t\tOn field: %s' % field_path_element.field_name)
+        sys.exit(1)
+
+    shared_set_ids = []
+    for row in shared_set_response:
+        shared_set = row.shared_set
+        shared_set_id = str(shared_set.id.value)
+        shared_set_ids.append(shared_set_id)
+        print('Campaign shared set ID "%s" and name "%s" was found.'
+              % (shared_set_id, shared_set.name.value))
+
+    # Next, retrieve shared criteria for all found shared sets.
+    shared_criteria_query = (
+        'SELECT shared_criterion.type, shared_criterion.keyword.text, '
+        'shared_criterion.keyword.match_type, shared_set.id '
+        'FROM shared_criterion WHERE shared_set.id IN (%s)'
+        % ', '.join(shared_set_ids))
+
+    try:
+        shared_criteria_response = ga_service.search(
+            customer_id, query=shared_criteria_query, page_size=page_size)
+    except google.ads.google_ads.errors.GoogleAdsException as ex:
+        print('Request with ID "%s" failed with status "%s" and includes the '
+              'following errors:' % (ex.request_id, ex.error.code().name))
+        for error in ex.failure.errors:
+            print('\tError with message "%s".' % error.message)
+            if error.location:
+                for field_path_element in error.location.field_path_elements:
+                    print('\t\tOn field: %s' % field_path_element.field_name)
+        sys.exit(1)
+
+    # Use the enum type to determine the enum name from the value.
+    keyword_match_type_enum = (
+        client.get_type('KeywordMatchTypeEnum').KeywordMatchType)
+
+    criterion_ids = []
+    for row in shared_criteria_response:
+        shared_criterion = row.shared_criterion
+        shared_criterion_resource_name = shared_criterion.resource_name
+        if (shared_criterion.type ==
+                client.get_type('CriterionTypeEnum').KEYWORD):
+            keyword = shared_criterion.keyword
+            print('Shared criterion with resource name "%s" for negative '
+                  'keyword with text "%s" and match type "%s" was found.'
+                  % (shared_criterion_resource_name, keyword.text.value,
+                     keyword_match_type_enum.Name(keyword.match_type)))
+        criterion_ids.append(shared_criterion_resource_name)
+
+    operations = []
+
+    # Finally, remove the criteria.
+    for criteria_id in criterion_ids:
+        shared_criterion_operation = client.get_type('SharedCriterionOperation')
+        shared_criterion_operation.remove = criteria_id
+        operations.append(shared_criterion_operation)
+
+    try:
+        response = shared_criterion_service.mutate_shared_criteria(
+            customer_id, operations)
+    except google.ads.google_ads.errors.GoogleAdsException as ex:
+        print('Request with ID "%s" failed with status "%s" and includes the '
+              'following errors:' % (ex.request_id, ex.error.code().name))
+        for error in ex.failure.errors:
+            print('\tError with message "%s".' % error.message)
+            if error.location:
+                for field_path_element in error.location.field_path_elements:
+                    print('\t\tOn field: %s' % field_path_element.field_name)
+        sys.exit(1)
+
+    for result in response.results:
+        print('Removed shared criterion "%s".' % result.resource_name)
+
+
+if __name__ == '__main__':
+    # GoogleAdsClient will read a google-ads.yaml configuration file in the
+    # home directory if none is specified.
+    google_ads_client = (google.ads.google_ads.client.GoogleAdsClient
+                         .load_from_storage())
+
+    parser = argparse.ArgumentParser(
+        description=('Finds shared sets, then finds and removes shared set '
+                     'criteria under them.'))
+    # The following argument(s) should be provided to run the example.
+    parser.add_argument('-c', '--customer_id', type=six.text_type,
+                        required=True, help='The AdWords customer ID.')
+    parser.add_argument('-i', '--campaign_id', type=six.text_type,
+                        required=True, help='The campaign ID.')
+    args = parser.parse_args()
+
+    main(google_ads_client, args.customer_id, _DEFAULT_PAGE_SIZE,
+         args.campaign_id)