Module: AdWords::Extensions

Defined in:
lib/adwords4r/apiextensions.rb

Constant Summary collapse

@@extensions =

Maintains a list of all extension methods, indexed by version and service. Using camelCase to match API method names.

{
  [13, 'Report'] => ['downloadXmlReport', 'downloadCsvReport'],
  [201003, 'ReportDefinition'] => ['downloadReport', 'downloadReportAsFile']
}
@@methods =

Defines the parameter list for every extension method

{
  'downloadXmlReport'    => ['job_id'],
  'downloadCsvReport'    => ['job_id'],
  'downloadReport'       => ['report_definition_id'],
  'downloadReportAsFile' => ['report_definition_id', 'path']
}

Class Method Summary collapse

Class Method Details

.downloadCsvReport(wrapper, job_id, report_xml = nil) ⇒ Object

Extension method – Download and return report data in CSV format.

Warning: this method is blocking for the calling thread.

Args:

  • wrapper: the service wrapper object for any API methods that need to be called

  • job_id: the job id for the report to be downloaded

  • xml: optional parameter used for testing and debugging

Returns: The CSV data for the report (as a string)



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/adwords4r/apiextensions.rb', line 121

def self.downloadCsvReport(wrapper, job_id, report_xml=nil)
  # Get XML report data.
  report_xml = downloadXmlReport(wrapper, job_id) if report_xml.nil?

  begin
    # Construct DOM object.
    doc = REXML::Document.new(report_xml)

    # Get data columns.
    columns = []
    doc.elements.each('report/table/columns/column') do |column_elem|
      name = column_elem.attributes['name']
      columns << name unless name.nil?
    end

    # Get data rows.
    rows = []
    doc.elements.each('report/table/rows/row') do |row_elem|
      rows << row_elem.attributes unless row_elem.attributes.nil?
    end

    # Build CSV
    csv = ''
    CSV::Writer.generate(csv) do |writer|
      writer << columns
      rows.each do |row|
        row_values = []
        columns.each { |column| row_values << row[column] }
        writer << row_values
      end
    end

    return csv
  rescue REXML::ParseException => e
    # Error parsing XML
    raise AdWords::Error::Error,
        "Error parsing report XML: %s\nSource: %s" % [e, e.backtrace.first]
  end
end

.downloadReport(wrapper, report_definition_id) ⇒ Object

Extension method – Download and return a v20xx report.

Warning: this method is blocking for the calling thread.

Args:

  • wrapper: the service wrapper object for any API methods that need to be called

  • report_definition_id: the id for the report definition

Returns: The data for the report (as a string)



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/adwords4r/apiextensions.rb', line 197

def self.downloadReport(wrapper, report_definition_id)
  # Set URL parameters.
  parameters = {'__rd' => report_definition_id.to_s}

  # Set HTTP headers.
  headers = {}
  headers['Authorization'] = 'GoogleLogin auth=%s' %
      wrapper.api.credentials.auth_token
  creds = wrapper.api.credentials.credentials
  if creds['clientEmail']
    headers['clientEmail'] = creds['clientEmail']
  elsif creds['clientCustomerId']
    headers['clientCustomerId'] = creds['clientCustomerId']
  end

  # Get download URL.
  url = AdWords::Service.report_download_url(
      wrapper.api.credentials.environment, 201003)

  # Download report data.
  client = HTTPClient.new
  report_data = client.get_content(url, parameters, headers)

  return report_data
end

.downloadReportAsFile(wrapper, report_definition_id, path) ⇒ Object

Extension method – Download and return a v20xx report into a file.

Warning: this method is blocking for the calling thread.

Args:

  • wrapper: the service wrapper object for any API methods that need to be called

  • report_definition_id: the id for the report definition

  • path: the file where the data should be saved

Returns: nil



174
175
176
177
178
179
180
181
182
183
 
# File 'lib/adwords4r/apiextensions.rb', line 174

def self.downloadReportAsFile(wrapper, report_definition_id, path)
  report_data = downloadReport(wrapper, report_definition_id)

  # Write to file (if provided)
  if path
    open(path, 'w') { |file| file.puts(report_data) }
  end

  return nil
end

.downloadXmlReport(wrapper, job_id) ⇒ Object

Extension method – Download and return report data in XML format.

Warning: this method is blocking for the calling thread.

Args:

  • wrapper: the service wrapper object for any API methods that need to be called

  • job_id: the job id for the report to be downloaded

Returns: The xml for the report (as a string)



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/adwords4r/apiextensions.rb', line 74

def self.downloadXmlReport(wrapper, job_id)
  sleep_interval = 30

  # Repeatedly check the report status until it is finished.
  # 'Pending' and 'InProgress' statuses indicate the job is still being run.
  status = wrapper.getReportJobStatus(job_id).getReportJobStatusReturn
  while status != 'Completed' && status != 'Failed'
    sleep(sleep_interval)
    status = wrapper.getReportJobStatus(job_id).getReportJobStatusReturn
  end

  if status == 'Completed'
    report_url =
        wrapper.getReportDownloadUrl(job_id).getReportDownloadUrlReturn

    # Download the report via the HTTPClient library and return its
    # contents. The report is an XML document; the actual element names vary
    # depending on the type of report run and columns requested.
    begin
      client = HTTPClient.new
      return client.get_content(report_url)
    rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
      # This exception indicates a connection-level error.
      # In general, it is likely to be transitory.
      raise AdWords::Error::Error, "Connection Error: %s\nSource: %s" %
          [e, e.backtrace.first]
    end
  else
    # Reports that pass validation will normally not fail, but if there is
    # an error in the report generation service it can sometimes happen.
    raise AdWords::Error::Error, 'Report generation failed.'
  end
end

.extensions ⇒ Object

Return list of all extension methods, indexed by version and service.



46
47
48
 
# File 'lib/adwords4r/apiextensions.rb', line 46

def self.extensions
  return @@extensions
end

.methods ⇒ Object

Return the parameter list for every extension method.



51
52
53
 
# File 'lib/adwords4r/apiextensions.rb', line 51

def self.methods
  return @@methods
end