Lookup utility

  • The ProtoLookupUtil simplifies looking up and creating instances of services, operations, enumerations, and resources by handling API version numbers and namespaces.

  • Instead of using the full class path, the ProtoLookupUtil allows for simpler instantiation using methods like client.resource.campaign.

  • The utility returns instances for resources, services, and operations, while returning a class reference for enumerations.

  • Shortcuts like :PAUSED can be used with enumerations to avoid looking up enumeration protos.

  • Using client.service is recommended for fetching services as it automatically handles developer token and authentication details.

Fetching references to proto classes when using the API requires that you either have an intrinsic understanding of the API or frequently look up the proto reference documentation for the exact namespace path.

ProtoLookupUtil

The lookup utility methods on GoogleAdsClient (backed by Factories and ServiceLookup, replacing the legacy ProtoLookupUtil class) let you look up and create instances of services, operations, enumerations, and resources without having to keep track of API version numbers and module namespaces. By default, these methods use the highest API version supported by your installed gem (V25 in the latest release, where minor API releases such as v25.1 use their major version module V25), or you can specify an explicit version prefix (such as v25) on the lookup call.

Without the lookup utility, you instantiate a campaign resource directly from its versioned namespace:

campaign =
  Google::Ads::GoogleAds::V25::Resources::Campaign.new

With the client lookup methods, you can instantiate the resource directly from the client:

campaign = client.resource.campaign

When fetching a resource, service, or operation, an instance of that entity is returned:

# Instantiate an operation
operation = client.operation.campaign

Service lookup

Use the client.service method to fetch service clients, even if you don't use this utility for other entities. client.service automatically configures your authentication credentials and transport settings on the returned service client:

campaign_service = client.service.campaign

Enumeration lookup

For enum fields on protobuf messages, assign a Ruby symbol directly instead of looking up the enumeration module:

campaign.status = :PAUSED

To inspect or iterate over all valid symbols for an enumeration at runtime, use client.enum, which returns the Google::Protobuf::EnumDescriptor for that enum:

status_enum = client.enum.campaign_status
status_enum.each { |status| p status }