Factories

  • The factories module provides a high-level interface for creating operations and resources in the Google Ads API client library.

  • Factory methods are automatically generated for all resources, enums, operations, and service types available in the Google Ads API.

  • Convenience methods like client.operation.create_resource, client.operation.update_resource, and client.operation.remove_resource simplify creating operations.

  • You can easily initialize resource objects and retrieve service objects using client.resource and client.service respectively.

  • Enum values are recommended to be set using symbol syntax, and you can also explicitly set Google Ads API versions for factories.

factories provides a high-level interface for creating operations and resources with the client library.

Factory methods are automatically generated for all resources, enums, operations, and service types provided by the Google Ads API. The examples on this page assume you have initialized a GoogleAdsClient instance and a target customer_id:

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new
customer_id = '1234567890'

Operations

The library provides client.operation.create_resource.<resource_type>, client.operation.update_resource.<resource_type>, and client.operation.remove_resource.<resource_type> convenience methods to build operations for working with the Google Ads API.

The following example creates a campaign budget resource:

campaign_budget_operation =
  client.operation.create_resource.campaign_budget do |budget|
    budget.name = "Interplanetary Budget #{(Time.new.to_f * 1000).to_i}"
    budget.delivery_method = :STANDARD
    budget.amount_micros = 500_000
  end

return_budget = client.service.campaign_budget.mutate_campaign_budgets(
  customer_id: customer_id,
  operations: [campaign_budget_operation]
)

Note that the object yielded to the block (budget) is a new instance of CampaignBudget that you can mutate, and the appropriate create operation for CampaignBudgetService is returned.

Similarly, the library provides convenience methods for updating resources:

campaign_service = client.service.campaign

# If you only have a resource name:
update_operation =
  client.operation.update_resource.campaign(campaign_resource_name) do |camp|
    camp.status = :PAUSED
  end

campaign_service.mutate_campaigns(
  customer_id: customer_id,
  operations: [update_operation]
)

# If you have a full resource proto:
update_operation = client.operation.update_resource.campaign(campaign) do |camp|
  camp.name = "A different Cruise #{(Time.new.to_f * 1000).to_i}"
end

campaign_service.mutate_campaigns(
  customer_id: customer_id,
  operations: [update_operation]
)

These calls return a well-formed update operation with a prepopulated field mask to update the resource in the Google Ads API.

The following example removes a resource using a resource path:

campaign_service = client.service.campaign
remove_operation =
  client.operation.remove_resource.campaign(campaign_resource_name)
campaign_service.mutate_campaigns(
  customer_id: customer_id,
  operations: [remove_operation]
)

If you prefer to work with the operation yourself, you can get a raw operation and then manually populate the fields:

operation = client.operation.campaign

Resources

The library provides client.resource.<resource_type> to initialize resource objects:

campaign.network_settings = client.resource.network_settings do |ns|
  ns.target_google_search = true
  ns.target_search_network = true
  ns.target_content_network = false
  ns.target_partner_search_network = false
end

A new instance of the requested resource type is yielded to the passed block for setting fields.

Services

The library provides client.service.<service_name> to retrieve service client objects:

campaign_service = client.service.campaign

Enums

Use the symbol syntax for statically setting enum fields (for example, campaign.status = :PAUSED). To enumerate all valid values for an enum, use the client.enum factory:

client.enum.ad_type.each { |ad_type| p ad_type }
# Output:
# :UNSPECIFIED
# :UNKNOWN
# :TEXT_AD
# :EXPANDED_TEXT_AD
# :EXPANDED_DYNAMIC_SEARCH_AD
# :HOTEL_AD
# :SHOPPING_SMART_AD
# :SHOPPING_PRODUCT_AD
# :VIDEO_AD
# :IMAGE_AD
# :RESPONSIVE_SEARCH_AD
# :LEGACY_RESPONSIVE_DISPLAY_AD
# :APP_AD
# :LEGACY_APP_INSTALL_AD
# :RESPONSIVE_DISPLAY_AD
# :LOCAL_AD
# :HTML5_UPLOAD_AD
# :DYNAMIC_HTML5_AD
# :APP_ENGAGEMENT_AD
# :SHOPPING_COMPARISON_LISTING_AD
# :VIDEO_BUMPER_AD
# :VIDEO_NON_SKIPPABLE_IN_STREAM_AD
# :VIDEO_TRUEVIEW_IN_STREAM_AD
# :VIDEO_RESPONSIVE_AD
# :SMART_CAMPAIGN_AD
# :CALL_AD
# :APP_PRE_REGISTRATION_AD
# :IN_FEED_VIDEO_AD
# :DEMAND_GEN_MULTI_ASSET_AD
# :DEMAND_GEN_CAROUSEL_AD
# :TRAVEL_AD
# :DEMAND_GEN_VIDEO_RESPONSIVE_AD
# :DEMAND_GEN_PRODUCT_AD
# :YOUTUBE_AUDIO_AD

Explicitly set Google Ads API versions

You can also explicitly set a major API version on any factory call (for example, v25; minor API releases such as v25.1 use the major version method v25):

client.resource.v25.[entity]
client.operation.v25.[operation]
client.service.v25.[service]
client.enum.v25.[enum]