- Google Ads v6_1 release (#383)

- Deprecate v3_0
- Add log masking for CustomerUserAccessInvitation.email_address field.
- Update examples to reflect changes to resource name helper methods.

Author: wihl

ChangeLog

@@ -1,3 +1,9 @@
+* 9.0.0
+- Google Ads v6_1 release
+- Deprecate v3_0
+- Add log masking for CustomerUserAccessInvitation.email_address field.
+- Update examples to reflect changes to resource name helper methods.
+
 * 8.2.0
 - Added new client configuration environment variables.
 - Added ability to configure YAML file location via environment variable.

examples/account_management/get_change_details.py

@@ -87,12 +87,18 @@ def main(client, customer_id):
             elif resource_type == "AD_GROUP":
                 old_resource = event.old_resource.ad_group
                 new_resource = event.new_resource.ad_group
+            elif resource_type == "AD_GROUP_AD":
+                old_resource = event.old_resource.ad_group_ad
+                new_resource = event.new_resource.ad_group_ad
             elif resource_type == "AD_GROUP_CRITERION":
                 old_resource = event.old_resource.ad_group_criterion
                 new_resource = event.new_resource.ad_group_criterion
             elif resource_type == "AD_GROUP_BID_MODIFIER":
                 old_resource = event.old_resource.ad_group_bid_modifier
                 new_resource = event.new_resource.ad_group_bid_modifier
+            elif resource_type == "AD_GROUP_FEED":
+                old_resource = event.old_resource.ad_group_feed
+                new_resource = event.new_resource.ad_group_feed
             elif resource_type == "CAMPAIGN":
                 old_resource = event.old_resource.campaign
                 new_resource = event.new_resource.campaign
@@ -102,6 +108,15 @@ def main(client, customer_id):
             elif resource_type == "CAMPAIGN_CRITERION":
                 old_resource = event.old_resource.campaign_criterion
                 new_resource = event.new_resource.campaign_criterion
+            elif resource_type == "CAMPAIGN_FEED":
+                old_resource = event.old_resource.campaign_feed
+                new_resource = event.new_resource.campaign_feed
+            elif resource_type == "FEED":
+                old_resource = event.old_resource.feed
+                new_resource = event.new_resource.feed
+            elif resource_type == "FEED_ITEM":
+                old_resource = event.old_resource.feed_item
+                new_resource = event.new_resource.feed_item
             else:
                 print(
                     "Unknown change_resource_type: '{event.change_resource_type}'"

examples/account_management/get_pending_invitations.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python
+# Copyright 2020 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 code example retrieves pending invitations for a customer account.
+
+To create a pending invitation, see the invite_user_with_access_role.py
+example.
+"""
+
+
+import argparse
+import sys
+
+from google.ads.google_ads.client import GoogleAdsClient
+from google.ads.google_ads.errors import GoogleAdsException
+
+
+def main(client, customer_id):
+    """The main method that creates all necessary entities for the example.
+
+    Args:
+        client: An initialized GoogleAdsClient instance.
+        customer_id: The client customer ID str.
+    """
+    google_ads_service = client.get_service("GoogleAdsService", version="v6")
+    # [START get_pending_invitations]
+    query = """
+        SELECT
+          customer_user_access_invitation.invitation_id,
+          customer_user_access_invitation.email_address,
+          customer_user_access_invitation.access_role,
+          customer_user_access_invitation.creation_date_time
+        FROM customer_user_access_invitation
+        WHERE customer_user_access_invitation.invitation_status = PENDING"""
+
+    try:
+        response = google_ads_service.search_stream(customer_id, query=query)
+        for batch in response:
+            for row in batch.results:
+                invite = row.customer_user_access_invitation
+                print(
+                    "A pending invitation with "
+                    f"invitation ID: '{invite.invitation_id}', "
+                    f"email address: {invite.email_address}, "
+                    f"access role: {invite.access_role}, and "
+                    f"created on: {invite.creation_date_time} was found."
+                )
+    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)
+    # [END get_pending_invitations]
+
+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()
+
+    parser = argparse.ArgumentParser(
+        description=("Retrieves pending invitations for a customer account.")
+    )
+    # The following argument(s) should be provided to run the example.
+    parser.add_argument(
+        "-c",
+        "--customer_id",
+        type=str,
+        required=True,
+        help="The Google Ads customer ID.",
+    )
+    args = parser.parse_args()
+
+    main(google_ads_client, args.customer_id)

examples/account_management/invite_user_with_access_role.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python
+# Copyright 2020 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 code example sends an invitation email to a user.
+
+The invitation is to manage a customer account with a desired access role.
+"""
+
+
+import argparse
+import sys
+
+from google.ads.google_ads.client import GoogleAdsClient
+from google.ads.google_ads.errors import GoogleAdsException
+
+
+def main(client, customer_id, email_address, access_role):
+    """The main method that creates all necessary entities for the example.
+
+    Args:
+        client: An initialized GoogleAdsClient instance.
+        customer_id: The client customer ID str.
+        email_address: The email address for the user receiving the invitation.
+        access_role: The desired access role for the invitee.
+    """
+    service = client.get_service(
+        "CustomerUserAccessInvitationService", version="v6"
+    )
+    # [START invite_user_with_access_role]
+    invitation_operation = client.get_type(
+        "CustomerUserAccessInvitationOperation", version="v6"
+    )
+    invitation = invitation_operation.create
+    invitation.email_address = email_address
+    invitation.access_role = client.get_type(
+        "AccessRoleEnum", version="v6"
+    ).AccessRole.Value(access_role)
+    try:
+        response = service.mutate_customer_user_access_invitation(
+            customer_id, invitation_operation
+        )
+        print(
+            "Customer user access invitation was sent for "
+            f"customer ID: '{customer_id}', "
+            f"email address {email_address}, and "
+            f"access role {access_role}. The invitation resource name is: "
+            f"{response.result.resource_name}"
+        )
+    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)
+    # [END invite_user_with_access_role]
+
+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()
+
+    parser = argparse.ArgumentParser(
+        description=(
+            "Sends an invitation email to a user to manage a customer "
+            "account with a desired access role."
+        )
+    )
+    # The following argument(s) should be provided to run the example.
+    parser.add_argument(
+        "-c",
+        "--customer_id",
+        type=str,
+        required=True,
+        help="The Google Ads customer ID.",
+    )
+    parser.add_argument(
+        "-e",
+        "--email_address",
+        type=str,
+        required=True,
+        help="The email address of the user to send the invitation to.",
+    )
+    parser.add_argument(
+        "-a",
+        "--access_role",
+        type=str,
+        required=True,
+        choices=google_ads_client.get_type(
+            "AccessRoleEnum", version="v6"
+        ).AccessRole.keys(),
+        help="The updated user access role.",
+    )
+    args = parser.parse_args()
+
+    main(
+        google_ads_client,
+        args.customer_id,
+        args.email_address,
+        args.access_role,
+    )

examples/basic_operations/pause_ad.py

@@ -20,7 +20,7 @@
 
 from google.api_core import protobuf_helpers
 from google.ads.google_ads.client import GoogleAdsClient
-from google.ads.google_ads.util import ResourceName
+from google.ads.google_ads.errors import GoogleAdsException
 
 
 def main(client, customer_id, ad_group_id, ad_id):
@@ -30,7 +30,7 @@ def main(client, customer_id, ad_group_id, ad_id):
 
     ad_group_ad = ad_group_ad_operation.update
     ad_group_ad.resource_name = ad_group_ad_service.ad_group_ad_path(
-        customer_id, ResourceName.format_composite(ad_group_id, ad_id)
+        customer_id, ad_group_id, ad_id
     )
     ad_group_ad.status = client.get_type(
         "AdGroupStatusEnum", version="v6"
@@ -42,7 +42,7 @@ def main(client, customer_id, ad_group_id, ad_id):
         ad_group_ad_response = ad_group_ad_service.mutate_ad_group_ads(
             customer_id, [ad_group_ad_operation]
         )
-    except google.ads.google_ads.errors.GoogleAdsException as ex:
+    except GoogleAdsException as ex:
         print(
             'Request with ID "%s" failed with status "%s" and includes the '
             "following errors:" % (ex.request_id, ex.error.code().name)

examples/basic_operations/remove_ad.py

@@ -19,23 +19,23 @@
 import sys
 
 from google.ads.google_ads.client import GoogleAdsClient
-from google.ads.google_ads.util import ResourceName
+from google.ads.google_ads.errors import GoogleAdsException
 
 
 def main(client, customer_id, ad_group_id, ad_id):
     ad_group_ad_service = client.get_service("AdGroupAdService", version="v6")
     ad_group_ad_operation = client.get_type("AdGroupAdOperation", version="v6")
 
     resource_name = ad_group_ad_service.ad_group_ad_path(
-        customer_id, ResourceName.format_composite(ad_group_id, ad_id)
+        customer_id, ad_group_id, ad_id
     )
     ad_group_ad_operation.remove = resource_name
 
     try:
         ad_group_ad_response = ad_group_ad_service.mutate_ad_group_ads(
             customer_id, [ad_group_ad_operation]
         )
-    except google.ads.google_ads.errors.GoogleAdsException as ex:
+    except GoogleAdsException as ex:
         print(
             'Request with ID "%s" failed with status "%s" and includes the '
             "following errors:" % (ex.request_id, ex.error.code().name)

examples/basic_operations/remove_keyword.py

@@ -20,15 +20,14 @@
 
 from google.ads.google_ads.client import GoogleAdsClient
 from google.ads.google_ads.errors import GoogleAdsException
-from google.ads.google_ads.util import ResourceName
 
 
 def main(client, customer_id, ad_group_id, criterion_id):
     agc_service = client.get_service("AdGroupCriterionService", version="v6")
     agc_operation = client.get_type("AdGroupCriterionOperation", version="v6")
 
-    resource_name = agc_service.ad_group_criteria_path(
-        customer_id, ResourceName.format_composite(ad_group_id, criterion_id)
+    resource_name = agc_service.ad_group_criterion_path(
+        customer_id, ad_group_id, criterion_id
     )
     agc_operation.remove = resource_name
 

examples/basic_operations/update_keyword.py

@@ -20,7 +20,6 @@
 
 from google.api_core import protobuf_helpers
 from google.ads.google_ads.client import GoogleAdsClient
-from google.ads.google_ads.util import ResourceName
 
 
 def main(client, customer_id, ad_group_id, criterion_id):
@@ -31,8 +30,8 @@ def main(client, customer_id, ad_group_id, criterion_id):
     )
 
     ad_group_criterion = ad_group_criterion_operation.update
-    ad_group_criterion.resource_name = agc_service.ad_group_criteria_path(
-        customer_id, ResourceName.format_composite(ad_group_id, criterion_id)
+    ad_group_criterion.resource_name = agc_service.ad_group_criterion_path(
+        customer_id, ad_group_id, criterion_id
     )
     ad_group_criterion.status = client.get_type(
         "AdGroupCriterionStatusEnum", version="v6"

examples/campaign_management/add_campaign_bid_modifier.py

@@ -48,27 +48,43 @@ def main(client, customer_id, campaign_id, bid_modifier_value):
         "InteractionTypeEnum", version="v6"
     ).CALLS
 
-    # Add the campaign bid modifier.
+    # [START mutable_resource]
+    # Add the campaign bid modifier. Here we pass the optional parameter
+    # response_content_type=MUTABLE_RESOURCE so that the response contains
+    # the mutated object and not just its resource name.
     try:
         campaign_bm_response = campaign_bm_service.mutate_campaign_bid_modifiers(
-            customer_id, [campaign_bid_modifier_operation]
+            customer_id,
+            [campaign_bid_modifier_operation],
+            response_content_type=client.get_type(
+                "ResponseContentTypeEnum", version="v6"
+            ).MUTABLE_RESOURCE,
         )
     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)
+            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('\tError with message "%s".' % error.message)
+            print(f'\tError with message "{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)
+                    print(f"\t\tOn field: {field_path_element.field_name}")
         sys.exit(1)
 
+    # The resource returned in the response can be accessed directly in the
+    # results list. Its fields can be read directly, and it can also be mutated
+    # further and used in subsequent requests, without needing to make
+    # additional Get or Search requests.
+    mutable_resource = campaign_bm_response.results[0].campaign_bid_modifier
     print(
-        "Created campaign bid modifier: %s."
-        % campaign_bm_response.results[0].resource_name
+        "Created campaign bid modifier with resource_name "
+        f"'{mutable_resource.resource_name}', criterion ID "
+        f"'{mutable_resource.criterion_id}', and bid modifier value "
+        f"'{mutable_resource.bid_modifier}', under the campaign with "
+        f"resource_name '{mutable_resource.campaign}', "
     )
+    # [END mutable_resource]
 
 
 if __name__ == "__main__":