Migration to Library Version 7.0.0

In version 7.0.0 of the ruby client library, we introduced some significant changes to how you interact with services. Primary among these is that all services now require keyword arguments for all fields, rather than positional arguments.

These changes were made to enable some use cases that were previously impossible. For example, you can now retrieve page tokens manually and implement finer-grained paging control, as well as set some request-level options that were previously unavailable.

To enable a smooth migration, we have built a temporary "translation layer" able to convert old-style positional arguments into the new keyword arguments automatically. However, whenever this layer is invoked, the library will log a deprecation warning, which will in a future version become an error. The translation layer will eventually be removed (at least six months after the initial release of 7.0.0), so you will eventually have to complete this migration.

Examples

Let's take a specific example call to demonstrate how you would go about migrating. Suppose you have some code that queries the GoogleAdsService:

This is how the code would have looked before 7.0.0. You specify the required fields (in this case, customer ID and search query) directly to the search method as positional arguments.

response = client.service.google_ads.search(customer_id, query)

Going forward after 7.0.0, you will instead specify a request and options arguments.

response = client.service.google_ads.search(
  request: {
    customer_id: customer_id,
    query: query,
  },
  options: {},
)

The options argument is optional, and in most cases will be unnecessary. Since options is going to be rarely used, we are also providing a shortcut that would allow you to specify the call as follows, essentially removing one level of keyword arguments from the call:

response = client.service.google_ads.search(
  customer_id: customer_id,
  query: query,
)

You can pass the fields of the request directly as keyword arguments to the service method. If you do so, you cannot also pass options.

You can find the names of the fields for a given request type in the official documentation for that service. For example, here is SearchGoogleAdsRequest.

This change will affect all API calls in the ruby library, regardless of service or method. Please make sure to check logs for any warnings to ensure that you have changed all locations where you make an API call. You can also opt in to errors rather than warnings early by updating your config to specify treat_deprecation_warnings_as_errors as true.

Updates

Please keep an eye on the ChangeLog for the library to know when we're planning to remove the translation layer.