Merge pull request BingAds#185 from BingAds/jianyun/13.0.10

release python sdk 13.0.10

Author: qitia

HISTORY.rst

@@ -1,6 +1,22 @@
 .. :changelog:
 
 Release History
+13.0.10(2021-06-20)
++++++++++++++++++++++++++
+
+* Update Bing Ads API Version 13 service proxies to reflect recent interface changes. For details please see the Bing Ads API Release Notes: https://docs.microsoft.com/en-us/bingads/guides/release-notes
+* Add new msads.manage scope for multi-factor authentication requirement. Eventually msads.manage will be required. Learn more here: https://go.microsoft.com/fwlink/?linkid=2155062
+* Default OAuth scope is set to the new msads.manage scope. Can be overridden temporarily with new oAuthScope parameter (replaces requireLiveConnect). 
+* Sandbox auth support via login.live-int.com is replaced with login.windows-ppe.net. 
+* Add BulkVideo for video ads support
+* Add mappings for new fields in BulkResponsiveAd: CallToActionLanguage, Videos, Headlines, Descriptions
+* Add mappings for new fields in BulkAdGroup: CpvBid, CpmBid
+* Update  ToBiddingSchemeBulkString(this BiddingScheme biddingScheme) to support MaxRoas, ManualCpv and ManualCpm
+* Add mappings for new fields in BulkAccount: AdClickParallelTracking, AutoApplyRecommendations, AllowImageAutoRetrieve
+* Conjunctive normal form (CNF) support is added to PageVisitorsRule and mapped in the BulkRemarketingList remarketing rule. Previously Microsoft Advertising only supported disjunctive normal form (DNF). You must ensure that your application can appropriately read and distinguish between CNF and DNF. Your application should no longer assume that the rule is disjunctive.
+* Add mapping for new MultimediaAdsBidAdjustment field in BulkCampaign and BulkAdGroup 
+* Fix issue of DSA setting not being exported for Search Campaign
+
 13.0.9.1(2021-04-29)
 +++++++++++++++++++++++++
 * Fix issue of missing proxies.

bingads/authorization.py

@@ -11,6 +11,9 @@
 
 PRODUCTION='production'
 SANDBOX='sandbox'
+MSADS_MANAGE='msads.manage'
+ADS_MANAGE='ads.manage'
+BINGADS_MANAGE='bingads.manage'
 
 class AuthorizationData:
     """ Represents a user who intends to access the corresponding customer and account.
@@ -285,7 +288,7 @@ class OAuthAuthorization(Authentication):
     * :class:`.OAuthWebAuthCodeGrant`
     """
 
-    def __init__(self, client_id, oauth_tokens=None, env=PRODUCTION, require_live_connect=False, tenant='common'):
+    def __init__(self, client_id, oauth_tokens=None, env=PRODUCTION, oauth_scope=MSADS_MANAGE, tenant='common'):
         """ Initializes a new instance of the OAuthAuthorization class.
 
         :param client_id: The client identifier corresponding to your registered application.
@@ -301,7 +304,7 @@ def __init__(self, client_id, oauth_tokens=None, env=PRODUCTION, require_live_co
         self._oauth_tokens = oauth_tokens
         self._state = None
         self.environment=env
-        self._require_live_connect=require_live_connect
+        self._oauth_scope=oauth_scope
         self._tenant = tenant
 
     @property
@@ -384,7 +387,7 @@ class OAuthWithAuthorizationCode(OAuthAuthorization):
     For more information about registering a Bing Ads application, see http://go.microsoft.com/fwlink/?LinkID=511607.
     """
 
-    def __init__(self, client_id, client_secret, redirection_uri, token_refreshed_callback=None, oauth_tokens=None, env=PRODUCTION, require_live_connect=False, tenant="common"):
+    def __init__(self, client_id, client_secret, redirection_uri, token_refreshed_callback=None, oauth_tokens=None, env=PRODUCTION, oauth_scope=MSADS_MANAGE, tenant="common"):
         """ Initialize a new instance of this class.
 
         :param client_id: The client identifier corresponding to your registered application.
@@ -401,7 +404,7 @@ def __init__(self, client_id, client_secret, redirection_uri, token_refreshed_ca
         :return:
         """
 
-        super(OAuthWithAuthorizationCode, self).__init__(client_id, oauth_tokens=oauth_tokens, env=env, require_live_connect=require_live_connect, tenant=tenant)
+        super(OAuthWithAuthorizationCode, self).__init__(client_id, oauth_tokens=oauth_tokens, env=env, oauth_scope=oauth_scope, tenant=tenant)
         self._client_secret = client_secret
         self._redirection_uri = redirection_uri
         self._token_refreshed_callback = token_refreshed_callback
@@ -412,8 +415,8 @@ def get_authorization_endpoint(self):
         :return: The Microsoft Account authorization endpoint.
         :rtype: str
         """
-        endpoint_url = _UriOAuthService.AUTHORIZE_URI[(self.environment, self._require_live_connect)]
-        if self.environment == PRODUCTION and self._require_live_connect == False:
+        endpoint_url = _UriOAuthService.AUTHORIZE_URI[(self.environment, self._oauth_scope)]
+        if self.environment == PRODUCTION and (self._oauth_scope == MSADS_MANAGE or self._oauth_scope == ADS_MANAGE):
             endpoint_url = endpoint_url.replace('common', self.tenant);
 
         endpoint = str.format(
@@ -453,7 +456,7 @@ def request_oauth_tokens_by_response_uri(self, response_uri, **kwargs):
             grant_type='authorization_code',
             environment=self.environment,
             code=code,
-            requireliveconnect=self._require_live_connect,
+            oauth_scope=self._oauth_scope,
             tenant=self.tenant,
             **kwargs
         )
@@ -480,8 +483,8 @@ def request_oauth_tokens_by_refresh_token(self, refresh_token):
             grant_type='refresh_token',
             refresh_token=refresh_token,
             environment=self.environment,
-            scope=_UriOAuthService.SCOPE[(self.environment, self._require_live_connect)],
-            requireliveconnect=self._require_live_connect,
+            scope=_UriOAuthService.SCOPE[(self.environment, self._oauth_scope)],
+            oauth_scope=self._oauth_scope,
             tenant = self.tenant
         )
         if self.token_refreshed_callback is not None:
@@ -543,7 +546,7 @@ class OAuthDesktopMobileAuthCodeGrant(OAuthWithAuthorizationCode):
     For more information about registering a Bing Ads application, see http://go.microsoft.com/fwlink/?LinkID=511607.
     """
 
-    def __init__(self, client_id, oauth_tokens=None, env=PRODUCTION, require_live_connect=False, tenant='common'):
+    def __init__(self, client_id, oauth_tokens=None, env=PRODUCTION, oauth_scope=MSADS_MANAGE, tenant='common'):
         """ Initializes a new instance of the this class with the specified client id.
 
         :param client_id: The client identifier corresponding to your registered application.
@@ -555,10 +558,10 @@ def __init__(self, client_id, oauth_tokens=None, env=PRODUCTION, require_live_co
         super(OAuthDesktopMobileAuthCodeGrant, self).__init__(
             client_id,
             None,
-            _UriOAuthService.REDIRECTION_URI[(env, require_live_connect)],
+            _UriOAuthService.REDIRECTION_URI[(env, oauth_scope)],
             oauth_tokens=oauth_tokens,
             env=env,
-            require_live_connect=require_live_connect,
+            oauth_scope=oauth_scope,
             tenant=tenant
         )
 
@@ -593,7 +596,7 @@ class OAuthDesktopMobileImplicitGrant(OAuthAuthorization):
     """
 
 
-    def __init__(self, client_id, oauth_tokens=None, env=PRODUCTION, require_live_connect=False, tenant='common'):
+    def __init__(self, client_id, oauth_tokens=None, env=PRODUCTION, oauth_scope=MSADS_MANAGE, tenant='common'):
         """ Initializes a new instance of the this class with the specified client id.
 
         :param client_id: The client identifier corresponding to your registered application.
@@ -602,7 +605,7 @@ def __init__(self, client_id, oauth_tokens=None, env=PRODUCTION, require_live_co
         :type oauth_tokens: OAuthTokens
         """
 
-        super(OAuthDesktopMobileImplicitGrant, self).__init__(client_id, oauth_tokens=oauth_tokens, env=env, require_live_connect=require_live_connect, tenant=tenant)
+        super(OAuthDesktopMobileImplicitGrant, self).__init__(client_id, oauth_tokens=oauth_tokens, env=env, oauth_scope=oauth_scope, tenant=tenant)
 
 
 
@@ -613,14 +616,14 @@ def get_authorization_endpoint(self):
         :rtype: str
         """
 
-        endpoint_url = _UriOAuthService.AUTHORIZE_URI[(self.environment, self._require_live_connect)]
-        if self.environment == PRODUCTION and self._require_live_connect == False:
+        endpoint_url = _UriOAuthService.AUTHORIZE_URI[(self.environment, self._oauth_scope)]
+        if self.environment == PRODUCTION and (self._oauth_scope == MSADS_MANAGE or self._oauth_scope == ADS_MANAGE):
             endpoint_url = endpoint_url.replace('common', self.tenant);
         endpoint = str.format(
             endpoint_url,
             self.client_id,
             'token',
-            _UriOAuthService.REDIRECTION_URI[(self.environment, self._require_live_connect)],
+            _UriOAuthService.REDIRECTION_URI[(self.environment, self._oauth_scope)],
         )
 
         return endpoint if self.state is None else endpoint + '&state=' + self.state
@@ -650,7 +653,7 @@ def extract_access_token_from_uri(self, redirection_uri):
 
     @property
     def redirection_uri(self):
-        return _UriOAuthService.REDIRECTION_URI[(self.environment, self._require_live_connect)]
+        return _UriOAuthService.REDIRECTION_URI[(self.environment, self._oauth_scope)]
 
 
 class _UriOAuthService:
@@ -659,21 +662,29 @@ class _UriOAuthService:
     def __init__(self):
         pass
 
-    REDIRECTION_URI={(PRODUCTION, True):'https://login.live.com/oauth20_desktop.srf',
-                      (PRODUCTION, False):'https://login.microsoftonline.com/common/oauth2/nativeclient',
-                      (SANDBOX, False):'https://login.live-int.com/oauth20_desktop.srf'
+    REDIRECTION_URI={
+        (PRODUCTION, MSADS_MANAGE):   'https://login.microsoftonline.com/common/oauth2/nativeclient',
+        (PRODUCTION, ADS_MANAGE):     'https://login.microsoftonline.com/common/oauth2/nativeclient',
+        (PRODUCTION, BINGADS_MANAGE): 'https://login.live.com/oauth20_desktop.srf',
+        (SANDBOX, MSADS_MANAGE):      'https://login.windows-ppe.net/common/oauth2/nativeclient'
     }
-    AUTH_TOKEN_URI={(PRODUCTION, True):'https://login.live.com/oauth20_token.srf',
-                    (PRODUCTION, False):'https://login.microsoftonline.com/common/oauth2/v2.0/token',
-                    (SANDBOX, False):'https://login.live-int.com/oauth20_token.srf'
+    AUTH_TOKEN_URI={
+        (PRODUCTION, MSADS_MANAGE):   'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+        (PRODUCTION, ADS_MANAGE):     'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+        (PRODUCTION, BINGADS_MANAGE): 'https://login.live.com/oauth20_token.srf',
+        (SANDBOX, MSADS_MANAGE):      'https://login.windows-ppe.net/consumers/oauth2/v2.0/token'
     }
-    AUTHORIZE_URI={(PRODUCTION, True):'https://login.live.com/oauth20_authorize.srf?client_id={0}&scope=bingads.manage&response_type={1}&redirect_uri={2}', 
-                   (PRODUCTION, False):'https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={0}&scope=https%3A%2F%2Fads.microsoft.com%2Fads.manage%20offline_access&response_type={1}&redirect_uri={2}',
-                   (SANDBOX, False):'https://login.live-int.com/oauth20_authorize.srf?client_id={0}&scope=bingads.manage&response_type={1}&redirect_uri={2}&prompt=login'
+    AUTHORIZE_URI={
+        (PRODUCTION, MSADS_MANAGE):   'https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={0}&scope=https%3A%2F%2Fads.microsoft.com%2Fmsads.manage%20offline_access&response_type={1}&redirect_uri={2}', 
+        (PRODUCTION, ADS_MANAGE):     'https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={0}&scope=https%3A%2F%2Fads.microsoft.com%2Fads.manage%20offline_access&response_type={1}&redirect_uri={2}',
+        (PRODUCTION, BINGADS_MANAGE): 'https://login.live.com/oauth20_authorize.srf?client_id={0}&scope=bingads.manage&response_type={1}&redirect_uri={2}',
+        (SANDBOX, MSADS_MANAGE):      'https://login.windows-ppe.net/consumers/oauth2/v2.0/authorize?client_id={0}&scope=https://api.ads.microsoft.com/msads.manage%20offline_access&response_type={1}&redirect_uri={2}&prompt=login'
     }
-    SCOPE={(PRODUCTION, True):'bingads.manage', 
-                   (PRODUCTION, False):'https://ads.microsoft.com/ads.manage offline_access',
-                   (SANDBOX, False):'bingads.manage'
+    SCOPE={
+        (PRODUCTION, MSADS_MANAGE):   'https://ads.microsoft.com/msads.manage offline_access', 
+        (PRODUCTION, ADS_MANAGE):     'https://ads.microsoft.com/ads.manage offline_access', 
+        (PRODUCTION, BINGADS_MANAGE): 'bingads.manage',
+        (SANDBOX, MSADS_MANAGE):      'https://api.ads.microsoft.com/msads.manage offline_access'
     }
 
     @staticmethod
@@ -689,10 +700,10 @@ def get_access_token(**kwargs):
         if 'client_secret' in kwargs and kwargs['client_secret'] is None:
             del kwargs['client_secret']
 
-        if 'requireliveconnect' in kwargs and kwargs['requireliveconnect'] == True:
+        if 'oauth_scope' in kwargs and kwargs['oauth_scope'] == 'bingads.manage':
             del kwargs['tenant']
 
-        auth_token_url = _UriOAuthService.AUTH_TOKEN_URI[(kwargs['environment'], kwargs['requireliveconnect'])]
+        auth_token_url = _UriOAuthService.AUTH_TOKEN_URI[(kwargs['environment'], kwargs['oauth_scope'])]
 
         if 'tenant' in kwargs and kwargs['tenant'] is not None:
             auth_token_url = auth_token_url.replace('common', kwargs['tenant'])

bingads/manifest.py

@@ -1,5 +1,5 @@
 import sys
-VERSION = '13.0.9.1'
+VERSION = '13.0.10'
 BULK_FORMAT_VERSION_6 = '6.0'
 WORKING_NAME = 'BingAdsSDKPython'
 USER_AGENT = '{0} {1} {2}'.format(WORKING_NAME, VERSION, sys.version_info[0:3])

bingads/v13/bulk/entities/__init__.py

@@ -30,4 +30,5 @@
 from .bulk_offline_conversion import *
 from .bulk_experiment import *
 from .bulk_image import *
+from .bulk_video import *
 from .feeds import *

bingads/v13/bulk/entities/audiences/bulk_campaign_negative_audience_association.py

@@ -4,7 +4,6 @@
 from bingads.v13.internal.bulk.mappings import _SimpleBulkMapping
 from bingads.v13.internal.bulk.string_table import _StringTable
 from bingads.v13.internal.extensions import *
-from docutils.nodes import row
 
 
 class BulkCampaignNegativeAudienceAssociation(BulkCampaignNegativeCriterion):

bingads/v13/bulk/entities/audiences/bulk_customer_list_item.py

@@ -31,6 +31,8 @@ def __init__(self, audience=None, parent_id=None, sub_type=None, text = None):
     def audience(self):
         """
         the audience, see more detail at: https://go.microsoft.com/fwlink/?linkid=846127
+        
+        :rtype: str
         """
         return self._audience
 
@@ -87,7 +89,7 @@ def text(self, value):
         _SimpleBulkMapping(
             header=_StringTable.Audience,
             field_to_csv=lambda c: bulk_str(c.audience),
-            csv_to_field=lambda c, v: setattr(c, 'audience', ve)
+            csv_to_field=lambda c, v: setattr(c, 'audience', v)
         ),
         _SimpleBulkMapping(
             header=_StringTable.SubType,

bingads/v13/bulk/entities/bulk_account.py

@@ -28,6 +28,9 @@ def __init__(self, account_id=None, customer_id=None, sync_time=None):
         self._profile_expansion_enabled = None
         self._tracking_url_template = None
         self._final_url_suffix = None
+        self._ad_click_parallel_tracking=None
+        self._auto_apply_recommendations = None
+        self._allow_image_auto_retrieve = None
 
     @property
     def id(self):
@@ -111,6 +114,45 @@ def final_url_suffix(self):
     @final_url_suffix.setter
     def final_url_suffix(self, v):
         self._final_url_suffix = v
+        
+    @property
+    def ad_click_parallel_tracking(self):
+        """ The setting of parallel tracking in the account.
+        
+        :return: The setting of parallel tracking of the account
+        :rtype: bool
+        """
+        return self._ad_click_parallel_tracking
+    
+    @ad_click_parallel_tracking.setter
+    def ad_click_parallel_tracking(self, v):
+        self._ad_click_parallel_tracking = v
+        
+    @property
+    def allow_image_auto_retrieve(self):
+        """ The setting of allowing image auto retrieve in the account.
+        
+        :return: The setting of allowing image auto retrieve of the account
+        :rtype: bool
+        """
+        return self._allow_image_auto_retrieve
+    
+    @allow_image_auto_retrieve.setter
+    def allow_image_auto_retrieve(self, v):
+        self._allow_image_auto_retrieve = v        
+        
+    @property
+    def auto_apply_recommendations(self):
+        """ The setting of allowing image auto retrieve in the account.
+        
+        :return: The setting of allowing image auto retrieve of the account
+        :rtype: dict
+        """
+        return self._auto_apply_recommendations
+    
+    @auto_apply_recommendations.setter
+    def auto_apply_recommendations(self, v):
+        self._auto_apply_recommendations = v        
 
     _MAPPINGS = [
         _SimpleBulkMapping(
@@ -153,6 +195,21 @@ def final_url_suffix(self, v):
             field_to_csv=lambda c: bulk_str(c.profile_expansion_enabled),
             csv_to_field=lambda c, v: setattr(c, '_profile_expansion_enabled', parse_bool(v))
         ),
+        _SimpleBulkMapping(
+            header=_StringTable.AdClickParallelTracking,
+            field_to_csv=lambda c: bulk_str(c.ad_click_parallel_tracking),
+            csv_to_field=lambda c, v: setattr(c, 'ad_click_parallel_tracking', parse_bool(v))
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.AllowImageAutoRetrieve,
+            field_to_csv=lambda c: bulk_str(c.allow_image_auto_retrieve),
+            csv_to_field=lambda c, v: setattr(c, 'allow_image_auto_retrieve', parse_bool(v))
+        ),        
+        _SimpleBulkMapping(
+            header=_StringTable.AutoApplyRecommendations,
+            field_to_csv=lambda c: dict_bulk_str(c.auto_apply_recommendations, ';'),
+            csv_to_field=lambda c, v: setattr(c, 'auto_apply_recommendations', parse_dict(v))
+        )
     ]
 
     def process_mappings_from_row_values(self, row_values):

bingads/v13/bulk/entities/bulk_ad_group.py

@@ -189,6 +189,16 @@ def quality_score_data(self):
             field_to_csv=lambda c: ad_group_bid_bulk_str(c.ad_group.CpcBid),
             csv_to_field=lambda c, v: setattr(c.ad_group, 'CpcBid', parse_ad_group_bid(v))
         ),
+        _SimpleBulkMapping(
+            header=_StringTable.CpvBid,
+            field_to_csv=lambda c: ad_group_bid_bulk_str(c.ad_group.CpvBid),
+            csv_to_field=lambda c, v: setattr(c.ad_group, 'CpvBid', parse_ad_group_bid(v))
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.CpmBid,
+            field_to_csv=lambda c: ad_group_bid_bulk_str(c.ad_group.CpmBid),
+            csv_to_field=lambda c, v: setattr(c.ad_group, 'CpmBid', parse_ad_group_bid(v))
+        ),
         _SimpleBulkMapping(
             header=_StringTable.Language,
             field_to_csv=lambda c: bulk_str(c.ad_group.Language),
@@ -243,6 +253,15 @@ def quality_score_data(self):
             field_to_csv=lambda c: c.ad_group.AdGroupType,
             csv_to_field=lambda c, v: setattr(c.ad_group, 'AdGroupType', v)
         ),
+        _SimpleBulkMapping(
+            header=_StringTable.MultiMediaAdBidAdjustment,
+            field_to_csv=lambda c: bulk_str(c.ad_group.MultimediaAdsBidAdjustment),
+            csv_to_field=lambda c, v: setattr(
+                c.ad_group,
+                'MultimediaAdsBidAdjustment',
+                int(v) if v else None
+            )
+        ),
     ]