adapi 0.0.1

data/examples/customize_configuration.rb

@@ -0,0 +1,17 @@
+require 'adapi'
+
+# this example shows how to load custom settings
+
+Adapi::Config.load_settings(
+  :path => File.expand_path(File.dirname(__FILE__)),
+  :filename => 'custom_settings.yml'
+)
+
+# :default account is set automatically
+p "Default settings:"
+p Adapi::Config.read[:authentication][:email]
+
+Adapi::Config.set(:sandbox)
+p "Set :sandbox account:"
+p Adapi::Config.read[:authentication][:email]
+

data/examples/log_to_specific_account.rb

@@ -0,0 +1,20 @@
+
+require 'adapi'
+
+# use specific config data
+Adapi::Config.set({
+  :authentication => {
+    :method => 'ClientLogin',
+    :email => 'sandbox_email@gmail.com',
+    :password => 'sandbox_password',
+    :developer_token => 'sandbox_developer_token',
+    :client_email => 'sandbox_client_email@gmail.com',
+    :user_agent => 'Adwords API Test'
+  },
+  :service => {
+    :environment => 'SANDBOX'
+  }
+})
+
+# create campaign
+require 'add_bare_campaign'

data/examples/update_campaign.rb

@@ -0,0 +1,23 @@
+
+require 'adapi'
+
+# create campaign
+require 'add_bare_campaign'
+
+p 'original status: %s' % $campaign[:status]
+
+campaign_updates = {
+  :id => $campaign[:id],
+  :status => 'ACTIVE'
+}
+
+$campaign = Adapi::Campaign.update(:data => campaign_updates)
+
+p 'updated status: %s' % $campaign[:status]
+
+$campaign = Adapi::Campaign.update(
+  :id => $campaign[:id],
+  :data => {:status => 'DELETED'}
+)
+
+p 'updated status (again): %s' % $campaign[:status]

data/examples/update_campaign_name.rb

@@ -0,0 +1,14 @@
+
+require 'adapi'
+
+# create campaign
+require 'add_bare_campaign'
+
+p 'original name: %s' % $campaign[:name]
+
+$campaign = Adapi::Campaign.rename(
+  :id => $campaign[:id],
+  :name => "Renamed Campaign #%d" % (Time.new.to_f * 1000).to_i
+)
+
+p 'updated name: %s' % $campaign[:name]

data/examples/update_campaign_status.rb

@@ -0,0 +1,15 @@
+
+require 'adapi'
+
+# create campaign
+require 'add_bare_campaign'
+
+p 'original status: %s' % $campaign[:status]
+
+$campaign = Adapi::Campaign.activate(:id => $campaign[:id])
+
+p 'updated status: %s' % $campaign[:status]
+
+$campaign = Adapi::Campaign.delete(:id => $campaign[:id])
+
+p 'updated status (again): %s' % $campaign[:status]

data/lib/adapi.rb

@@ -0,0 +1,18 @@
+
+require 'rubygems'
+require 'adwords_api'
+require 'collection'
+require 'yaml'
+
+require 'adapi/config'
+require 'adapi/api'
+require 'adapi/campaign'
+require 'adapi/campaign_target'
+require 'adapi/ad_group'
+require 'adapi/ad_group_criterion'
+require 'adapi/ad'
+require 'adapi/version'
+
+module Adapi
+  API_VERSION = :v201101  
+end

data/lib/adapi/ad.rb

@@ -0,0 +1,64 @@
+module Adapi
+
+  # TODO add synonym for actual service name: AdGroupAd
+  #
+  class Ad < Api
+
+    def initialize(params = {})
+      params[:service_name] = :AdGroupAdService
+      super(params)
+    end
+
+    def self.create(params = {})
+      ad_service = Ad.new
+
+      ad_group_id = params[:data].delete(:ad_group_id)
+
+      operation = { :operator => 'ADD', 
+        :operand => { :ad_group_id => ad_group_id, :ad => params[:data] }
+      } 
+    
+      response = ad_service.service.mutate([operation])
+
+      ad_group = response[:value].first
+
+      ad = nil
+      if response and response[:value]
+        ad = response[:value].first
+        puts "  Ad ID is #{ad[:ad][:id]}, type is '#{ad[:ad][:xsi_type]}' and status is '#{ad[:status]}'."
+      end
+
+      ad
+    end
+
+    def self.find(params = {})
+      ad_service = Ad.new
+
+      raise "No AdGroup ID" unless params[:ad_group_id]
+      ad_group_id = params[:ad_group_id].to_i
+
+      selector = {
+        :fields => ['Id', 'Headline'],
+        :ordering => [{:field => 'Id', :sort_order => 'ASCENDING'}],
+        :predicates => [
+          {:field => 'AdGroupId', :operator => 'EQUALS', :values => ad_group_id }
+          # { :field => 'Status', :operator => 'IN', :values => ['ENABLED', 'PAUSED', 'DISABLED'] }
+        ]
+      }
+
+      response = ad_service.service.get(selector)
+
+      if response and response[:entries]
+        ads = response[:entries]
+        puts "Ad group ##{ad_group_id} has #{ads.length} ad(s)."
+        ads.each do |ad|
+          puts "  Ad id is #{ad[:ad][:id]}, type is #{ad[:ad][:xsi_type]} and " +
+              "status is \"#{ad[:status]}\"."
+        end
+      else
+        puts "No ads found for ad group ##{ad_group_id}."
+      end
+    end
+
+  end
+end

data/lib/adapi/ad_group.rb

@@ -0,0 +1,70 @@
+module Adapi
+  class AdGroup < Api
+
+    def initialize(params = {})
+      params[:service_name] = :AdGroupService
+      super(params)
+    end
+
+    def self.create(params = {})
+      ad_group_service = AdGroup.new
+
+      criteria = params[:data].delete(:criteria)
+      ads = params[:data].delete(:ads) || []
+
+      # prepare for adding campaign
+      operation = { :operator => 'ADD', :operand => params[:data] }
+    
+      response = ad_group_service.service.mutate([operation])
+
+      ad_group = response[:value].first
+
+      if criteria
+        Adapi::AdGroupCriterion.create(
+          :ad_group_id => ad_group[:id],
+          :criteria => criteria
+        )
+      end
+
+      ads.each do |ad_data|
+        Adapi::Ad.create(
+          :data => ad_data.merge(:ad_group_id => ad_group[:id])
+        )
+      end
+
+      # puts "Ad group ID %d was successfully added." % ad_group[:id]
+      ad_group
+    end
+
+    # should be sorted out later, but leave it be for now
+    #
+    def self.find(params = {})
+      ad_group_service = AdGroup.new
+
+      raise "No Campaign ID" unless params[:campaign_id]
+      campaign_id = params[:campaign_id]
+
+      selector = {
+        :fields => ['Id', 'Name'],
+        # :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}],
+        :predicates => [{
+          :field => 'CampaignId', :operator => 'EQUALS', :values => campaign_id
+        }]
+      }
+
+      response = ad_group_service.service.get(selector)
+
+      if response and response[:entries]
+        ad_groups = response[:entries]
+        puts "Campaign ##{campaign_id} has #{ad_groups.length} ad group(s)."
+        ad_groups.each do |ad_group|
+          puts "  Ad group name is \"#{ad_group[:name]}\" and id is #{ad_group[:id]}."
+        end
+     else
+       puts "No ad groups found for campaign ##{campaign_id}."
+     end
+
+    end
+
+  end
+end

data/lib/adapi/ad_group_criterion.rb

@@ -0,0 +1,68 @@
+module Adapi
+  class AdGroupCriterion < Api
+
+    def initialize(params = {})
+      params[:service_name] = :AdGroupCriterionService
+      super(params)
+    end
+
+    def self.create(params = {})
+      ad_group_criterion_service = AdGroupCriterion.new
+
+      raise "No criteria available" unless params[:criteria].is_a?(Array)
+
+      # if ad_group_id is supplied as separate parameter, include it into
+      # criteria
+      if params[:ad_group_id]
+        params[:criteria].map! { |c| c.merge(:ad_group_id => params[:ad_group_id].to_i) }
+      end
+
+      operation = params[:criteria].map do |criterion|
+        { :operator => 'ADD', :operand => criterion }
+      end
+    
+      response = ad_group_criterion_service.service.mutate(operation)
+
+      ad_group_criteria = nil
+      if response and response[:value]
+        ad_group_criteria = response[:value]
+        puts "Added #{ad_group_criteria.length} criteria " # "to ad group #{ad_group_id}."
+        ad_group_criteria.each do |ad_group_criterion|
+          puts "  Criterion id is #{ad_group_criterion[:criterion][:id]} and " +
+            "type is #{ad_group_criterion[:criterion][:"@xsi:type"]}."
+        end
+      else
+        puts "No criteria were added."
+      end
+
+      ad_group_criteria 
+    end
+
+    def find(params = {})
+      raise "No Campaign ID" unless params[:campaign_id]
+      campaign_id = params[:campaign_id]
+
+      selector = {
+        :fields => ['Id', 'Name'],
+        # :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}],
+        :predicates => [{
+          :field => 'CampaignId', :operator => 'EQUALS', :values => campaign_id
+        }]
+      }
+
+      response = @service.get(selector)
+
+      if response and response[:entries]
+        ad_groups = response[:entries]
+        puts "Campaign ##{campaign_id} has #{ad_groups.length} ad group(s)."
+        ad_groups.each do |ad_group|
+          puts "  Ad group name is \"#{ad_group[:name]}\" and id is #{ad_group[:id]}."
+        end
+     else
+       puts "No ad groups found for campaign ##{campaign_id}."
+     end
+
+    end
+
+  end
+end

data/lib/adapi/api.rb

@@ -0,0 +1,20 @@
+module Adapi
+  class Api
+
+    attr_accessor :adwords, :service, :version, :params
+
+    def initialize(params = {})
+      raise "Missing Service Name" unless params[:service_name]
+
+      puts "\n\nEXISTING INSTANCE USED\n\n" if params[:adwords_api_instance]
+
+      # if params[:api_login] in nil, default login data are used
+      # from ~/adwords_api.yml
+      @adwords = params[:adwords_api_instance] || AdwordsApi::Api.new(Adapi::Config.read)
+      @version = API_VERSION
+      @service = @adwords.service(params[:service_name].to_sym, @version)
+      @params = params
+    end
+
+  end
+end

data/lib/adapi/campaign.rb

@@ -0,0 +1,142 @@
+module Adapi
+  class Campaign < Api
+
+    def initialize(params = {})
+      params[:service_name] = :CampaignService
+      super(params)
+   end
+
+    # campaign data can be passed either as single hash:
+    # Campaign.create(:name => 'Campaign 123', :status => 'ENABLED')
+    # or as hash in a :data key:
+    # Campaign.create(:data => { :name => 'Campaign 123', :status => 'ENABLED' })
+    #
+    def self.create(params = {})
+      campaign_service = Campaign.new
+
+      # give users options to shorten input params
+      params = { :data => params } unless params.has_key?(:data)
+
+      # prepare for adding campaign
+      ad_groups = params[:data].delete(:ad_groups).to_a
+      targets = params[:data].delete(:targets)
+      
+      operation = { :operator => 'ADD', :operand => params[:data] }
+    
+      response = campaign_service.service.mutate([operation])
+
+      campaign = nil
+      if response and response[:value]
+        campaign = response[:value].first
+        puts "Campaign with name '%s' and ID %d was added." % [campaign[:name], campaign[:id]]
+      else
+        return nil
+      end
+
+      # create targets if they are available
+      if targets
+        Adapi::CampaignTarget.create(
+          :campaign_id => campaign[:id],
+          :targets => targets,
+          :api_adwords_instance => campaign_service.adwords
+        )
+      end
+
+      # if campaign has ad_groups, create them as well
+      ad_groups.each do |ad_group_data|
+        Adapi::AdGroup.create(
+          :data => ad_group_data.merge(:campaign_id => campaign[:id]),
+          :api_adwords_instance => campaign_service.adwords
+        )
+      end
+
+      campaign
+    end
+
+    # general method for changing campaign data
+    # TODO enable updating of all campaign parts at once, same as for Campaign#create method
+    # 
+    def self.update(params = {})
+      campaign_service = Campaign.new
+
+      # give users options to shorten input params
+      params = { :data => params } unless params.has_key?(:data)
+
+      campaign_id = params[:id] || params[:data][:id] || nil
+      return nil unless campaign_id
+      
+      operation = { :operator => 'SET',
+        :operand => params[:data].merge(:id => campaign_id.to_i)
+      }
+    
+      response = campaign_service.service.mutate([operation])
+
+      if response and response[:value]
+        campaign = response[:value].first
+        puts 'Campaign id %d successfully updated.' % campaign[:id]
+      else
+        puts 'No campaigns were updated.'
+      end
+
+      return campaign
+    end
+
+    def self.set_status(params = {})
+      params[:id] ||= (params[:data] || params[:data][:id]) || nil
+      return nil unless params[:id]
+      return nil unless %w{ ACTIVE PAUSED DELETED }.include?(params[:status])
+
+      self.update(:id => params[:id], :status => params[:status])
+    end
+
+    def self.activate(params = {})
+      self.set_status params.merge(:status => 'ACTIVE')
+    end
+
+    def self.pause(params = {})
+      self.set_status params.merge(:status => 'PAUSED')
+    end
+
+    def self.delete(params = {})
+      self.set_status params.merge(:status => 'DELETED')
+    end
+
+    def self.rename(params = {})
+      params[:id] ||= (params[:data] || params[:data][:id]) || nil
+      return nil unless (params[:id] && params[:name])
+
+      self.update(:id => params[:id], :name => params[:name])
+    end
+
+    def self.find(params = {})
+      campaign_service = Campaign.new
+
+      selector = {
+        :fields => ['Id', 'Name', 'Status']
+        # :predicates => [{ :field => 'Id', :operator => 'EQUALS', :values => '334315' }]
+        # :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}]
+      }
+
+      # set filtering conditions: find by id, status etc.
+      if params[:conditions]
+        selector[:predicates] = params[:conditions].map do |c|
+          { :field => c[0].to_s.capitalize, :operator => 'EQUALS', :values => c[1] }
+        end
+      end
+
+      response = campaign_service.service.get(selector)
+
+      return (response and response[:entries]) ? response[:entries].to_a : []
+    
+      if response
+        response[:entries].to_a.each do |campaign|
+          puts "Campaign name is \"#{campaign[:name]}\", id is #{campaign[:id]} " +
+              "and status is \"#{campaign[:status]}\"."
+        end
+      else
+        puts "No campaigns were found."
+      end
+    end
+
+  end
+end