Part 6 - Create a Budget

We're going to rewrite the logic that creates a campaign budget with the AdWords API so that it uses the Google Ads API.

The _create_campaign_budget method creates a new budget with a few individual steps:

Retrieve the necessary service client
Create an object representing the resource we are creating
Create and configure a mutate operation object
Send the operation to the API in a mutate request
Perform a searchStream request create an object for the newly created entity
Return the newly created entity

These steps apply to all mutate methods throughout this script and are the building blocks for most mutate requests in the Google Ads API.

The first step is to swap out the AdWords service client being passed to the _create_campaign_budget method with the Google Ads service client. Because the methods using the Google Ads API return resource objects as opposed to IDs in the AdWords API, rename the returned variable name accordingly. The resulting call to _create_campaign_budget should look like this:

6.0.0: Updating the Call to _create_campaign_budget (Google Ads API)
budget = _create_campaign_budget(googleads_client)

In order for the following call to _create_campaign to work after making these changes, update the argument passed to the _create_campaign method to pass in the new budget’s ID:

6.0.1: Updating the Call to _create_campaign (AdWords API)
campaign_id = _create_campaign(adwords_client, budget.id)

Part 6.1 - Retrieve the necessary service client

Here is how the AdWords client library retrieves the BudgetService client:

6.1.0: Retrieving the BudgetService (AdWords API)
# Initializes a BudgetService client for the AdWords API. budget_service = client.GetService("BudgetService", version="v201809")

We'll need the Google Ads equivalent of BudgetService. According to the map of AdWords services to Google Ads services, we'll need to use the CampaignBudgetService:

6.1.1: Retrieving the CampaignBudgetService (Google Ads API)
# Initializes a CampaignBudgetService client for the Google Ads API. campaign_budget_service = client.get_service("CampaignBudgetService")

Part 6.2 - Create a mutate operation

Here the AdWords API operation is a dict that's inserted into a list:

6.2.0: Initializing a Budget Operation (AdWords API)
budget_operations = [{"operator": "ADD", "operand": budget}]

In the Google Ads API these operations have distinct types specific to their respective services. Consult the services documentation for the latest API version to determine which operation class is needed. The CampaignBudgetService.MutateCampaignBudgets method requires a CampaignBudgetOperation:

6.2.1: Initializing a CampaignBudgetOperation (Google Ads API)
budget_operation = client.get_type("CampaignBudgetOperation")

Part 6.3 Configure the Operation object

The AdWords API client library accepts a dict that represents the budget:

6.3.0: Configuring a Budget Operation (AdWords API)
budget = { "name": "Interplanetary Cruise Budget #{}".format(uuid.uuid4()), "amount": {"microAmount": "50000000"}, "deliveryMethod": "STANDARD", }

The Google Ads API client library includes a class for all resources in the API, and these classes mirror the structure of their protobuf definitions. Here’s how to create a CampaignBudget and add it to the operation:

6.3.1: Configuring a CampaignBudgetOperation (Google Ads API)
# Retrieve the campaign_budget from the existing operation. # Here we use the "create" oneof to specify that this is a # "create" operation and not an "update" or a "remove". In # Python you can access this field directly, in other languages # you may need to set it explicitly. campaign_budget = budget_operation.create campaign_budget.name = f"Interplanetary Cruise Budget #{uuid.uuid4()}" campaign_budget.amount_micros = 50000000 # Enums also have their own classes. The below is special syntax for enums in # the Python client library and is the equivalent of calling # client.get_type("BudgetDeliveryMethodEnum"). campaign_budget.delivery_method = client.enums.BudgetDeliveryMethodEnum.STANDARD

6.3.1: Configuring a CampaignBudgetOperation (Google Ads API)

# Retrieve the campaign_budget from the existing operation.
# Here we use the "create" oneof to specify that this is a
# "create" operation and not an "update" or a "remove". In
# Python you can access this field directly, in other languages
# you may need to set it explicitly.
campaign_budget = budget_operation.create
campaign_budget.name = f"Interplanetary Cruise Budget #{uuid.uuid4()}"
campaign_budget.amount_micros = 50000000
# Enums also have their own classes. The below is special syntax for enums in
# the Python client library and is the equivalent of calling
# client.get_type("BudgetDeliveryMethodEnum").
campaign_budget.delivery_method = client.enums.BudgetDeliveryMethodEnum.STANDARD

Part 6.4 - Send the operation to the API in a mutate request

6.4.0: Submitting a Budget Mutate Request (AdWords API)
# Sends the operation to the AdWords API in a mutate request. results = budget_service.mutate(budget_operations)

This step is very similar with the Google Ads API client library:

6.4.1: Submitting a Budget Mutate Request (Google Ads API)
# Sends the operation to the Google Ads API in a mutate request. # Note that the Google Ads client library requires the customer ID # to be passed into the service method, whereas the AdWords client # library reads the customer ID from configuration. response = campaign_budget_service.mutate_campaign_budgets( customer_id=_CUSTOMER_ID, operations=[budget_operation] )

6.4.1: Submitting a Budget Mutate Request (Google Ads API)

# Sends the operation to the Google Ads API in a mutate request.
# Note that the Google Ads client library requires the customer ID
# to be passed into the service method, whereas the AdWords client
# library reads the customer ID from configuration.
response = campaign_budget_service.mutate_campaign_budgets(
    customer_id=_CUSTOMER_ID, operations=[budget_operation]
)

Part 6.5 - Get information about the new object

In this script the newly created budget is returned by the response object:

6.5.0: Parsing a Budget Mutate Response (AdWords API)
created_budget = results["value"][0]

The same is not true by default in the Google Ads API. The default behavior is for mutate requests to only return the entity's resource name.

6.5.1: Parsing a Budget Mutate Response (Google Ads API)
resource_name = response.results[0].resource_name

In the Google Ads API, it's possible to configure a mutate request so that the response contains the entire object, not just its resource name. We'll look more closely at this functionality later in Part 10.

Unlike the previous version of this method, we'll return an instance of the campaign budget entity, and will use the reporting method defined in Part 5 to retrieve it.

6.5.2: Using Google Ads API Reporting to Retrieve the Full Budget Object
query = f""" SELECT campaign_budget.id, campaign_budget.name, campaign_budget.resource_name FROM campaign_budget WHERE campaign_budget.resource_name = '{resource_name}'""" googleads_row = _search_google_ads(client, query) return googleads_row.campaign_budget

6.5.2: Using Google Ads API Reporting to Retrieve the Full Budget Object

query = f"""
    SELECT
      campaign_budget.id,
      campaign_budget.name,
      campaign_budget.resource_name
    FROM campaign_budget
    WHERE campaign_budget.resource_name = '{resource_name}'"""

googleads_row = _search_google_ads(client, query)

return googleads_row.campaign_budget

Part 6.6 - Finished _create_campaign_budget method

6.6.0: Complete _create_campaign_budget Method (Google Ads API)
def _create_campaign_budget(client): """Creates a new campaign budget and returns a subset of its fields. Only the fields selected in the below GAQL query will be present on the returned campaign budget. Args: client: An instance of the GoogleAdsClient class. Returns: (CampaignBudget) The newly created budget with a subset of its fields. """ budget_service = client.get_service("CampaignBudgetService") budget_operation = client.get_type("CampaignBudgetOperation") # Retrieve the campaign_budget from the existing operation campaign_budget = budget_operation.create campaign_budget.name = f"Interplanetary Cruise Budget #{uuid.uuid4()}" campaign_budget.amount_micros = 50000000 # Enums also have their own classes. The below is special syntax for enums in # the Python client library and is the equivalent of calling # client.get_type("BudgetDeliveryMethodEnum"). campaign_budget.delivery_method = ( client.enums.BudgetDeliveryMethodEnum.STANDARD ) # Sends the operation to the Google Ads API in a mutate request. # Note that the Google Ads client library requires the customer ID # to be passed into the service method, whereas the AdWords client # library reads the customer ID from configuration. response = campaign_budget_service.mutate_campaign_budgets( customer_id=_CUSTOMER_ID, operations=[budget_operation] ) resource_name = response.results[0].resource_name query = f""" SELECT campaign_budget.id, campaign_budget.name, campaign_budget.resource_name FROM campaign_budget WHERE campaign_budget.resource_name = '{resource_name}'""" googleads_row = _search_google_ads(client, query) return googleads_row.campaign_budget

6.6.0: Complete _create_campaign_budget Method (Google Ads API)

def _create_campaign_budget(client):
    """Creates a new campaign budget and returns a subset of its fields.

    Only the fields selected in the below GAQL query will be present on
    the returned campaign budget.

    Args:
        client: An instance of the GoogleAdsClient class.

    Returns:
        (CampaignBudget) The newly created budget with a subset of its fields.
    """
    budget_service = client.get_service("CampaignBudgetService")

    budget_operation = client.get_type("CampaignBudgetOperation")
    # Retrieve the campaign_budget from the existing operation
    campaign_budget = budget_operation.create
    campaign_budget.name = f"Interplanetary Cruise Budget #{uuid.uuid4()}"
    campaign_budget.amount_micros = 50000000
    # Enums also have their own classes. The below is special syntax for enums in
    # the Python client library and is the equivalent of calling
    # client.get_type("BudgetDeliveryMethodEnum").
    campaign_budget.delivery_method = (
        client.enums.BudgetDeliveryMethodEnum.STANDARD
    )
    # Sends the operation to the Google Ads API in a mutate request.
    # Note that the Google Ads client library requires the customer ID
    # to be passed into the service method, whereas the AdWords client
    # library reads the customer ID from configuration.

    response = campaign_budget_service.mutate_campaign_budgets(
        customer_id=_CUSTOMER_ID, operations=[budget_operation]
    )

    resource_name = response.results[0].resource_name

    query = f"""
        SELECT
          campaign_budget.id,
          campaign_budget.name,
          campaign_budget.resource_name
        FROM campaign_budget
        WHERE campaign_budget.resource_name = '{resource_name}'"""

    googleads_row = _search_google_ads(client, query)

    return googleads_row.campaign_budget

Run the script to ensure everything is still working as expected:

python create_complete_campaign_adwords_api_only.py

Part 5 - Write a reporting method

Part 7 - Create a campaign