bingads package

Subpackages

Submodules

bingads.authorization module

class bingads.authorization.Authentication[source]

Bases: object

The base class for all authentication classes.

See also:

enrich_headers(headers)[source]

Sets the required header elements for the corresponding Bing Ads service or bulk file upload operation.

The header elements that the method sets will differ depending on the type of authentication. For example if you use one of the OAuth classes, the AuthenticationToken header will be set by this method, whereas the UserName and Password headers will remain empty.

Parameters

headers (dict) – Bing Ads service or bulk file upload operation headers.

Return type

None

class bingads.authorization.AuthorizationData(account_id=None, customer_id=None, developer_token=None, authentication=None)[source]

Bases: object

Represents a user who intends to access the corresponding customer and account.

An instance of this class is required to authenticate with Bing Ads if you are using either ServiceClient or BulkServiceManager.

property account_id

The identifier of the account that owns the entities in the request.

Used as the CustomerAccountId header and the AccountId body elements in calls to the Bing Ads web services.

Return type

int

property authentication

An object representing the authentication method that should be used in calls to the Bing Ads web services.

See also:

Return type

Authentication

property customer_id

The identifier of the customer that owns the account.

Used as the CustomerId header element in calls to the Bing Ads web services.

Return type

int

property developer_token

The Bing Ads developer access token.

Used as the DeveloperToken header element in calls to the Bing Ads web services.

Return type

str

class bingads.authorization.OAuthAuthorization(client_id, oauth_tokens=None, env='production', oauth_scope='msads.manage', tenant='common')[source]

Bases: bingads.authorization.Authentication

The abstract base class for all OAuth authentication classes.

You can use this class to dynamically instantiate a derived OAuth authentication class at run time. This class cannot be instantiated, and instead you should use either OAuthDesktopMobileAuthCodeGrant, OAuthDesktopMobileImplicitGrant, OAuthWebAuthCodeGrant, which extend this class.

See also:

property client_id

The client identifier corresponding to your registered application.

For more information about using a client identifier for authentication, see the Client Password Authentication section of the OAuth 2.0 spec at https://tools.ietf.org/html/rfc6749#section-4.1

Return type

str

enrich_headers(headers)[source]

Sets the AuthenticationToken headers elements for Bing Ads service or bulk file upload operation.

get_authorization_endpoint()[source]

Gets the Microsoft Account authorization endpoint where the user should be navigated to give his or her consent.

Returns

The Microsoft Account authorization endpoint.

Return type

str

property oauth_tokens

Contains information about OAuth access tokens received from the Microsoft Account authorization service.

Return type

OAuthTokens

property redirection_uri

The URI to which the user of the app will be redirected after receiving user consent.

Return type

str

property state

An opaque value used by the client to maintain state between the request and callback :rtype: str

property tenant
Return type

str

class bingads.authorization.OAuthDesktopMobileAuthCodeGrant(client_id, oauth_tokens=None, env='production', oauth_scope='msads.manage', tenant='common')[source]

Bases: bingads.authorization.OAuthWithAuthorizationCode

Represents an OAuth authorization object implementing the authorization code grant flow for use in a desktop or mobile application.

You can use an instance of this class as the AuthorizationData.Authentication property of an AuthorizationData object to authenticate with Bing Ads services. In this case the AuthenticationToken request header will be set to the corresponding OAuthTokens.AccessToken value.

This class implements the authorization code grant flow for Managing User Authentication with OAuth documented at http://go.microsoft.com/fwlink/?LinkID=511609. This is a standard OAuth 2.0 flow and is defined in detail in the Authorization Code Grant section of the OAuth 2.0 spec at https://tools.ietf.org/html/rfc6749#section-4.1. For more information about registering a Bing Ads application, see http://go.microsoft.com/fwlink/?LinkID=511607.

class bingads.authorization.OAuthDesktopMobileImplicitGrant(client_id, oauth_tokens=None, env='production', oauth_scope='msads.manage', tenant='common')[source]

Bases: bingads.authorization.OAuthAuthorization

Represents an OAuth authorization object implementing the implicit grant flow for use in a desktop or mobile application.

You can use an instance of this class as the AuthorizationData.Authentication property of an AuthorizationData object to authenticate with Bing Ads services. In this case the AuthenticationToken request header will be set to the corresponding OAuthTokens.AccessToken value.

This class implements the implicit grant flow for Managing User Authentication with OAuth documented at http://go.microsoft.com/fwlink/?LinkID=511608. This is a standard OAuth 2.0 flow and is defined in detail in the Authorization Code Grant section of the OAuth 2.0 spec at https://tools.ietf.org/html/rfc6749#section-4.1. For more information about registering a Bing Ads application, see http://go.microsoft.com/fwlink/?LinkID=511607.

extract_access_token_from_uri(redirection_uri)[source]

Extracts the access token from the specified redirect URI.

Parameters

redirection_uri (str) – The redirect URI that contains an access token.

Returns

The OAuthTokens object which contains both the access_token and access_token_expires_in_seconds properties.

Return type

OAuthTokens

get_authorization_endpoint()[source]

Gets the Microsoft Account authorization endpoint where the user should be navigated to give his or her consent.

Returns

The Microsoft Account authorization endpoint.

Return type

str

property redirection_uri

The URI to which the user of the app will be redirected after receiving user consent.

Return type

str

class bingads.authorization.OAuthTokens(access_token=None, access_token_expires_in_seconds=None, refresh_token=None, response_json=None)[source]

Bases: object

Contains information about OAuth access tokens received from the Microsoft Account authorization service.

You can get OAuthTokens using the RequestAccessAndRefreshTokens method of RequestAccessAndRefreshTokens method of either the OAuthDesktopMobileAuthCodeGrant or OAuthWebAuthCodeGrant classes.

property access_token

OAuth access token that will be used for authorization in the Bing Ads services.

Return type

str

property access_token_expired

Whether the access token has been expired.

Return type

bool

property access_token_expires_in_seconds

Expiration time for the corresponding access token in seconds.

Return type

int

property access_token_received_datetime

The datetime when access token was received

Return type

datetime

property refresh_token

OAuth refresh token that can be user to refresh an access token.

Return type

str

property response_json

OAuth whole attribute that got along with access token.

Return type

dictionary

class bingads.authorization.OAuthWebAuthCodeGrant(client_id, client_secret, redirection_uri, token_refreshed_callback=None, oauth_tokens=None, env='production', oauth_scope='msads.manage', tenant='common')[source]

Bases: bingads.authorization.OAuthWithAuthorizationCode

Represents an OAuth authorization object implementing the authorization code grant flow for use in a web application.

You can use an instance of this class as the AuthorizationData.Authentication property of an AuthorizationData object to authenticate with Bing Ads services. In this case the AuthenticationToken request header will be set to the corresponding OAuthTokens.AccessToken value.

This class implements the authorization code grant flow for Managing User Authentication with OAuth documented at http://go.microsoft.com/fwlink/?LinkID=511609. This is a standard OAuth 2.0 flow and is defined in detail in the Authorization Code Grant section of the OAuth 2.0 spec at https://tools.ietf.org/html/rfc6749#section-4.1. For more information about registering a Bing Ads application, see http://go.microsoft.com/fwlink/?LinkID=511607.

class bingads.authorization.OAuthWithAuthorizationCode(client_id, client_secret, redirection_uri, token_refreshed_callback=None, oauth_tokens=None, env='production', oauth_scope='msads.manage', tenant='common')[source]

Bases: bingads.authorization.OAuthAuthorization

Represents a proxy to the Microsoft account authorization service.

Implement an extension of this class in compliance with the authorization code grant flow for Managing User Authentication with OAuth documented at http://go.microsoft.com/fwlink/?LinkID=511609. This is a standard OAuth 2.0 flow and is defined in detail in the Authorization Code Grant section of the OAuth 2.0 spec at https://tools.ietf.org/html/rfc6749#section-4.1. For more information about registering a Bing Ads application, see http://go.microsoft.com/fwlink/?LinkID=511607.

property client_secret

The client secret corresponding to your registered application, or None if your app is a desktop or mobile app.

Return type

str

get_authorization_endpoint()[source]

Gets the Microsoft Account authorization endpoint where the user should be navigated to give his or her consent.

Returns

The Microsoft Account authorization endpoint.

Return type

str

property redirection_uri

The URI to which your client browser will be redirected after receiving user consent.

Return type

str

request_oauth_tokens_by_refresh_token(refresh_token)[source]

Retrieves OAuth access and refresh tokens from the Microsoft Account authorization service.

Using the specified refresh token. For more information, see the Refreshing an Access Token section in the OAuth 2.0 spec at https://tools.ietf.org/html/rfc6749#section-6.

Parameters

refresh_token (str) – The refresh token used to request new access and refresh tokens.

Returns

OAuth tokens

Return type

OAuthTokens

request_oauth_tokens_by_response_uri(response_uri, **kwargs)[source]

Retrieves OAuth access and refresh tokens from the Microsoft Account authorization service.

Using the specified authorization response redirection uri. For more information, see the Authorization Response section in the OAuth 2.0 spec at https://tools.ietf.org/html/rfc6749#section-4.1.

Parameters

response_uri (str) – The response redirection uri.

Returns

OAuth tokens

Return type

OAuthTokens

property token_refreshed_callback

The callback function registered, will be invoked after oauth tokens has been refreshed.

Return type

OAuthTokens->None

class bingads.authorization.PasswordAuthentication(user_name, password)[source]

Bases: bingads.authorization.Authentication

Represents a legacy Bing Ads authentication method using user name and password.

You can use an instance of this class as the authentication property of a AuthorizationData object to authenticate with Bing Ads services. Existing users with legacy Bing Ads credentials may continue to specify the UserName and Password header elements. In future versions of the API, Bing Ads will transition exclusively to Microsoft Account authentication. New customers are required to sign up for Bing Ads with a Microsoft Account, and to manage those accounts you must use OAuth. For example instead of using this PasswordAuthentication class, you would authenticate with an instance of either OAuthDesktopMobileAuthCodeGrant, OAuthDesktopMobileImplicitGrant, or OAuthWebAuthCodeGrant.

enrich_headers(headers)[source]

Sets the user name and password as headers elements for Bing Ads service or bulk file upload operation.

property password

The Bing Ads user’s sign-in password.

Return type

str

property user_name

The Bing Ads user’s sign-in user name. You may not set this element to a Microsoft account.

Return type

str

bingads.exceptions module

exception bingads.exceptions.FileDownloadException(description)[source]

Bases: bingads.exceptions.SdkException

This exception is thrown if timeout occurs

exception bingads.exceptions.FileUploadException(description)[source]

Bases: bingads.exceptions.SdkException

This exception is thrown if timeout occurs

exception bingads.exceptions.OAuthTokenRequestException(error_code, description)[source]

Bases: bingads.exceptions.SdkException

This exception is thrown if an error was returned from the Microsoft Account authorization server.

property error_code

The error code of the OAuth error.

Return type

str

property error_description

The description of the OAuth error.

Return type

str

exception bingads.exceptions.SdkException(message)[source]

Bases: Exception

Base Exception for exceptions in SDK.

property message

Detailed exception message.

Return type

str

exception bingads.exceptions.TimeoutException(description)[source]

Bases: bingads.exceptions.SdkException

This exception is thrown if timeout occurs

bingads.headerplugin module

class bingads.headerplugin.HeaderPlugin[source]

Bases: suds.plugin.MessagePlugin

get_response_header()[source]
parsed(context)[source]

Suds has SAX parsed the received reply.

Provides the plugin with the opportunity to inspect/modify the SAX parsed DOM tree for the reply before it is unmarshalled.

@param context: The reply context.

The I{reply} is DOM tree.

@type context: L{MessageContext}

bingads.manifest module

bingads.service_client module

class bingads.service_client.BingAdsBuilder(resolver)[source]

Bases: suds.builder.Builder

skip_value(type)[source]

whether or not to skip setting the value

class bingads.service_client.ServiceClient(service, version, authorization_data=None, environment='production', **suds_options)[source]

Bases: object

Provides an interface for calling the methods of the specified Bing Ads service.

property authorization_data

Represents a user who intends to access the corresponding customer and account.

Return type

AuthorizationData

property factory

The internal suds soap client factory.

Return type

Factory

get_response_header()[source]
property refresh_oauth_tokens_automatically

A value indicating whether OAuth access and refresh tokens should be refreshed automatically upon access token expiration.

Return type

bool

property service_url

The wsdl url of service based on the specific service and environment.

Return type

str

set_options(**kwargs)[source]

Set suds options, these options will be passed to suds.

Parameters

kwargs – suds options.

Return type

None

property soap_client

The internal suds soap client.

Return type

Client

bingads.service_info module

bingads.util module

class bingads.util.DictCache[source]

Bases: dict, suds.cache.Cache

purge(key, /)

Delete self[key].

put(id_, obj)[source]

Put an object into the cache.

@param id: The object id. @type id: str @param object: The object to add. @type object: any

bingads.util.errorcode_of_exception(ex)[source]
bingads.util.operation_errorcode_of_exception(ex)[source]

Module contents