Module: AdwordsApi::Extensions

Defined in:
lib/adwords_api/extensions.rb

Constant Summary collapse

@@extensions =

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

{
  [:v13, :ReportService] => [:download_xml_report, :download_csv_report],
  [:v201003, :ReportDefinitionService] => [:download_report,
      :download_report_as_file],
  [:v201008, :ReportDefinitionService] => [:download_report,
      :download_report_as_file],
  [:v201101, :ReportDefinitionService] => [:download_report,
      :download_report_as_file],
  [:v201109, :ReportDefinitionService] => [:download_report,
      :download_report_as_file]
}
@@methods =

Defines the parameter list for every extension method.

{
  :download_xml_report     => [:job_id],
  :download_csv_report     => [:job_id],
  :download_report         => [:report_definition_id],
  :download_report_as_file => [:report_definition_id, :path]
}

Class Method Summary collapse

Class Method Details

.download_csv_report(wrapper, args) ⇒ 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)



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
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/adwords_api/extensions.rb', line 132

def self.download_csv_report(wrapper, args)
  (job_id, report_xml) = args
  # Get XML report data.
  report_xml = download_xml_report(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 AdwordsApi::Errors::ApiException,
        "Error parsing report XML: %s\nSource: %s" % [e, e.backtrace.first]
  end
end

.download_report(wrapper, args) ⇒ 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)



205
206
207
208
209
210
 
# File 'lib/adwords_api/extensions.rb', line 205

def self.download_report(wrapper, args)
  report_definition_id = args.first
  url = get_report_url(wrapper, "?__rd=%s" % report_definition_id)
  report_response = get_report_response(wrapper, url)
  return report_response.body
end

.download_report_as_file(wrapper, args) ⇒ 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



186
187
188
189
190
191
 
# File 'lib/adwords_api/extensions.rb', line 186

def self.download_report_as_file(wrapper, args)
  (report_definition_id, path) = args
  report_data = download_report(wrapper, [report_definition_id])
  save_to_file(report_data, path)
  return nil
end

.download_xml_report(wrapper, args) ⇒ 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)



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/adwords_api/extensions.rb', line 84

def self.download_xml_report(wrapper, args)
  job_id = args.first
  sleep_interval = 30

  status_field = :get_report_job_status_return
  download_field = :get_report_download_url_return

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

  if status == 'Completed'
    report_url = wrapper.get_report_download_url(job_id)[download_field]

    # Download the report 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
      return AdsCommon::Http.get(report_url, wrapper.api.config)
    rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
      # This exception indicates a connection-level error.
      # In general, it is likely to be transitory.
      raise AdsCommon::Errors::HttpError, e.message, e.backtrace
    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 AdwordsApi::Errors::ApiException, 'Report generation failed.'
  end
end

.extensions ⇒ Object

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



56
57
58
 
# File 'lib/adwords_api/extensions.rb', line 56

def self.extensions
  return @@extensions
end

.methods ⇒ Object

Return the parameter list for every extension method.



61
62
63
 
# File 'lib/adwords_api/extensions.rb', line 61

def self.methods
  return @@methods
end