Google provides a Ruby client library for interacting with the Ad Manager API.
We recommend using the client library with RubyGems.

To get started, create a new project in the IDE of your choice or add the
dependency to an existing project. Google publishes client library to
RubyGems as
[`google-ads-ad_manager`](https://rubygems.org/gems/google-ads-ad_manager).

### Gemfile

```yaml
gem 'google-ads-ad_manager', '~> 5.6.0'
```

### Command line

```bash
gem install google-ads-ad_manager
```

## Configure credentials

The Ruby client library uses OAuth2 and [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials)
(ADC) to authenticate.

ADC searches for credentials in order in the following locations:

1. `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
2. User credentials set up through the Google Cloud CLI (gcloud CLI).
3. When running on Google Cloud, the service account attached to the Google Cloud resource.

For creating and configuring your ADC credentials, see
[Authentication](https://developers.google.com/ad-manager/api/beta/authentication.md.txt).

## Make your first request

Each REST service has a has a corresponding Ruby class with methods for each
corresponding REST method. The following example reads a
[`Network`](https://developers.google.com/ad-manager/api/beta/reference/rest/v1/networks.md.txt).

```ruby
require "google/ads/ad_manager/v1"

def get_network
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Ads::AdManager::V1::NetworkService::Rest::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Ads::AdManager::V1::GetNetworkRequest.new(name: => 'networks/NETWORK_CODE)'

  # Call the get_network method.
  result = client.get_network request

  # The returned object is of type Google::Ads::AdManager::V1::Network.
  p result
end
```

For examples of other methods and resources, see the GitHub repository
[`googleapis/google-cloud-ruby`](https://github.com/googleapis/google-cloud-ruby/tree/main/google-ads-ad_manager-v1/snippets).

## Log HTTP requests and responses

The Ruby client library library uses the standard `logger`
library to log HTTP requests and responses. Logging is disabled by
default.

To enable logging, set the environment variable `GOOGLE_SDK_RUBY_LOGGING_GEMS`
to the value `google-ads-ad_manager`. If you use more than one Google API, you
can set the value to a comma-delimited list of client library gem names. The
default logging behavior writes logs to the standard error stream.

Alternatively, you can enable logging in your Ruby code by modifying the
`logger` configuration when constructing a client object.

```ruby
require "google/ads/ad_manager/v1"
require "logger"

client = ::Google::Ads::AdManager::V1::NetworkService::Rest::Client.new do |config|
  config.logger = Logger.new "my-app.log"
end
```

## Handle errors

All Ad Manager API errors are subclasses of
[::Google::Cloud::Error](https://cloud.google.com/ruby/docs/reference/google-cloud-errors/latest/Google-Cloud-Error)
in the Ruby client library.

```ruby
result = client.get_network request
rescue ::Google::Cloud::Error => e
  puts "An error of type #{e.class} occurred with HTTP status #{e.status_code}"
```

Ad Manager API errors also include a unique `request_id` you can
provide to [support](https://developers.google.com/ad-manager/api/beta/support) for assistance with
troubleshooting. The following example extracts the
`request_id` from the error `details`.

```ruby
rescue ::Google::Cloud::Error => e
  request_info = e.details.find { |detail| detail.is_a?(Google::Rpc::RequestInfo)}
  puts request_info.request_id
```

## Construct resource names

The client library provides helper classes for building resource names from
IDs.

```ruby
require "google/ads/ad_manager/v1"

#  Constructs a String in the format:
#  "networks/{networkCode}/orders/{orderId}"
order_name = Google::Ads::AdManager::V1::OrderService::Paths::order_path(:network_code => 123, :order => 456)
```

## Configure proxy settings

The Ruby client library respects both `HTTP_PROXY` and `HTTPS_PROXY`
environment variables.