Migrate to microgenerator, update all examples, add interface improvements (#399)

Author: BenRKarl

ChangeLog

@@ -1,3 +1,14 @@
+* 10.0.0
+- Revamp of protobuf message interface to improve usability. See:
+https://developers.google.com/google-ads/api/docs/client-libs/python/library-version-10
+- Remove ResourceName utility
+- Add ability to specify API version at client level, which overrides setting
+  at service or type level.
+- GoogleAdsClient.get_type is now an instance, not class, level method
+- Add copy_from helper method to GoogleAdsClient.
+- Add "enums" attribute to GoogleAdsClient for easier Enum accessing.
+- Various updates to all examples
+
 * 9.0.0
 - Google Ads v6_1 release
 - Deprecate v3_0

README.rst

@@ -42,6 +42,7 @@ Authors
 * `David Wihl`_
 * `Ben Karl`_
 * `Andrew Burke`_
+* `Laura Chevalier`_
 
 .. |build-status| image:: https://storage.googleapis.com/gaa-clientlibs/badges/google-ads-python/buildstatus_ubuntu.svg
 .. _Developer Site: https://developers.google.com/google-ads/api/docs/client-libs/python/
@@ -52,3 +53,4 @@ Authors
 .. _David Wihl: https://github.com/wihl
 .. _Ben Karl: https://github.com/BenRKarl
 .. _Andrew Burke: https://github.com/AndrewMBurke
+.. _Laura Chevalier: https://github.com/laurachevalier4

examples/account_management/approve_merchant_center_link.py

@@ -26,8 +26,8 @@
 import argparse
 import sys
 
-from google.ads.google_ads.client import GoogleAdsClient
-from google.ads.google_ads.errors import GoogleAdsException
+from google.ads.googleads.client import GoogleAdsClient
+from google.ads.googleads.errors import GoogleAdsException
 from google.api_core import protobuf_helpers
 
 
@@ -41,57 +41,45 @@ def main(client, customer_id, merchant_center_account_id):
         is to be approved.
     """
     merchant_center_link_service = client.get_service(
-        "MerchantCenterLinkService", version="v6"
+        "MerchantCenterLinkService"
     )
 
-    try:
-        # [START approve_merchant_center_link]
-        # Retrieve all the existing Merchant Center links.
-        response = merchant_center_link_service.list_merchant_center_links(
-            customer_id
-        )
+    # [START approve_merchant_center_link]
+    # Retrieve all the existing Merchant Center links.
+    response = merchant_center_link_service.list_merchant_center_links(
+        customer_id=customer_id
+    )
+    print(
+        f"{len(response.merchant_center_links)} Merchant Center link(s) "
+        "found with the following details:"
+    )
+    # [END approve_merchant_center_link]
+
+    merchant_center_link_status_enum = client.get_type(
+        "MerchantCenterLinkStatusEnum"
+    ).MerchantCenterLinkStatus
+
+    # Iterate through the results and filter for links with pending statuses.
+    for merchant_center_link in response.merchant_center_links:
+        # [START approve_merchant_center_link_1]
         print(
-            f"{len(response.merchant_center_links)} Merchant Center link(s) "
-            "found with the following details:"
+            f"Link '{merchant_center_link.resource_name}' has status "
+            f"'{merchant_center_link.status.name}'."
         )
-        # [END approve_merchant_center_link]
-
-        merchant_center_link_status_enum = client.get_type(
-            "MerchantCenterLinkStatusEnum", version="v6"
-        ).MerchantCenterLinkStatus
-
-        # Iterate through the results and filter for links with pending states.
-        for merchant_center_link in response.merchant_center_links:
-            # [START approve_merchant_center_link_1]
-            print(
-                f"Link '{merchant_center_link.resource_name}' has status "
-                f"'{merchant_center_link_status_enum.Name(merchant_center_link.status)}'."
+        # [END approve_merchant_center_link_1]
+
+        if (
+            merchant_center_link.status
+            == merchant_center_link_status_enum.PENDING
+            and str(merchant_center_link.id) == merchant_center_account_id
+        ):
+            _update_merchant_center_link_status(
+                client,
+                customer_id,
+                merchant_center_link_service,
+                merchant_center_link,
+                merchant_center_link_status_enum.ENABLED,
             )
-            # [END approve_merchant_center_link_1]
-
-            if (
-                merchant_center_link.status
-                == merchant_center_link_status_enum.PENDING
-                and str(merchant_center_link.id) == merchant_center_account_id
-            ):
-                _update_merchant_center_link_status(
-                    client,
-                    customer_id,
-                    merchant_center_link_service,
-                    merchant_center_link,
-                    merchant_center_link_status_enum.ENABLED,
-                )
-    except GoogleAdsException as ex:
-        print(
-            f'Request with ID "{ex.request_id}" failed with status'
-            f'"{ex.error.code().name}" and includes the following errors:'
-        )
-        for error in ex.failure.errors:
-            print(f'\tError with message "{error.message}".')
-            if error.location:
-                for field_path_element in error.location.field_path_elements:
-                    print(f"\t\tOn field: {field_path_element.field_name}")
-        sys.exit(1)
 
 
 # [START approve_merchant_center_link_2]
@@ -112,38 +100,34 @@ def _update_merchant_center_link_status(
         status: The updated status to apply to the merchant center link.
     """
     # Creates an operation.
-    operation = client.get_type("MerchantCenterLinkOperation", version="v6")
+    operation = client.get_type("MerchantCenterLinkOperation")
     link_to_update = operation.update
     link_to_update.resource_name = merchant_center_link.resource_name
     # Enables the pending link.
     link_to_update.status = status
-
-    field_mask = protobuf_helpers.field_mask(None, link_to_update)
-    operation.update_mask.CopyFrom(field_mask)
+    client.copy_from(
+        operation.update_mask,
+        protobuf_helpers.field_mask(None, link_to_update._pb),
+    )
 
     # Updates the link.
     mutate_response = merchant_center_link_service.mutate_merchant_center_link(
-        customer_id, operation
+        customer_id=customer_id, operation=operation
     )
 
-    merchant_center_link_status_enum = client.get_type(
-        "MerchantCenterLinkStatusEnum", version="v6"
-    ).MerchantCenterLinkStatus
-
     # Displays the result.
     print(
         "The status of Merchant Center Link with resource name "
         f"'{mutate_response.result.resource_name}' to Google Ads account : "
-        f"{customer_id} was updated to "
-        f"{merchant_center_link_status_enum.Name(status)}."
+        f"{customer_id} was updated to {status.name}."
     )
     # [END approve_merchant_center_link_2]
 
 
 if __name__ == "__main__":
     # GoogleAdsClient will read the google-ads.yaml configuration file in the
     # home directory if none is specified.
-    google_ads_client = GoogleAdsClient.load_from_storage()
+    googleads_client = GoogleAdsClient.load_from_storage(version="v6")
 
     parser = argparse.ArgumentParser(
         description=("Approves a Merchant Center link request.")
@@ -166,4 +150,18 @@ def _update_merchant_center_link_status(
     )
     args = parser.parse_args()
 
-    main(google_ads_client, args.customer_id, args.merchant_center_account_id)
+    try:
+        main(
+            googleads_client, args.customer_id, args.merchant_center_account_id
+        )
+    except GoogleAdsException as ex:
+        print(
+            f'Request with ID "{ex.request_id}" failed with status'
+            f'"{ex.error.code().name}" and includes the following errors:'
+        )
+        for error in ex.failure.errors:
+            print(f'\tError with message "{error.message}".')
+            if error.location:
+                for field_path_element in error.location.field_path_elements:
+                    print(f"\t\tOn field: {field_path_element.field_name}")
+        sys.exit(1)

examples/account_management/create_customer.py

@@ -25,19 +25,17 @@
 import sys
 from datetime import datetime
 
-import google.ads.google_ads.client
-
+from google.ads.googleads.client import GoogleAdsClient
+from google.ads.googleads.errors import GoogleAdsException
 
 # [START create_customer]
 def main(client, manager_customer_id):
-    customer_service = client.get_service("CustomerService", version="v6")
-    customer = client.get_type("Customer", version="v6")
-    today = datetime.today().strftime("%Y%m%d %H:%M:%S")
-    customer.descriptive_name = (
-        "Account created with " "CustomerService on %s" % today
-    )
+    customer_service = client.get_service("CustomerService")
+    customer = client.get_type("Customer")
+    now = datetime.today().strftime("%Y%m%d %H:%M:%S")
+    customer.descriptive_name = f"Account created with CustomerService on {now}"
     # For a list of valid currency codes and time zones see this documentation:
-    # https://developers.google.com/adwords/api/docs/appendix/codes-formats
+    # https://developers.google.com/google-ads/api/reference/data/codes-formats
     customer.currency_code = "USD"
     customer.time_zone = "America/New_York"
     # The below values are optional. For more information about URL
@@ -46,39 +44,21 @@ def main(client, manager_customer_id):
     customer.final_url_suffix = (
         "keyword={keyword}&matchtype={matchtype}" "&adgroupid={adgroupid}"
     )
-    customer.has_partners_badge = False
 
-    try:
-        response = customer_service.create_customer_client(
-            manager_customer_id, customer
-        )
-        print(
-            (
-                'Customer created with resource name "%s" under manager account '
-                'with customer ID "%s"'
-            )
-            % (response.resource_name, manager_customer_id)
-        )
-    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)
-        # [END create_customer]
+    response = customer_service.create_customer_client(
+        customer_id=manager_customer_id, customer_client=customer
+    )
+    print(
+        f'Customer created with resource name "{response.resource_name}" '
+        f'under manager account with ID "{manager_customer_id}".'
+    )
+    # [END create_customer]
 
 
 if __name__ == "__main__":
     # GoogleAdsClient will read the 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()
-    )
+    googleads_client = GoogleAdsClient.load_from_storage(version="v6")
 
     parser = argparse.ArgumentParser(
         description=("Creates a new client under the given manager.")
@@ -95,4 +75,16 @@ def main(client, manager_customer_id):
     )
     args = parser.parse_args()
 
-    main(google_ads_client, args.manager_customer_id)
+    try:
+        main(googleads_client, args.manager_customer_id)
+    except GoogleAdsException as ex:
+        print(
+            f'Request with ID "{ex.request_id}" failed with status '
+            f'"{ex.error.code().name}" and includes the following errors:'
+        )
+        for error in ex.failure.errors:
+            print(f'	Error with message "{error.message}".')
+            if error.location:
+                for field_path_element in error.location.field_path_elements:
+                    print(f"\t\tOn field: {field_path_element.field_name}")
+        sys.exit(1)