Class: BingAdsApi::CampaignManagement

Inherits:
Service
  • Object
show all
Defined in:
lib/bing-ads-api/service/campaign_management.rb

Overview

Public : This class represents the Campaign Management Services defined in the Bing Ads API, to manage advertising campaigns

Author

[email protected]

Examples

options = {
  :environment => :sandbox,
  :username => "username",
  :password => "pass",
  :developer_token => "SOME_TOKEN",
  :customer_id => "1234567",
  :account_id => "9876543" }
service = BingAdsApi::CampaignManagement.new(options)

Constant Summary

Constants inherited from Service

Service::LOGGER

Instance Attribute Summary

Attributes inherited from Service

#client_proxy, #environment

Instance Method Summary collapse

Methods inherited from Service

#call, #get_response_hash

Constructor Details

#initialize(options = {}) ⇒ CampaignManagement

Public : Constructor

Author

[email protected]

options - Hash with the parameters for the client proxy and the environment

Examples

options = {
  :environment => :sandbox,
  :username => "username",
  :password => "password",
  :developer_token => "DEV_TOKEN",
  :customer_id => "123456",
  :account_id => "654321"
}
service = BingAdsApi::CampaignManagement.new(options)



38
39
40
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 38

def initialize(options={})
	super(options)
end

Instance Method Details

#add_ad_groups(campaign_id, ad_groups) ⇒ Object

Public : Adds 1 or more AdGroups to a Campaign

Author

[email protected]

Parameters

campaing_id - the campaign id where the ad groups will be added ad_groups - Array ad groups to be added

Examples 

service.add_ad_groups(1, [<BingAdsApi::AdGroup>]) 
# => <Hash>
Returns

Hash with the ‘add_ad_groups_response’ structure

Raises

exception



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 214

def add_ad_groups(campaign_id, ad_groups)
	
	groups = []
	if ad_groups.is_a? Array
		groups = ad_groups.map{ |gr| gr.to_hash(:camelcase) }
	elsif ad_groups.is_a? BingAdsApi::AdGroup
		groups = ad_groups.to_hash
	else 
		raise "ad_groups must be an array of BingAdsApi::AdGroup"
	end
	message = {
		:campaign_id => campaign_id, 
		:ad_groups => {:ad_group => groups} }
	puts message
	response = call(:add_ad_groups, message)
	return get_response_hash(response, __method__)
end

#add_ads(ad_group_id, ads) ⇒ Object

Public : Add ads into a specified ad group

Author

[email protected]

Parameters

ad_group_id - a number with the id where the ads should be added ads - an array of BingAdsApi::Ad instances

Examples

# if the operation returns partial errors 
service.add_ads(1, [BingAdsApi::Ad]) 
# => {:ad_ids => [], :partial_errors => BingAdsApi::PartialErrors } 

# if the operation doesn't return partial errors 
service.add_ads(1, [BingAdsApi::Ad]) 
# => {:ad_ids => [] }
Returns

Hash with the AddAdsResponse structure.

If the operation returns ‘PartialErrors’ key, this methods returns those errors as an BingAdsApi::PartialErrors instance

Raises

exception



353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 353

def add_ads(ad_group_id, ads)
	
	ads_for_soap = []
	if ads.is_a? Array
		ads_for_soap = ads.map{ |ad| ad_to_hash(ad, :camelcase) }
	elsif ads.is_a? BingAdsApi::Ad
		ads_for_soap = ad_to_hash(ads, :camelcase)
	else 
		raise "ads must be an array or instance of BingAdsApi::Ad"
	end
	message = {
		:ad_group_id => ad_group_id, 
		:ads => {:ad => ads_for_soap} }
	puts message
	response = call(:add_ads, message)

	response_hash = get_response_hash(response, __method__)

	# Checks if there are partial errors in the request
	if response_hash[:partial_errors].key?(:batch_error) 
		partial_errors = BingAdsApi::PartialErrors.new(
			response_hash[:partial_errors])
		response_hash[:partial_errors] = partial_errors
	else 
		response_hash.delete(:partial_errors)
	end
	
	return response_hash
end

#add_campaigns(account_id, campaigns) ⇒ Object

Public : Adds a campaign to the specified account

Author

[email protected]

Parameters

account_id - account who will own the newly campaigns campaigns - An array of BingAdsApi::Campaign

Examples 

service.add_campaigns(1, [<BingAdsApi::Campaign>]) 
# => <Hash>
Returns

hash with the ‘add_campaigns_response’ structure

Raises

exception



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 87

def add_campaigns(, campaigns)
	
	camps = []
	if campaigns.is_a? Array
		camps = campaigns.map{ |camp| camp.to_hash(:camelcase) }
	elsif campaigns.is_a? BingAdsApi::Campaign
		camps = campaigns.to_hash
	else 
		raise "campaigns must be an array of BingAdsApi::Campaigns"
	end
	message = {
		:account_id => , 
		:campaigns => {:campaign => camps} }
	puts message
	response = call(:add_campaigns, message)
	return get_response_hash(response, __method__)
end

#get_ad_groups_by_campaign_id(campaign_id) ⇒ Object

Public : Returns all the ad groups that belongs to the specified campaign

Author

[email protected]

Parameters

campaign_id - campaign id

Examples 

service.get_ad_groups_by_campaign_id(1) 
# => Array[AdGroups]
Returns

Array with all the ad groups present in campaign_id

Raises

exception



157
158
159
160
161
162
163
164
165
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 157

def get_ad_groups_by_campaign_id(campaign_id)
	response = call(:get_ad_groups_by_campaign_id, 
		{campaign_id: campaign_id})
	response_hash = get_response_hash(response, __method__)
	ad_groups = response_hash[:ad_groups][:ad_group].map do |ad_group_hash|
		BingAdsApi::AdGroup.new(ad_group_hash)
	end
	return ad_groups
end

#get_ad_groups_by_ids(campaign_id, ad_groups_ids) ⇒ Object

Public : Returns the specified ad groups that belongs to the specified campaign

Author

[email protected]

Parameters

campaign_id - campaign id ad_groups_ids - array with ids from ad groups

Examples 

service.get_ad_groups_by_ids(1, [1,2,3]) 
# => Array[AdGroups]
Returns

Array with the ad groups specified in the ad_groups_ids array

Raises

exception



184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 184

def get_ad_groups_by_ids(campaign_id, ad_groups_ids)
	
	message = {
		:campaign_id => campaign_id,
		:ad_group_ids => {"ins1:long" => ad_groups_ids} }
	response = call(:get_ad_groups_by_ids, message)
	response_hash = get_response_hash(response, __method__)
	ad_groups = response_hash[:ad_groups][:ad_group].map do |ad_group_hash|
		BingAdsApi::AdGroup.new(ad_group_hash)
	end
	return ad_groups
	
end

#get_ads_by_ad_group_id(ad_group_id) ⇒ Object

Public : Obtains all the ads associated to the specified ad group

Author

[email protected]

Parameters

ad_group_id - long with the ad group id

Examples 

service.get_ads_by_ad_group_id(1) 
# => [<BingAdsApi::Ad]
Returns

An array of BingAdsApi::Ad

Raises

exception



279
280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 279

def get_ads_by_ad_group_id(ad_group_id)
	response = call(:get_ads_by_ad_group_id, 
		{ad_group_id: ad_group_id})
	response_hash = get_response_hash(response, __method__)
	
	if response_hash[:ads][:ad].is_a?(Array)
		ads = response_hash[:ads][:ad].map do |ad_hash|
			initialize_ad(ad_hash)
		end
	else
		ads = [ initialize_ad(response_hash[:ads][:ad]) ]
	end
	return ads
end

#get_ads_by_ids(ad_group_id, ad_ids) ⇒ Object

Public : Obtains the ads indicated in ad_ids associated to the specified ad group

Author

[email protected]

Parameters

ad_group_id - long with the ad group id ads_id - an Array io ads ids, that are associated to the ad_group_id provided

Examples 

service.get_ads_by_ids(1, [1,2,3]) 
# => [<BingAdsApi::Ad>]
Returns

An array of BingAdsApi::Ad

Raises

exception



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 310

def get_ads_by_ids(ad_group_id, ad_ids)


	message = {
		:ad_group_id => ad_group_id,
		:ad_ids => {"ins1:long" => ad_ids} }
	response = call(:get_ads_by_ids, message)
	response_hash = get_response_hash(response, __method__)
	
	if response_hash[:ads][:ad].is_a?(Array)
		ads = response_hash[:ads][:ad].map do |ad_hash|
			initialize_ad(ad_hash)
		end
	else
		ads = [ initialize_ad(response_hash[:ads][:ad]) ]
	end
	return ads
end

#get_campaigns_by_account_id(account_id) ⇒ Object

Public : Returns all the campaigns found in the specified account

Author

[email protected]

Parameters

account_id - account who owns the campaigns

Examples 

campaign_management_service.(1) 
# => Array[BingAdsApi::Campaign]
Returns

Array of BingAdsApi::Campaign

Raises

exception



61
62
63
64
65
66
67
68
69
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 61

def ()
	response = call(:get_campaigns_by_account_id, 
		{account_id: })
	response_hash = get_response_hash(response, __method__)
	campaigns = response_hash[:campaigns][:campaign].map do |camp_hash|
		BingAdsApi::Campaign.new(camp_hash)
	end
	return campaigns
end

#update_ad_groups(campaign_id, ad_groups) ⇒ Object

Public : Updates on or more ad groups in a specified campaign

Author

[email protected]

Parameters

campaign_id - campaign who owns the updated ad groups

Examples 

service.update_ad_groups(1, [<BingAdsApi::AdGroup]) 
# => true
Returns

boolean. true if the updates is successfull. false otherwise

Raises

exception



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 247

def update_ad_groups(campaign_id, ad_groups)
	groups = []
	if ad_groups.is_a? Array
		groups = ad_groups.map{ |gr| gr.to_hash(:camelcase) }
	elsif ad_groups.is_a? BingAdsApi::AdGroup
		groups = ad_groups.to_hash(:camelcase)
	else 
		raise "ad_groups must be an array or instance of BingAdsApi::AdGroup"
	end
	message = {
		:campaign_id => campaign_id, 
		:ad_groups => {:ad_group => groups} }
	puts message
	response = call(:update_ad_groups, message)
	return get_response_hash(response, __method__)
end

#update_ads(ad_group_id, ads) ⇒ Object

Public : Updates ads for the specified ad group

Author

[email protected]

Parameters

ad_group_id - long with the ad group id ads - array of BingAdsApi::Ad subclasses instances to update

Examples 

service.update_ads(1, [<BingAdsApi::Ad>]) 
# => Hash
Returns

Hash with the UpdateAddsResponse structure

Raises

exception



399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 399

def update_ads(ad_group_id, ads)

	ads_for_soap = []
	if ads.is_a? Array
		ads_for_soap = ads.map{ |ad| ad_to_hash(ad, :camelcase) }
	elsif ads.is_a? BingAdsApi::Ad
		ads_for_soap = ad_to_hash(ads, :camelcase)
	else 
		raise "ads must be an array or instance of BingAdsApi::Ad"
	end
	message = {
		:ad_group_id => ad_group_id, 
		:ads => {:ad => ads_for_soap} }
	puts message
	response = call(:update_ads, message)

	response_hash = get_response_hash(response, __method__)

	# Checks if there are partial errors in the request
	if response_hash[:partial_errors].key?(:batch_error) 
		partial_errors = BingAdsApi::PartialErrors.new(
			response_hash[:partial_errors])
		response_hash[:partial_errors] = partial_errors
	else 
		response_hash.delete(:partial_errors)
	end
	
	return response_hash
end

#update_campaigns(account_id, campaigns) ⇒ Object

Public : Updates on or more campaigns for the specified account

Author

[email protected]

Parameters

account_id - account who own the updated campaigns campaigns - Array with the campaigns to be updated

Examples 

service_update_campaigns(1, [<BingAdsApi::Campaign]) 
# =>  true
Returns

boolean. true if the update was successful. false otherwise

Raises

exception



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/bing-ads-api/service/campaign_management.rb', line 121

def update_campaigns(, campaigns)
	camps = []
	if campaigns.is_a? Array
		camps = campaigns.map do |camp| 
			camp.to_hash(:camelcase) 
		end
	elsif campaigns.is_a? BingAdsApi::Campaign
		camps = campaigns.to_hash
	else 
		raise "campaigns must be an array of BingAdsApi::Campaigns"
	end
	message = {
		:account_id => , 
		:campaigns => {:campaign => camps} }
	puts message
	response = call(:update_campaigns, message)
	return get_response_hash(response, __method__)
	
end