The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Google-Ads-GoogleAds-Client-4.0.0
River stage zero No dependents
++
/ Google::Ads::GoogleAds::Client

NAME

Google::Ads::GoogleAds::Client

SYNOPSIS

  use Google::Ads::GoogleAds::Client;

  my $api_client = Google::Ads::GoogleAds::Client->new();

  my $customer_id = "1234567890";

  my $query = "SELECT campaign.id, campaign.name FROM campaign";

  my $response = $api_client->GoogleAdsService()->search({
    customer_id => $customer_id,
    query       => $query,
    pageSize    => PAGE_SIZE
  });

  foreach my $row (@{$response->{results}}) {
    # Do something with the results
  }

DESCRIPTION

Google::Ads::GoogleAds::Client is the main interface to the Google Ads API. It takes care of handling your API credentials, and exposes all of the underlying services that make up the Google Ads API.

The Google::Ads::GoogleAds::Client module should be loaded before other Google::Ads:: modules. A warning will occur if modules are loaded in the wrong order.

ATTRIBUTES

Each of these attributes can be set via Google::Ads::GoogleAds::Client->new().

Alternatively, there is a get_ and set_ method associated with each attribute for retrieving or setting them dynamically. For example, the set_login_customer_id() allows you to change the value of the "login_customer_id" attribute and get_login_customer_id() returns the current value of the attribute.

developer_token

A string used to tie usage of the Google Ads API to a specific Google Ads manager account.

The value should be a character string assigned to you by Google. You can apply for a Developer Token by following the instructions at https://developers.google.com/google-ads/api/docs/first-call/dev-token.

login_customer_id

This is the customer ID of the authorized customer to use in the request, without hyphens. If your access to the customer account is through a manager account, this attribute is required and must be set to the customer ID of the manager account.

linked_customer_id

This header is only required for methods that update the resources of an entity when permissioned via Linked Accounts in the Google Ads UI (AccountLink resource in the Google Ads API). Set this value to the customer ID of the data provider that updates the resources of the specified customer ID. It should be set without dashes.

service_address

The Google Ads API service address.

user_agent

The user-agent request header used to identify this application.

proxy

The proxy server URL to be used for internet connectivity.

http_timeout

The HTTP timeout value in seconds.

version

The version of the Google Ads API to use. The latest is the default.

die_on_faults

By default the client returns a Google::Ads::GoogleAds::GoogleAdsException object if an error has occurred at the server side. However if this flag is set to true, the client will issue a die() command on received API faults.

The default is "false".

properties_file

The path of the configuration file. The default value is googleads.properties file in the home directory.

last_request

The last HTTP request sent by this client.

last_response

The last HTTP response received by this client.

METHODS

new

Initializes a new Google::Ads::GoogleAds::Client object.

Parameters

The new() method takes parameters as a hash reference. The attributes of this object can be populated in a number of ways:

  • If the "properties_file" parameter is given, then properties are read from that file and the corresponding attributes are populated.

  • If no "properties_file" parameter is given, then the code checks to see if there is a file named googleads.properties in the home directory of the current user. If there is, then properties are read from there.

  • Any of the "ATTRIBUTES" can be passed in as keys in the parameters hash reference. If any attribute is explicitly passed in then it will override the value for that attribute that might be in the properties file.

Returns

A new Google::Ads::GoogleAds::Client object with the appropriate attributes set.

Exceptions

If a "properties_file" is passed in but the file cannot be read, the code will die() with an error message describing the failure.

Example

  # Basic use case. Attributes will be read from ~/googleads.properties file.
  my $api_client = Google::Ads::GoogleAds::Client->new();

  # Most attributes from a custom properties file, but override login_customer_id.
  eval {
    my $api_client = Google::Ads::GoogleAds::Client->new({
      properties_file   => "/path/to/googleads.properties",
      login_customer_id => "1234567890"
    });
  };
  if ($@) {
    # The properties file couldn't be read; handle error as appropriate.
  }

  # Specify all attributes explicitly. The properties file will not override.
  my $api_client = Google::Ads::GoogleAds::Client->new({
    developer_token   => "123xyzabc...",
    login_customer_id => "1234567890"
  });

  $api_client->get_oauth_2_applications_handler()->set_refresh_token('1/Abc...');

set_die_on_faults

This module supports two approaches for handling API faults (i.e. errors returned by the underlying REST API service).

One approach is to issue a die() with a description of the error when an API fault occurs. This die() would ideally be contained within an eval { }; block, thereby emulating try { } / catch { } exception functionality in other languages.

A different approach is to require developers to explicitly check for API faults being returned after each Google Ads API request. This approach requires a bit more work, but has the advantage of exposing the full details of the API fault, like the fault code.

Refer to the object Google::Ads::GoogleAds::GoogleAdsException for more details on how faults get returned.

The default value is false, i.e. you must explicitly check for faults.

Parameters

A true value will cause this module to die() when an API fault occurs.

A false value will suppress this die(). This is the default behavior.

Returns

The input parameter is returned.

Example

  # $api_client is a Google::Ads::GoogleAds::Client.

  # Enable die()ing on faults.
  $api_client->set_die_on_faults(1);
  eval { my $response = $api_client->AdGroupAdService()->mutate($mutate_request); };
  if ($@) {
    # Do something with the error information in $@.
  }

  # Default behavior.
  $api_client->set_die_on_faults(0);
  my $response = $api_client->AdGroupAdService()->mutate($mutate_request);
  if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
    # Do something with this GoogleAdsException object.
  }

get_die_on_faults

Returns

A true or false value indicating whether the Google::Ads::GoogleAds::Client instance is set to die() on API faults.

{ServiceName}

The client object contains a method for each service provided by the Google Ads API. For example it can be invoked as $api_client->AdGroupService() and it will return an object of type Google::Ads::GoogleAds::V4::Services::AdGroupService when using version V4 of the API.

For a list of all the available services please refer to https://developers.google.com/google-ads/api/docs and for code samples on how to invoke the services please refer to scripts in the examples folder.

get_oauth_2_applications_handler

Returns the OAuth2 authorization handler for Web/Installed applications attached to the client, for programmatically setting/overriding its properties.

  $api_client->get_oauth_2_applications_handler()->set_client_id('client-id');
  $api_client->get_oauth_2_applications_handler()->set_client_secret('client-secret');
  $api_client->get_oauth_2_applications_handler()->set_access_token('access-token');
  $api_client->get_oauth_2_applications_handler()->set_refresh_token('refresh-token');
  $api_client->get_oauth_2_applications_handler()->set_access_type('access-type');
  $api_client->get_oauth_2_applications_handler()->set_prompt('prompt');
  $api_client->get_oauth_2_applications_handler()->set_redirect_uri('redirect-url');

Refer to Google::Ads::GoogleAds::OAuth2ApplicationsHandler for more details.

__parse_properties_file (Private)

Parameters

The path to a properties file on disk. The data in the file should be in the following format:

 key1=value1
 key2=value2

Returns

A hash corresponding to the keys and values in the properties file.

Exceptions

Issues a die() with an error message if the properties file could not be read.

_auth_handler (Protected)

Retrieves the active auth handler. All handlers are checked in the order.

Returns

An implementation of Google::Ads::GoogleAds::Common::AuthHandlerInterface.

LICENSE AND COPYRIGHT

Copyright 2019 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

     http://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.

REPOSITORY INFORMATION

 $Rev: $
 $LastChangedBy: $
 $Id: $