update to version 11.12.3

Author: qitia

HISTORY.rst

@@ -1,44 +1,50 @@
 .. :changelog:
 
 Release History
+-----------
+11.12.3(2018-06-10)
+Added support for Cooperative bidding e.g., added mappings for "Bid Boost Value", "Bid Option" and "Maximum Bid" fields via the BulkAdGroup. 
+ 
+Added mappings for the 'MSCLKID Auto Tagging Enabled" and "Tracking Tempalte" fields via the BulkAccount.
+
 -----------
 11.12.2(2018-05-15)
 +++++++++++++++++++
-*To extend support for [Microsoft Audience Ads](https://docs.microsoft.com/en-us/bingads/guides/audience-ads), new bulk objects are added to the SDK for reading and writing Bulk file records e.g., BulkResponsiveAd and BulkResponsiveAdLabel. 
+*To extend support for Microsoft Audience Ads, new bulk objects are added to the SDK for reading and writing Bulk file records e.g., BulkResponsiveAd and BulkResponsiveAdLabel. 
 *Added retries for the 117 throttling error if encountered while polling for the status of a bulk or reporting operation. 
 
 ---------------
 11.12.1(2018-04-12)
 +++++++++++++++++++
-*Added support for Bing Ads API Version 12. For more information, see [Migrating to Bing Ads API Version 12](https://docs.microsoft.com/en-us/bingads/guides/migration-guide).
+*Added support for Bing Ads API Version 12. For more information, see Migrating to Bing Ads API Version 12.
 *The version parameter is now required when creating each ServiceClient. Previously the version was optional and defaulted to version 11. The version parameter is moved to the second position between the service client name and the authorization data. 
 *The file_type parameter now defaults to 'Csv' as an *str* datatype instead of the DownloadFileType for BulkFileReader, BulkServiceManager, DownloadParameters and SubmitDownloadParameters. You can set 'Tsv' if you prefer the tab separated file format type.  
 
 ---------------
 11.5.9(2018-03-12)
 +++++++++++++++++++
-*Updated to support [Microsoft Account authentication in sandbox](https://docs.microsoft.com/en-us/bingads/guides/sandbox.md#access). 
+*Updated to support Microsoft Account authentication in sandbox. 
 
 ---------------
 11.5.8(2018-01-12)
 +++++++++++++++++++
-*The Bulk and Campaign Management proxies are updated to support [audience search size](https://docs.microsoft.com/en-us/bingads/guides/release-notes#audiencesearchsize-january2018). In addition the SDK supports audience search size via the BulkCustomAudience, BulkInMarketAudience, and BulkRemarketingList classes.
+*The Bulk and Campaign Management proxies are updated to support audience search size. In addition the SDK supports audience search size via the BulkCustomAudience, BulkInMarketAudience, and BulkRemarketingList classes.
 	
 *Allow the Parent Id to be empty when deleting Bulk entities. Previously the Parent Id was required by the SDK although the Bulk service does not always require it.
 
 ---------------
 11.5.7(2017-12-12)
 +++++++++++++++++++
 
-*The Version 11 Reporting service proxies are updated to support new columns for [Estimated Bids](https://docs.microsoft.com/en-us/bingads/guides/release-notes#reporting-estimatedbids-november2017). 
+*The Version 11 Reporting service proxies are updated to support new columns for Estimated Bids. 
 
 11.5.6(2017-11-01)
 +++++++++++++++++++
 
 * Support for version 9 and 10 ended on October 31st, 2017. The following version 9 and 10 proxies are now removed from the SDK. You must upgrade to version 11.
   - Removed the Version 9 proxies for Customer Billing, Customer Management, and Reporting services. Also removed the Version 9 ReportingServiceManager.
   - Removed the Version 10 proxies for Ad Insight, Bulk, and Campaign Management services. Also removed the Version 10 BulkServiceManager and Version 10 Bulk entities.
-* The Version 11 Reporting service proxies are updated to support new columns for [Exact Match Impression Share Percent](https://docs.microsoft.com/en-us/bingads/guides/release-notes#reporting-exactmatchimpressionshare-october2017) and [Labels](https://docs.microsoft.com/en-us/bingads/guides/release-notes#reporting-labels-october2017).
+* The Version 11 Reporting service proxies are updated to support new columns for Exact Match Impression Share Percent and Labels.
 * Improved memory usage for decompressing the bulk and report files.
 * Set the default encoding to utf-8-sig and removed the chardet requirement. Bulk file download and upload should always be UTF-8 encoding with BOM.
 
@@ -50,16 +56,16 @@ Release History
 11.5.5(2017-09-13)
 +++++++++++++++++++
 
-* The [Reporting]( https://msdn.microsoft.com/library/bing-ads-overview-release-notes.aspx#reporting_locations_august2017) service proxies are updated to support new columns for location targeting.
+* The Reporting service proxies are updated to support new columns for location targeting.
 
 
 11.5.4(2017-08-08)
 +++++++++++++++++++
 
-* The [Campaign Management]( https://msdn.microsoft.com/library/bing-ads-overview-release-notes.aspx#inheritedbidstrategytype_july2017) service proxies are updated to support inherited bid strategy type.
-* The [Reporting]( https://msdn.microsoft.com/library/bing-ads-overview-release-notes.aspx#reporting_bsc_july2017) service proxies are updated to support new columns for Bing Shopping campaigns.
-* New version 11 bulk labels objects are added i.e., *BulkLabel*, *BulkCampaignLabel*, *BulkAdGroupLabel*, *BulkKeywordLabel*, *BulkAppInstallAdLabel*, *BulkDynamicSearchAdLabel*, *BulkExpandedTextAdLabel*, *BulkProductAdLabel*, and *BulkTextAdLabel* objects are added to the SDK for reading and writing the corresponding [Bulk file records]( https://msdn.microsoft.com/library/bing-ads-overview-release-notes.aspx#bulk_v11_labels_july2017).
-* A new version 11 bulk offline conversion object is added i.e., the *BulkOfflineConversion* object is added to the SDK for writing and uploading the corresponding [Bulk file record]( https://msdn.microsoft.com/library/bing-ads-overview-release-notes.aspx#bulk_v11_offline_conversions_july2017).
+* The Campaign Management service proxies are updated to support inherited bid strategy type.
+* The Reporting service proxies are updated to support new columns for Bing Shopping campaigns.
+* New version 11 bulk labels objects are added i.e., *BulkLabel*, *BulkCampaignLabel*, *BulkAdGroupLabel*, *BulkKeywordLabel*, *BulkAppInstallAdLabel*, *BulkDynamicSearchAdLabel*, *BulkExpandedTextAdLabel*, *BulkProductAdLabel*, and *BulkTextAdLabel* objects are added to the SDK for reading and writing the corresponding Bulk file records.
+* A new version 11 bulk offline conversion object is added i.e., the *BulkOfflineConversion* object is added to the SDK for writing and uploading the corresponding Bulk file record.
 
 
 10.4.12(2017-02-28)

bingads/authorization.py

@@ -625,7 +625,7 @@ def get_access_token(**kwargs):
             r.raise_for_status()
         except Exception:
             error_json = json.loads(r.text)
-            raise OAuthTokenRequestException(error_json['error'], error_json['error_description'])
+            raise OAuthTokenRequestException(error_json.get('error'), error_json.get('error_description'))
 
         r_json = json.loads(r.text)
         return OAuthTokens(r_json['access_token'], int(r_json['expires_in']), r_json['refresh_token'])

bingads/manifest.py

@@ -1,5 +1,5 @@
 import sys
-VERSION = '11.12.2'
+VERSION = '11.12.3'
 BULK_FORMAT_VERSION_5 = '5.0'
 BULK_FORMAT_VERSION_6 = '6.0'
 WORKING_NAME = 'BingAdsSDKPython'

bingads/v11/bulk/entities/bulk_account.py

@@ -23,6 +23,8 @@ def __init__(self, account_id=None, customer_id=None, sync_time=None):
         self._id = account_id
         self._customer_id = customer_id
         self._sync_time = sync_time
+        self._msclkid_auto_tagging_enabled = None
+        self._tracking_url_template = None
 
     @property
     def id(self):
@@ -60,6 +62,24 @@ def sync_time(self):
         """
 
         return self._sync_time
+    
+    @property
+    def msclkid_auto_tagging_enabled(self):
+        """ Determines whether auto-tagging of the MSCLKID query string parameter is enabled. The MSCLKID is a 32-character GUID that is unique for each ad click.
+        :return: The msclkid autotag setting of the account
+        :rtype: bool
+        """
+        return self._msclkid_auto_tagging_enabled    
+    
+    @property
+    def tracking_url_template(self):
+        """ The tracking template to use as a default for all URLs in your account.
+        
+        :return: The tracking template of the account
+        :rtype: str
+        """
+        return self._tracking_url_template    
+    
 
     _MAPPINGS = [
         _SimpleBulkMapping(
@@ -77,6 +97,16 @@ def sync_time(self):
             field_to_csv=lambda c: bulk_datetime_str(c.sync_time),
             csv_to_field=lambda c, v: setattr(c, '_sync_time', parse_datetime(v) if v else None)
         ),
+        _SimpleBulkMapping(
+            header=_StringTable.MSCLKIDAutoTaggingEnabled,
+            field_to_csv=lambda c: bulk_str(c.msclkid_auto_tagging_enabled),
+            csv_to_field=lambda c, v: setattr(c, '_msclkid_auto_tagging_enabled', parse_bool(v))
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.TrackingTemplate,
+            field_to_csv=lambda c: bulk_str(c.tracking_url_template),
+            csv_to_field=lambda c, v: setattr(c, '_tracking_url_template', v)
+        ),
     ]
 
     def process_mappings_from_row_values(self, row_values):

bingads/v11/bulk/entities/bulk_ad_group.py

@@ -238,17 +238,34 @@ def performance_data(self):
             csv_to_field=lambda c, v: setattr(c.ad_group, 'PrivacyStatus', v if v else None)
         ),
         _ComplexBulkMapping(bidding_scheme_to_csv, csv_to_bidding_scheme),
-        
+
         _SimpleBulkMapping(
             header=_StringTable.TargetSetting,
             field_to_csv=lambda c: target_setting_to_csv(c.ad_group),
             csv_to_field=lambda c, v: csv_to_target_setting(c.ad_group, v)
         ),
+
         _SimpleBulkMapping(
             header=_StringTable.RemarketingTargetingSetting,
             field_to_csv=lambda c: bulk_str(c.ad_group.RemarketingTargetingSetting),
             csv_to_field=lambda c, v: setattr(c.ad_group, 'RemarketingTargetingSetting', v if v else None)
         ),
+
+        _SimpleBulkMapping(
+            header=_StringTable.BidOption,
+            field_to_csv=lambda c: bid_option_to_csv(c.ad_group),
+            csv_to_field=lambda c, v: csv_to_bid_option(c.ad_group, v)
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.BidBoostValue,
+            field_to_csv=lambda c: bid_boost_value_to_csv(c.ad_group),
+            csv_to_field=lambda c, v: csv_to_bid_boost_value(c.ad_group, v)
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.MaximumBid,
+            field_to_csv=lambda c: maximum_bid_to_csv(c.ad_group),
+            csv_to_field=lambda c, v: csv_to_maximum_bid(c.ad_group, v)
+        ),
     ]
 
     def process_mappings_from_row_values(self, row_values):

bingads/v11/internal/bulk/csv_headers.py

@@ -172,6 +172,11 @@ class _CsvHeaders:
         _StringTable.CampaignType,
         _StringTable.CampaignPriority,
         _StringTable.LocalInventoryAdsEnabled,
+        
+        #CoOp
+        _StringTable.BidOption,
+        _StringTable.BidBoostValue,
+        _StringTable.MaximumBid,
 
         # V10 added
         _StringTable.FieldPath,
@@ -317,7 +322,10 @@ class _CsvHeaders:
         _StringTable.ConversionName,
         _StringTable.ConversionTime,
         _StringTable.ConversionValue,
-        _StringTable.MicrosoftClickId
+        _StringTable.MicrosoftClickId,
+        
+        # Account
+        _StringTable.MSCLKIDAutoTaggingEnabled
 
     ]
 

bingads/v11/internal/bulk/string_table.py

@@ -68,6 +68,7 @@ class _StringTable:
     Account = "Account"
     SyncTime = "Sync Time"
     Name = "Name"
+    MSCLKIDAutoTaggingEnabled = "MSCLKID Auto Tagging Enabled"
     LastModifiedTime = "Modified Time"
     AdFormatPreference = "Ad Format Preference"
 
@@ -225,6 +226,11 @@ class _StringTable:
     CampaignType = "Campaign Type"
     CampaignPriority = "Priority"
     LocalInventoryAdsEnabled = "LocalInventoryAdsEnabled"
+    
+    # CoOp
+    BidOption = "Bid Option"
+    BidBoostValue = "Bid Boost Value"
+    MaximumBid = "Maximum Bid"
 
     # V10 added
     FieldPath = "Field Path"

bingads/v11/internal/extensions.py

@@ -40,6 +40,7 @@
 LocationIntentCriterion = _CAMPAIGN_OBJECT_FACTORY_V11.create('LocationIntentCriterion')
 RadiusCriterion = _CAMPAIGN_OBJECT_FACTORY_V11.create('RadiusCriterion')
 TargetSetting_Type = type(_CAMPAIGN_OBJECT_FACTORY_V11.create('TargetSetting'))
+CoOpSetting_Type = type(_CAMPAIGN_OBJECT_FACTORY_V11.create('CoOpSetting'))
 
 def bulk_str(value):
     if value is None or (hasattr(value, 'value') and value.value is None):
@@ -438,7 +439,7 @@ def keyword_bid_bulk_str(value):
 
 def parse_keyword_bid(value):
     bid = _CAMPAIGN_OBJECT_FACTORY_V11.create('Bid')
-    if not value:
+    if not value or value == DELETE_VALUE:
         bid.Amount = None
     else:
         bid.Amount = float(value)
@@ -1183,11 +1184,72 @@ def parse_rule_PageVisitors(rule_str):
     rule.RuleItemGroups = parse_rule_groups(rule_str)
     return rule
 
+def maximum_bid_to_csv(ad_group):
+    if not ad_group.Settings or not ad_group.Settings.Setting:
+        return None
+    settings = [setting for setting in ad_group.Settings.Setting if isinstance(setting, CoOpSetting_Type)]
+    if len(settings) == 0:
+        return None
+    if len(settings) != 1:
+        raise ValueError('Can only have 1 CoOpSetting in AdGroup Settings.')
+    coop_setting = settings[0]
+    return coop_setting.BidMaxValue
+
+def csv_to_maximum_bid(ad_group, value):
+    coop_setting = validate_coop_setting(ad_group)
+    coop_setting.BidMaxValue = float(value) if value else None 
+    
+def bid_boost_value_to_csv(ad_group):
+    if not ad_group.Settings or not ad_group.Settings.Setting:
+        return None
+    settings = [setting for setting in ad_group.Settings.Setting if isinstance(setting, CoOpSetting_Type)]
+    if len(settings) == 0:
+        return None
+    if len(settings) != 1:
+        raise ValueError('Can only have 1 CoOpSetting in AdGroup Settings.')
+    coop_setting = settings[0]
+    return coop_setting.BidBoostValue
+
+def csv_to_bid_boost_value(ad_group, value):
+    coop_setting = validate_coop_setting(ad_group)
+    coop_setting.BidBoostValue = float(value) if value else None 
+
+def bid_option_to_csv(ad_group):
+    if not ad_group.Settings or not ad_group.Settings.Setting:
+        return None
+    settings = [setting for setting in ad_group.Settings.Setting if isinstance(setting, CoOpSetting_Type)]
+    if len(settings) == 0:
+        return None
+    if len(settings) != 1:
+        raise ValueError('Can only have 1 CoOpSetting in AdGroup Settings.')
+    coop_setting = settings[0]
+    return coop_setting.BidOption
+
+def csv_to_bid_option(ad_group, value):
+    coop_setting = validate_coop_setting(ad_group)
+    coop_setting.BidOption = value if value else None 
+
+def validate_coop_setting(ad_group):
+    settings = [setting for setting in ad_group.Settings.Setting if isinstance(setting, CoOpSetting_Type)]
+    if len(settings) == 0:
+        return create_coop_setting(ad_group)
+    
+    if len(settings) > 1:
+        raise ValueError('Can only have 1 CoOpSetting in AdGroup Settings.')
+    return settings[0]
+
+def create_coop_setting(ad_group):
+    coop_setting = _CAMPAIGN_OBJECT_FACTORY_V11.create('CoOpSetting')
+    coop_setting.Type = 'CoOpSetting'
+    ad_group.Settings.Setting.append(coop_setting)
+    return coop_setting
 
 def target_setting_to_csv(ad_group):
     if not ad_group.Settings or not ad_group.Settings.Setting:
         return None
     settings = [setting for setting in ad_group.Settings.Setting if isinstance(setting, TargetSetting_Type)]
+    if len(settings) == 0:
+        return None
     if len(settings) != 1:
         raise ValueError('Can only have 1 TargetSetting in AdGroup Settings.')
     target_setting = settings[0]

bingads/v12/bulk/entities/bulk_account.py

@@ -23,6 +23,8 @@ def __init__(self, account_id=None, customer_id=None, sync_time=None):
         self._id = account_id
         self._customer_id = customer_id
         self._sync_time = sync_time
+        self._msclkid_auto_tagging_enabled = None
+        self._tracking_url_template = None
 
     @property
     def id(self):
@@ -61,6 +63,23 @@ def sync_time(self):
 
         return self._sync_time
 
+    @property
+    def msclkid_auto_tagging_enabled(self):
+        """ Determines whether auto-tagging of the MSCLKID query string parameter is enabled. The MSCLKID is a 32-character GUID that is unique for each ad click.
+        :return: The msclkid autotag setting of the account
+        :rtype: bool
+        """
+        return self._msclkid_auto_tagging_enabled    
+    
+    @property
+    def tracking_url_template(self):
+        """ The tracking template to use as a default for all URLs in your account.
+        
+        :return: The tracking template of the account
+        :rtype: str
+        """
+        return self._tracking_url_template    
+    
     _MAPPINGS = [
         _SimpleBulkMapping(
             header=_StringTable.Id,
@@ -77,6 +96,16 @@ def sync_time(self):
             field_to_csv=lambda c: bulk_datetime_str(c.sync_time),
             csv_to_field=lambda c, v: setattr(c, '_sync_time', parse_datetime(v) if v else None)
         ),
+        _SimpleBulkMapping(
+            header=_StringTable.MSCLKIDAutoTaggingEnabled,
+            field_to_csv=lambda c: bulk_str(c.msclkid_auto_tagging_enabled),
+            csv_to_field=lambda c, v: setattr(c, '_msclkid_auto_tagging_enabled', parse_bool(v))
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.TrackingTemplate,
+            field_to_csv=lambda c: bulk_str(c.tracking_url_template),
+            csv_to_field=lambda c, v: setattr(c, '_tracking_url_template', v)
+        ),
     ]
 
     def process_mappings_from_row_values(self, row_values):

bingads/v12/bulk/entities/bulk_ad_group.py

@@ -216,6 +216,21 @@ def performance_data(self):
             field_to_csv=lambda c: bulk_str(c.ad_group.PrivacyStatus),
             csv_to_field=lambda c, v: setattr(c.ad_group, 'PrivacyStatus', v if v else None)
         ),
+        _SimpleBulkMapping(
+            header=_StringTable.BidOption,
+            field_to_csv=lambda c: bid_option_to_csv(c.ad_group),
+            csv_to_field=lambda c, v: csv_to_bid_option(c.ad_group, v)
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.BidBoostValue,
+            field_to_csv=lambda c: bid_boost_value_to_csv(c.ad_group),
+            csv_to_field=lambda c, v: csv_to_bid_boost_value(c.ad_group, v)
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.MaximumBid,
+            field_to_csv=lambda c: maximum_bid_to_csv(c.ad_group),
+            csv_to_field=lambda c, v: csv_to_maximum_bid(c.ad_group, v)
+        ),
     ]
 
     def process_mappings_from_row_values(self, row_values):