bing-ads 0.1.11 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 423587915177b9c676bd2534087b0a8f233cbbc9
-  data.tar.gz: 5377b102e6a1512fbd268c97bada27af95482184
+  metadata.gz: 69fd2b5280eafbb14724463be4492828935ebbc4
+  data.tar.gz: 0fa11c1a1c80a3788b42637248340933455488d9
 SHA512:
-  metadata.gz: 56a1313389de341e937e47b94ec8fec9be888f619a547000bbfc305f28dd78de618b5578b8e6f345e7117ca2dc89a6f2693cca82ea9c43666283bf9344e2be33
-  data.tar.gz: 5dbd8a412d30767047a3a7dc6380fdb134f240d543ba121653f7857d0247e22470ae2ae8ca8cee07f660b1bfc07fcdd2ef2d9c772048c67b1b7d292cf968dfda
+  metadata.gz: c07d81eb68e2f058b0ec7a1ca6fca6a426e89c61f4efad82d8f12a8ead814c1771859f74ac3b7ec5dc114e36ca067f302baa4352dc511e3f567c8dbb64501a32
+  data.tar.gz: b7ed4a73f67e5daa38b16e12512e49322cc5b74f05ce7b4645a72c419dde7f961a9ad8452e48b82ee18406cfe9840496d7f121a0d4e78d24cd910158599fe6ad

data/README.md

@@ -312,16 +312,121 @@ response = service.delete_keywords(ad_group_id, keyword_ids_to_delete)
 ```
 
 ### Bulk Service
-Not yet supported
+#### Initialization
+```ruby
+# Authentication token is not supported in sandbox, use `username` and `password` instead
+# https://msdn.microsoft.com/en-us/library/dn277356.aspx
+
+options = {
+  environment: :sandbox,
+  authentication_token: '39b290146bea6ce975c37cfc23',
+  developer_token: 'BBD37VB98',
+  customer_id: '21027149',
+  account_id: '5278183',
+  # client_settings: { logger: LOGGER::STDOUT }
+}
+
+service = Bing::Ads::API::V11::Services::Bulk.new(options)
+```
+
+#### Submit a request for a URL where a bulk upload file may be posted.
+```ruby
+response = service.get_bulk_upload_url
+
+# @return
+# {
+#   request_id: 4981237213
+#   upload_url: '-'
+# }
+```
+
+#### Get the status and completion percentage of a bulk upload request.
+```ruby
+response = service.get_bulk_upload_status(request_id)
+
+# @return
+# {
+#   errors: [],
+#   percent_complete: 100,
+#   request_status: '-',
+#   result_file_url: '-'
+# }
+```
 
 ### Reporting Service
-Not yet supported. Use: https://github.com/FindHotel/bing-ads-reporting
+
+#### Initialization
+```ruby
+# Authentication token is not supported in sandbox, use `username` and `password` instead
+# https://msdn.microsoft.com/en-us/library/dn277356.aspx
+
+options = {
+  environment: :sandbox,
+  authentication_token: '39b290146bea6ce975c37cfc23',
+  developer_token: 'BBD37VB98',
+  customer_id: '21027149',
+  # client_settings: { logger: LOGGER::STDOUT }
+}
+
+service = Bing::Ads::API::V11::Services::Reporting.new(options)
+```
+
+#### Submit Generate Report
+To get reports from Bing, you must first submit a report generation request.
+
+The method `submit_generate_report` receive two params as input, first the `report_type` and then a hash with the report options.
+
+Example:
+
+```ruby
+response = service.submit_generate_report(:keyword_performance, {
+  exclude_column_headers: false,
+  exclude_report_footer: false,
+  exclude_report_header: false,
+  language: 'English',
+  format: 'Tsv',
+  report_name: 'keyword_performance_report',
+  return_only_complete_data: false,
+  aggregation: 'Daily',
+  columns: [:destination_url, :average_cpc],
+  from_date: '2017-10-23',
+  to_date: '2017-10-25'
+  account_ids: [144012349, 224002158]
+})
+```
+
+The required options depend on the report type you are using.
+
+Response example:
+
+```ruby
+{:report_request_id=>"30000000999745662", :@xmlns=>"https://bingads.microsoft.com/Reporting/v11"}
+```
+
+#### Poll Generate Report
+
+To retrieve the report generated you have a few options:
+
+You can check if the report is ready and then get the url:
+```ruby
+service.report_url(report_request_id) if service.report_ready?(report_request_id)
+```
+
+Or you can download the body of the report when it's ready. (and then write to a file for example)
+```ruby
+service.report_body(report_request_id) if service.report_ready?(report_request_id)
+```
+
+You can also get the entire poll_generate_reportl report object:
+```ruby
+service.poll_generate_report(report_request_id)
+```
 
 ### Errors raised
-* `Bing::Ads::API::Errors::AuthenticationParamsMissing`
-No username/password or authentication_token.
+* `Bing::Ads::API::Errors::AuthenticationParamsMissing` No username/password or authentication_token.
 * `Bing::Ads::API::Errors::AuthenticationTokenExpired` Authentication token needs to be refreshed.
 * `Bing::Ads::API::Errors::LimitError` An API limit has been exceeded on a specific request. Check message for details.
+* `Bing::Ads::API::Errors::DownloadError` Error when downloading a report body.
 
 ## Development
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/bing/ads.rb

@@ -7,6 +7,7 @@ require 'savon'
 
 require 'bing/ads/api/errors'
 require 'bing/ads/api/soap_client'
+require 'bing/ads/api/http_client'
 require 'bing/ads/api/v11'
 require 'bing/ads/api/v11/constants'
 require 'bing/ads/api/v11/data'

data/lib/bing/ads/api/errors.rb

@@ -11,6 +11,9 @@ module Bing
         # Bing::Ads::API::Errors::UnhandledSOAPFault
         class UnhandledSOAPFault < RuntimeError; end;
 
+        # Bing::Ads::API::Errors::DownloadError
+        class DownloadError < RuntimeError; end;
+
         # Bing::Ads::API::Errors::LimitError
         class LimitError < RuntimeError
           def initialize(operation, limit, type)

data/lib/bing/ads/api/http_client.rb

@@ -0,0 +1,22 @@
+module Bing
+  module Ads
+    module API
+      # Bing::Ads::API::HttpClient
+      class HttpClient
+        API_CALL_RETRY_COUNT = 3
+
+        def self.download(url, retry_count = API_CALL_RETRY_COUNT)
+          1.upto(retry_count + 1) do |retry_index|
+            response = Net::HTTP.get_response(URI(url))
+            if response.is_a?(Net::HTTPSuccess)
+              break response.body
+            else
+              next if retry_index <= retry_count
+              raise Bing::Ads::API::Errors::DownloadError, "#{response.code} #{response.msg}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bing/ads/api/v11/data.rb

@@ -2,3 +2,4 @@ require_relative './data/ad_group'
 require_relative './data/expanded_text_ad'
 require_relative './data/campaign'
 require_relative './data/keyword'
+require_relative './data/report_request'

data/lib/bing/ads/api/v11/data/report_request.rb

@@ -0,0 +1,106 @@
+module Bing
+  module Ads
+    module API
+      module V11
+        module Data
+          # Bing::Ads::API::V11::Data::ReportRequest
+          class ReportRequest
+
+            # @order
+            # https://msdn.microsoft.com/en-us/library/bing-ads-reporting-reportrequest.aspx
+            KEYS_ORDER = [
+              :exclude_column_headers,
+              :exclude_report_footer,
+              :exclude_report_header,
+              :format,
+              :language,
+              :report_name,
+              :return_only_complete_data,
+              :aggregation,
+              :columns,
+              :filter,
+              :scope,
+              :time
+            ]
+
+            class << self
+              def prepare(type, report_request_raw)
+                report_request_raw[:columns] = prepare_columns(
+                  columns: report_request_raw[:columns],
+                  type: type.to_s.classify
+                )
+
+                report_request_raw[:scope] = prepare_scope(
+                  account_ids: report_request_raw[:account_ids]
+                )
+
+                report_request_raw[:time] = prepare_time_period(
+                  from_date: report_request_raw[:from_date],
+                  to_date:   report_request_raw[:to_date]
+                )
+
+                report_request_raw.except!(:from_date, :to_date, :account_ids)
+
+                report_request = Bing::Ads::Utils.sort_keys(report_request_raw, KEYS_ORDER)
+                namespace_identifier = Bing::Ads::API::V11::NAMESPACE_IDENTIFIER
+                {
+                  report_request: Bing::Ads::Utils.camelcase_keys(report_request),
+                  :attributes! => {
+                    report_request: {
+                      "xmlns:i" => "http://www.w3.org/2001/XMLSchema-instance",
+                      "i:type" => "#{namespace_identifier}:#{type.to_s.classify}ReportRequest"
+                    }
+                  }
+                }
+              end
+
+              private
+
+              def prepare_columns(type:, columns:)
+                {
+                  "#{type}ReportColumn" => columns.map(&:to_s).map(&:camelcase)
+                }
+              end
+
+              def prepare_scope(account_ids:)
+                account_ids_elements =
+                  if account_ids.nil?
+                    nil
+                  else
+                    {
+                      'a1:long' => account_ids,
+                      '@xmlns:a1' => 'http://schemas.microsoft.com/2003/10/Serialization/Arrays'
+                    }
+                  end
+
+                {
+                  account_ids: account_ids_elements,
+                  ad_groups: nil,
+                  campaigns: nil
+                }
+              end
+
+              def prepare_time_period(from_date:, to_date:)
+                from_date = Date.parse(from_date)
+                to_date = Date.parse(to_date)
+
+                {
+                  custom_date_range_end: {
+                    day: to_date.day,
+                    month: to_date.month,
+                    year: to_date.year
+                  },
+                  custom_date_range_start: {
+                    day: from_date.day,
+                    month: from_date.month,
+                    year: from_date.year
+                  }
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bing/ads/api/v11/services.rb

@@ -2,3 +2,4 @@ require_relative './services/base'
 require_relative './services/bulk'
 require_relative './services/campaign_management'
 require_relative './services/customer_management'
+require_relative './services/reporting'

data/lib/bing/ads/api/v11/services/base.rb

@@ -51,11 +51,12 @@ module Bing
                 response = soap_client.call(operation: operation.to_sym, payload: payload)
                 return response.hash
               rescue Savon::SOAPFault => error
-                fault_detail = error.to_hash[:fault][:detail]
-                if fault_detail.key?(:api_fault_detail)
-                  handle_soap_fault(operation, fault_detail, :api_fault_detail)
-                elsif fault_detail.key?(:ad_api_fault_detail)
-                  handle_soap_fault(operation, fault_detail, :ad_api_fault_detail)
+                fault = error.to_hash[:fault]
+
+                if fault.dig(:detail, :api_fault_detail)
+                  handle_soap_fault(operation, fault[:detail], :api_fault_detail)
+                elsif fault.dig(:detail, :ad_api_fault_detail)
+                  handle_soap_fault(operation, fault[:detail], :ad_api_fault_detail)
                 else
                   if retries_made < retry_attempts
                     sleep(2**retries_made)
@@ -63,7 +64,7 @@ module Bing
                     retry
                   else
                     raise Bing::Ads::API::Errors::UnhandledSOAPFault,
-                          "SOAP error (#{fault_detail.keys.join(', ')}) while calling #{operation}. #{error.message}"
+                          "SOAP error (#{fault.keys.join(', ')}) while calling #{operation}. #{error.message}"
                   end
                 end
               rescue Savon::HTTPError => error

data/lib/bing/ads/api/v11/services/bulk.rb

@@ -23,6 +23,8 @@ module Bing
               response_body.slice(:errors, :percent_complete, :request_status, :result_file_url)
             end
 
+            # TODO operations: https://msdn.microsoft.com/en-us/library/bing-ads-bulk-service-operations.aspx
+
             private
 
             def service_name

data/lib/bing/ads/api/v11/services/reporting.rb

@@ -0,0 +1,51 @@
+module Bing
+  module Ads
+    module API
+      module V11
+        module Services
+          # Bing::Ads::API::V11::Services::CampaignManagement
+          class Reporting < Base
+            def initialize(options = {})
+              super(options)
+            end
+
+            def submit_generate_report(type, report_options)
+              payload = Bing::Ads::API::V11::Data::ReportRequest.prepare(type, report_options)
+              response = call(:submit_generate_report, payload)
+              response_body = response_body(response, __method__)
+              response_body
+            end
+
+            def poll_generate_report(report_request_id)
+              response = call(:poll_generate_report, report_request_id: report_request_id)
+              response_body = response_body(response, __method__)
+              response_body
+            end
+
+            def report_ready?(report_request_id)
+              polled = poll_generate_report(report_request_id)
+              status = polled.dig(:report_request_status, :status)
+              raise "Report status: Error for ID: #{report_request_id}" if status == "Error"
+              status == "Success"
+            end
+
+            def report_url(report_request_id)
+              polled = poll_generate_report(report_request_id)
+              polled.dig(:report_request_status, :report_download_url)
+            end
+
+            def report_body(report_request_id)
+              HttpClient.download(report_url(report_request_id))
+            end
+
+            private
+
+            def service_name
+              'reporting'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bing/ads/version.rb

@@ -1,5 +1,5 @@
 module Bing
   module Ads
-    VERSION = '0.1.11'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bing-ads
 version: !ruby/object:Gem::Version
-  version: 0.1.11
+  version: 0.2.0
 platform: ruby
 authors:
 - oss92
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-12 00:00:00.000000000 Z
+date: 2017-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: savon
@@ -117,6 +117,7 @@ files:
 - bing-ads.gemspec
 - lib/bing/ads.rb
 - lib/bing/ads/api/errors.rb
+- lib/bing/ads/api/http_client.rb
 - lib/bing/ads/api/soap_client.rb
 - lib/bing/ads/api/v11.rb
 - lib/bing/ads/api/v11/constants.rb
@@ -130,11 +131,13 @@ files:
 - lib/bing/ads/api/v11/data/campaign.rb
 - lib/bing/ads/api/v11/data/expanded_text_ad.rb
 - lib/bing/ads/api/v11/data/keyword.rb
+- lib/bing/ads/api/v11/data/report_request.rb
 - lib/bing/ads/api/v11/services.rb
 - lib/bing/ads/api/v11/services/base.rb
 - lib/bing/ads/api/v11/services/bulk.rb
 - lib/bing/ads/api/v11/services/campaign_management.rb
 - lib/bing/ads/api/v11/services/customer_management.rb
+- lib/bing/ads/api/v11/services/reporting.rb
 - lib/bing/ads/utils.rb
 - lib/bing/ads/version.rb
 homepage: https://github.com/FindHotel/bing-ads
@@ -157,7 +160,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Enhances the experience of developing Bing Ads applications with Ruby