Changes for release v1_0. (#42)

ChangeLog

@@ -1,3 +1,9 @@
+* 1.0.0:
+- Google Ads v1_0 release.
+- Move examples out of v0 directory.
+- Add dismiss_recommendations example.
+- Add get_hotel_ads_performance example.
+
 * 0.7.0:
 - Google Ads v0_7 release.
 - Address inconsistent exception handling in Exception and Logging

README.rst

@@ -70,6 +70,24 @@ retrieve the corresponding service client instance:
 
   google_ads_service = client.get_service('GoogleAdsService')
 
+API versioning
+################################
+With the release of Google Ads API v1_0 it's now possible to specify an API
+version when getting services and types. The ``get_service`` and ``get_type``
+client methods accept a second named parameter, ``version`` that refers to a
+valid API version. For example, to request an instance of the
+``GoogleAdsService`` that uses Google Ads API version ``v0`` use the
+following:
+
+.. code-block:: python
+
+  google_ads_service = client.get_service('GoogleAdsService', version='v0')
+
+The currently available list of versions is:
+
+* ``'v0'``
+* ``'v1'``
+
 Enabling and Configuring logging
 ################################
 The library uses Python's built in logging framework. You can specify your

examples/v0/account_management/create_customer.py → examples/account_management/create_customer.py

@@ -30,8 +30,8 @@
 
 
 def main(client, manager_customer_id):
-    customer_service = client.get_service('CustomerService')
-    customer = client.get_type('Customer')
+    customer_service = client.get_service('CustomerService', version='v1')
+    customer = client.get_type('Customer', version='v1')
     today = datetime.today().strftime('%Y%m%d %H:%M:%S')
     customer.descriptive_name.value = ('Account created with '
                                        'CustomerService on %s' % today)

examples/v0/account_management/get_accessible_customers.py → examples/account_management/get_accessible_customers.py

@@ -27,7 +27,7 @@
 
 
 def main(client):
-    customer_service = client.get_service('CustomerService')
+    customer_service = client.get_service('CustomerService', version='v1')
 
     try:
         accessible_customers = customer_service.list_accessible_customers()

examples/v0/account_management/get_account_changes.py → examples/account_management/get_account_changes.py

@@ -58,7 +58,7 @@ def resource_name_for_resource_type(resource_type, row):
 
 
 def main(client, customer_id):
-  ads_service = client.get_service('GoogleAdsService')
+  ads_service = client.get_service('GoogleAdsService', version='v1')
   query = ('SELECT change_status.resource_name, '
            'change_status.last_change_date_time, '
            'change_status.resource_type, '
@@ -75,10 +75,10 @@ def main(client, customer_id):
   response = ads_service.search(customer_id, query=query,
                                 page_size=ADS_PAGE_SIZE)
 
-  resource_type_enum = (client.get_type('ChangeStatusResourceTypeEnum')
-                        .ChangeStatusResourceType)
-  change_status_operation_enum = (client.get_type('ChangeStatusOperationEnum')
-                                  .ChangeStatusOperation)
+  resource_type_enum = (client.get_type(
+      'ChangeStatusResourceTypeEnum', version='v1').ChangeStatusResourceType)
+  change_status_operation_enum = (client.get_type(
+      'ChangeStatusOperationEnum', version='v1').ChangeStatusOperation)
 
   try:
     for row in response:

examples/v0/account_management/get_account_information.py → examples/account_management/get_account_information.py

@@ -26,7 +26,7 @@
 
 
 def main(client, customer_id):
-    customer_service = client.get_service('CustomerService')
+    customer_service = client.get_service('CustomerService', version='v1')
 
     resource_name = customer_service.customer_path(customer_id)
 

examples/v0/advanced_operations/add_ad_group_bid_modifiers.py → examples/advanced_operations/add_ad_group_bid_modifiers.py

@@ -26,8 +26,9 @@
 
 
 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')
+    ad_group_service = client.get_service('AdGroupService', version='v1')
+    ad_group_bm_service = client.get_service('AdGroupBidModifierService',
+                                             version='v1')
 
     # Create ad group bid modifier for mobile devices with the specified ad
     # group ID and bid modifier value.
@@ -43,7 +44,8 @@ def main(client, customer_id, ad_group_id, bid_modifier_value):
     ad_group_bid_modifier.bid_modifier.value = bid_modifier_value
 
     # Sets the device.
-    ad_group_bid_modifier.device.type = client.get_type('DeviceEnum').MOBILE
+    ad_group_bid_modifier.device.type = client.get_type('DeviceEnum',
+                                                        version='v1').MOBILE
 
     # Add the ad group bid modifier.
     try:

examples/v0/advanced_operations/add_expanded_text_ad_with_upgraded_urls.py → examples/advanced_operations/add_expanded_text_ad_with_upgraded_urls.py

@@ -23,15 +23,16 @@
 
 
 def main(client, customer_id, ad_group_id):
-    ad_group_ad_service = client.get_service('AdGroupAdService')
-    ad_group_service = client.get_service('AdGroupService')
+    ad_group_ad_service = client.get_service('AdGroupAdService', version='v1')
+    ad_group_service = client.get_service('AdGroupService', version='v1')
 
     # Create ad group ad.
-    ad_group_ad_operation = client.get_type('AdGroupAdOperation')
+    ad_group_ad_operation = client.get_type('AdGroupAdOperation', version='v1')
     ad_group_ad = ad_group_ad_operation.create
     ad_group_ad.ad_group.value = ad_group_service.ad_group_path(
         customer_id, ad_group_id)
-    ad_group_ad.status = client.get_type('AdGroupAdStatusEnum').PAUSED
+    ad_group_ad.status = client.get_type('AdGroupAdStatusEnum',
+                                         version='v1').PAUSED
 
     # Set expanded text ad info
     final_url = ad_group_ad.ad.final_urls.add()

examples/v0/advanced_operations/create_and_attach_shared_keyword_sets.py → examples/advanced_operations/create_and_attach_shared_keyword_sets.py

@@ -27,16 +27,19 @@
 
 
 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')
+    campaign_service = client.get_service('CampaignService', version='v1')
+    shared_set_service = client.get_service('SharedSetService', version='v1')
+    shared_criterion_service = client.get_service('SharedCriterionService',
+                                                  version='v1')
+    campaign_shared_set_service = client.get_service('CampaignSharedSetService',
+                                                     version='v1')
 
     # Create shared negative keyword set.
-    shared_set_operation = client.get_type('SharedSetOperation')
+    shared_set_operation = client.get_type('SharedSetOperation', version='v1')
     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
+    shared_set.type = client.get_type('SharedSetTypeEnum',
+                                      version='v1').NEGATIVE_KEYWORDS
 
     try:
         shared_set_resource_name = shared_set_service.mutate_shared_sets(
@@ -58,11 +61,13 @@ def main(client, customer_id, campaign_id):
 
     shared_criteria_operations = []
     for keyword in keywords:
-        shared_criterion_operation = client.get_type('SharedCriterionOperation')
+        shared_criterion_operation = client.get_type('SharedCriterionOperation',
+                                                     version='v1')
         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
+        keyword_info.match_type = client.get_type('KeywordMatchTypeEnum',
+                                                  version='v1').BROAD
         shared_criterion.shared_set.value = shared_set_resource_name
         shared_criteria_operations.append(shared_criterion_operation)
 
@@ -82,7 +87,8 @@ def main(client, customer_id, campaign_id):
     for shared_criterion in response.results:
         print('Created shared criterion "%s".' % shared_criterion.resource_name)
 
-    campaign_set_operation = client.get_type('CampaignSharedSetOperation')
+    campaign_set_operation = client.get_type('CampaignSharedSetOperation',
+                                             version='v1')
     campaign_set = campaign_set_operation.create
     campaign_set.campaign.value = campaign_service.campaign_path(
         customer_id, campaign_id)

examples/v0/advanced_operations/find_and_remove_criteria_from_shared_set.py → examples/advanced_operations/find_and_remove_criteria_from_shared_set.py

@@ -26,8 +26,9 @@
 
 
 def main(client, customer_id, page_size, campaign_id):
-    ga_service = client.get_service('GoogleAdsService')
-    shared_criterion_service = client.get_service('SharedCriterionService')
+    ga_service = client.get_service('GoogleAdsService', version='v1')
+    shared_criterion_service = client.get_service('SharedCriterionService',
+                                                  version='v1')
 
     # First, retrieve all shared sets associated with the campaign.
     shared_sets_query = (
@@ -77,14 +78,14 @@ def main(client, customer_id, page_size, campaign_id):
 
     # Use the enum type to determine the enum name from the value.
     keyword_match_type_enum = (
-        client.get_type('KeywordMatchTypeEnum').KeywordMatchType)
+        client.get_type('KeywordMatchTypeEnum', version='v1').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):
+                client.get_type('CriterionTypeEnum', version='v1').KEYWORD):
             keyword = shared_criterion.keyword
             print('Shared criterion with resource name "%s" for negative '
                   'keyword with text "%s" and match type "%s" was found.'
@@ -96,7 +97,8 @@ def main(client, customer_id, page_size, campaign_id):
 
     # Finally, remove the criteria.
     for criteria_id in criterion_ids:
-        shared_criterion_operation = client.get_type('SharedCriterionOperation')
+        shared_criterion_operation = client.get_type('SharedCriterionOperation',
+                                                     version='v1')
         shared_criterion_operation.remove = criteria_id
         operations.append(shared_criterion_operation)
 

examples/v0/advanced_operations/get_ad_group_bid_modifiers.py → examples/advanced_operations/get_ad_group_bid_modifiers.py

@@ -25,7 +25,7 @@
 
 
 def main(client, customer_id, page_size, ad_group_id=None):
-    ga_service = client.get_service('GoogleAdsService')
+    ga_service = client.get_service('GoogleAdsService', version='v1')
 
     query = ('SELECT campaign.id, ad_group.id, '
              'ad_group_bid_modifier.criterion_id, '
@@ -38,7 +38,7 @@ def main(client, customer_id, page_size, ad_group_id=None):
     results = ga_service.search(customer_id, query=query, page_size=page_size)
 
     # Use the enum type to determine the enum name from the value.
-    device_enum = client.get_type('DeviceEnum').Device
+    device_enum = client.get_type('DeviceEnum', version='v1').Device
 
     try:
         for row in results:

examples/v0/advanced_operations/use_portfolio_bidding_strategy.py → examples/advanced_operations/use_portfolio_bidding_strategy.py

@@ -24,12 +24,15 @@
 
 
 def main(client, customer_id):
-    campaign_budget_service = client.get_service('CampaignBudgetService')
-    bidding_strategy_service = client.get_service('BiddingStrategyService')
-    campaign_service = client.get_service('CampaignService')
+    campaign_budget_service = client.get_service('CampaignBudgetService',
+                                                 version='v1')
+    bidding_strategy_service = client.get_service('BiddingStrategyService',
+                                                  version='v1')
+    campaign_service = client.get_service('CampaignService', version='v1')
 
     # Create a budget, which can be shared by multiple campaigns.
-    campaign_budget_operation = client.get_type('CampaignBudgetOperation')
+    campaign_budget_operation = client.get_type('CampaignBudgetOperation',
+                                                version='v1')
     campaign_budget = campaign_budget_operation.create
     campaign_budget.name.value = 'Interplanetary Budget %s' % uuid.uuid4()
     campaign_budget.delivery_method = client.get_type(
@@ -57,7 +60,8 @@ def main(client, customer_id):
     print('Budget "%s" was created.' % campaign_budget_id)
 
     # Create a portfolio bidding strategy.
-    bidding_strategy_operation = client.get_type('BiddingStrategyOperation')
+    bidding_strategy_operation = client.get_type('BiddingStrategyOperation',
+                                                 version='v1')
     bidding_strategy = bidding_strategy_operation.create
     bidding_strategy.name.value = 'Enhanced CPC %s' % uuid.uuid4()
     target_spend = bidding_strategy.target_spend
@@ -84,7 +88,7 @@ def main(client, customer_id):
     print('Portfolio bidding strategy "%s" was created.' % bidding_strategy_id)
 
     # Create campaign.
-    campaign_operation = client.get_type('CampaignOperation')
+    campaign_operation = client.get_type('CampaignOperation', version='v1')
     campaign = campaign_operation.create
     campaign.name.value = 'Interplanetary Cruise %s' % uuid.uuid4()
     campaign.advertising_channel_type = client.get_type(
@@ -93,7 +97,7 @@ def main(client, customer_id):
     # Recommendation: Set the campaign to PAUSED when creating it to prevent the
     # ads from immediately serving. Set to ENABLED once you've added targeting
     # and the ads are ready to serve.
-    campaign.status = client.get_type('CampaignStatusEnum').PAUSED
+    campaign.status = client.get_type('CampaignStatusEnum', version='v1').PAUSED
 
     # Set the bidding strategy and budget.
     campaign.bidding_strategy.value = bidding_strategy_id

examples/v0/basic_operations/add_ad_groups.py → examples/basic_operations/add_ad_groups.py

@@ -27,17 +27,18 @@
 
 
 def main(client, customer_id, campaign_id):
-    ad_group_service = client.get_service('AdGroupService')
-    campaign_service = client.get_service('CampaignService')
+    ad_group_service = client.get_service('AdGroupService', version='v1')
+    campaign_service = client.get_service('CampaignService', version='v1')
 
     # Create ad group.
-    ad_group_operation = client.get_type('AdGroupOperation')
+    ad_group_operation = client.get_type('AdGroupOperation', version='v1')
     ad_group = ad_group_operation.create
     ad_group.name.value = 'Earth to Mars cruises %s' % uuid.uuid4()
-    ad_group.status = client.get_type('AdGroupStatusEnum').ENABLED
+    ad_group.status = client.get_type('AdGroupStatusEnum', version='v1').ENABLED
     ad_group.campaign.value = campaign_service.campaign_path(
         customer_id, campaign_id)
-    ad_group.type = client.get_type('AdGroupTypeEnum').SEARCH_STANDARD
+    ad_group.type = client.get_type('AdGroupTypeEnum',
+                                    version='v1').SEARCH_STANDARD
     ad_group.cpc_bid_micros.value = 10000000
 
     # Add the ad group.

examples/v0/basic_operations/add_campaigns.py → examples/basic_operations/add_campaigns.py

@@ -31,11 +31,13 @@
 
 
 def main(client, customer_id):
-    campaign_budget_service = client.get_service('CampaignBudgetService')
-    campaign_service = client.get_service('CampaignService')
+    campaign_budget_service = client.get_service('CampaignBudgetService',
+                                                 version='v1')
+    campaign_service = client.get_service('CampaignService', version='v1')
 
     # Create a budget, which can be shared by multiple campaigns.
-    campaign_budget_operation = client.get_type('CampaignBudgetOperation')
+    campaign_budget_operation = client.get_type('CampaignBudgetOperation',
+                                                version='v1')
     campaign_budget = campaign_budget_operation.create
     campaign_budget.name.value = 'Interplanetary Budget %s' % uuid.uuid4()
     campaign_budget.delivery_method = client.get_type(
@@ -58,16 +60,16 @@ def main(client, customer_id):
         sys.exit(1)
 
     # Create campaign.
-    campaign_operation = client.get_type('CampaignOperation')
+    campaign_operation = client.get_type('CampaignOperation', version='v1')
     campaign = campaign_operation.create
     campaign.name.value = 'Interplanetary Cruise %s' % uuid.uuid4()
     campaign.advertising_channel_type = client.get_type(
         'AdvertisingChannelTypeEnum').SEARCH
 
-    # Recommendation: Set the campaign to PAUSED when creating it to prevent the
-    # ads from immediately serving. Set to ENABLED once you've added targeting
-    # and the ads are ready to serve.
-    campaign.status = client.get_type('CampaignStatusEnum').PAUSED
+    # Recommendation: Set the campaign to PAUSED when creating it to prevent
+    # the ads from immediately serving. Set to ENABLED once you've added
+    # targeting and the ads are ready to serve.
+    campaign.status = client.get_type('CampaignStatusEnum', version='v1').PAUSED
 
     # Set the bidding strategy and budget.
     campaign.manual_cpc.enhanced_cpc_enabled.value = True
@@ -82,7 +84,8 @@ def main(client, customer_id):
 
     # Optional: Set the start date.
     start_time = datetime.date.today() + datetime.timedelta(days=1)
-    campaign.start_date.value = datetime.date.strftime(start_time, _DATE_FORMAT)
+    campaign.start_date.value = datetime.date.strftime(start_time,
+                                                       _DATE_FORMAT)
 
     # Optional: Set the end date.
     end_time = start_time + datetime.timedelta(weeks=4)

examples/v0/basic_operations/add_expanded_text_ads.py → examples/basic_operations/add_expanded_text_ads.py

@@ -27,15 +27,16 @@
 
 
 def main(client, customer_id, ad_group_id):
-    ad_group_ad_service = client.get_service('AdGroupAdService')
-    ad_group_service = client.get_service('AdGroupService')
+    ad_group_ad_service = client.get_service('AdGroupAdService', version='v1')
+    ad_group_service = client.get_service('AdGroupService', version='v1')
 
     # Create ad group ad.
-    ad_group_ad_operation = client.get_type('AdGroupAdOperation')
+    ad_group_ad_operation = client.get_type('AdGroupAdOperation', version='v1')
     ad_group_ad = ad_group_ad_operation.create
     ad_group_ad.ad_group.value = ad_group_service.ad_group_path(
         customer_id, ad_group_id)
-    ad_group_ad.status = client.get_type('AdGroupAdStatusEnum').PAUSED
+    ad_group_ad.status = client.get_type('AdGroupAdStatusEnum',
+                                         version='v1').PAUSED
 
     # Set expanded text ad info
     final_url = ad_group_ad.ad.final_urls.add()

examples/v0/basic_operations/add_keywords.py → examples/basic_operations/add_keywords.py

@@ -23,11 +23,13 @@
 
 
 def main(client, customer_id, ad_group_id, keyword):
-    ad_group_service = client.get_service('AdGroupService')
-    ad_group_criterion_service = client.get_service('AdGroupCriterionService')
+    ad_group_service = client.get_service('AdGroupService', version='v1')
+    ad_group_criterion_service = client.get_service('AdGroupCriterionService',
+                                                    version='v1')
 
     # Create keyword.
-    ad_group_criterion_operation = client.get_type('AdGroupCriterionOperation')
+    ad_group_criterion_operation = client.get_type('AdGroupCriterionOperation',
+                                                   version='v1')
     ad_group_criterion = ad_group_criterion_operation.create
     ad_group_criterion.ad_group.value = ad_group_service.ad_group_path(
         customer_id, ad_group_id)