bingads.v13.bulk package

Subpackages

Submodules

bingads.v13.bulk.bulk_operation module

class bingads.v13.bulk.bulk_operation.BulkDownloadOperation(request_id, authorization_data, poll_interval_in_milliseconds=5000, environment='production', tracking_id=None, **suds_options)[source]

Bases: bingads.v13.bulk.bulk_operation.BulkOperation

Represents a bulk download operation requested by a user.

You can use this class to poll for the download status, and then download the file when available.

Example:

The BulkServiceManager.submit_download() method returns an instance of this class. If for any reason you do not want to wait for the file to be prepared for download, for example if your application quits unexpectedly or you have other tasks to process, you can use an instance of BulkDownloadOperation to download the file when it is available.

get_status()[source]

Track the detailed download status.

Returns

The status of bulk download operation.

Return type

BulkOperationStatus

track(progress=None, timeout_in_milliseconds=None)[source]

Runs until the bulk service has finished processing the download or upload request.

Parameters

progress (BulkOperationProgressInfo -> None) – (optional) Tracking the percent complete progress information for the bulk operation.

Returns

The final BulkOperationStatus.

Return type

BulkOperationStatus

class bingads.v13.bulk.bulk_operation.BulkOperation(request_id, authorization_data, poll_interval_in_milliseconds=5000, environment='production', tracking_id=None, **suds_options)[source]

Bases: object

The base class that can be derived to represent a bulk operation requested by a user.

You can use either the BulkDownloadOperation or BulkUploadOperation derived class to poll for the operation status, and then download the results file when available.

download_result_file(result_file_directory, result_file_name, decompress, overwrite, timeout_in_milliseconds=None)[source]

Download file with specified URL and download parameters.

Parameters

  • result_file_directory (str) – The download result local directory name.

  • result_file_name (str | None) – The download result local file name.

  • decompress (bool) – Determines whether to decompress the ZIP file. If set to true, the file will be decompressed after download. The default value is false, in which case the downloaded file is not decompressed.

  • overwrite (bool) – Indicates whether the result file should overwrite the existing file if any.

  • timeout_in_milliseconds (int) – (optional) timeout for download result file in milliseconds

Returns

The download file path.

Return type

str

property final_status

Gets the final status of the bulk operation or null if the operation is still running.

Return type

BulkOperationStatus

get_status()[source]
property poll_interval_in_milliseconds

The time interval in milliseconds between two status polling attempts.

Return type

int

property request_id

The request identifier corresponding to the bulk upload or download, depending on the derived type.

Return type

str

property service_client

The internal bulk service client.

Return type

ServiceClient

track(percent_complete=None)[source]
class bingads.v13.bulk.bulk_operation.BulkUploadOperation(request_id, authorization_data, poll_interval_in_milliseconds=5000, environment='production', tracking_id=None, **suds_options)[source]

Bases: bingads.v13.bulk.bulk_operation.BulkOperation

Represents a bulk upload operation requested by a user.

You can use this class to poll for the upload status, and then download the upload results file when available.

Example:

The BulkServiceManager.submit_upload() method returns an instance of this class. If for any reason you do not want to wait for the file to finish uploading, for example if your application quits unexpectedly or you have other tasks to process, you can use an instance of BulkUploadOperation to download the upload results file when it is available.

get_status()[source]

Track the detailed upload status.

Returns

The status of bulk upload operation.

Return type

BulkOperationStatus

track(progress=None, timeout_in_milliseconds=None)[source]

Runs until the bulk service has finished processing the download or upload request.

Parameters

progress (BulkOperationProgressInfo -> None) – (optional) Tracking the percent complete progress information for the bulk operation.

Returns

The final BulkOperationStatus.

Return type

BulkOperationStatus

class bingads.v13.bulk.bulk_operation.TlsHttpAdapter(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)[source]

Bases: requests.adapters.HTTPAdapter

” Transport adapter that chooses the TLS protocols based on python versions.

init_poolmanager(connections, maxsize, block=False)[source]

Initializes a urllib3 PoolManager.

This method should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parameters

  • connections – The number of urllib3 connection pools to cache.

  • maxsize – The maximum number of connections to save in the pool.

  • block – Block when no free connections are available.

  • pool_kwargs – Extra keyword arguments used to initialize the Pool Manager.

bingads.v13.bulk.bulk_operation_progress_info module

class bingads.v13.bulk.bulk_operation_progress_info.BulkOperationProgressInfo(percent_complete=0)[source]

Bases: object

Contains percent complete progress information for the bulk operation.

property percent_complete

Percent complete progress information for the bulk operation.

Return type

int

bingads.v13.bulk.bulk_operation_status module

class bingads.v13.bulk.bulk_operation_status.BulkOperationStatus(status=None, percent_complete=None, result_file_url=None, errors=None)[source]

Bases: object

Contains tracking details about the results and status of the corresponding BulkDownloadOperation or BulkUploadOperation.

property errors

The list of errors associated with the operation.

Return type

list[OperationError]

property percent_complete

Percent complete progress information for the bulk operation.

Return type

int

property result_file_url

The download or upload result file Url.

Return type

str

property status

The download or upload status.

Return type

str

bingads.v13.bulk.bulk_service_manager module

class bingads.v13.bulk.bulk_service_manager.BulkServiceManager(authorization_data, poll_interval_in_milliseconds=5000, environment='production', working_directory=None, **suds_options)[source]

Bases: object

BOMLEN = 3

Provides high level methods for uploading and downloading entities using the Bulk API functionality.

Also provides methods for submitting upload or download operations.

Example:

download_file() will submit the download request to the bulk service, poll until the status is completed (or returns an error), and downloads the file locally. If instead you want to manage the low level details you would first call submit_download(), wait for the results file to be prepared using either BulkDownloadOperation.get_status() or BulkDownloadOperation.track(), and then download the file with the BulkOperation.download_result_file() method.

SYNC_THRESHOLD = 1000
bulkupload_entitie_records(entity_upload_parameters, tmp_file, progress=None)[source]

Uploads the specified Bulk entities in sync way by UploadEntityRecords.

bulkupload_entities(entity_upload_parameters, tmp_file, progress=None)[source]

Uploads the specified Bulk entities in async way.

Parameters

  • entity_upload_parameters (EntityUploadParameters) – Determines various upload parameters, for example what entities to upload.

  • tmp_file (string) – The temp file path that contains the content to upload

  • progress (BulkOperationProgressInfo -> None) – (optional) Tracking the percent complete progress information for the bulk operation.

Returns

Bulk entity generator.

Return type

generator[BulkEntity]

download_entities(download_parameters, progress=None)[source]

Downloads the specified Bulk entities.

Parameters

  • download_parameters (DownloadParameters) – Determines various download parameters, for example where the file should be downloaded.

  • progress (BulkOperationProgressInfo -> None) – (optional) Tracking the percent complete progress information for the bulk operation.

Returns

Bulk entity generator.

Return type

generator[BulkEntity]

download_file(download_parameters, progress=None)[source]

Downloads the specified Bulk entities to a local file.

Parameters

  • download_parameters (DownloadParameters) – Determines various download parameters, for example where the file should be downloaded.

  • progress (BulkOperationProgressInfo -> None) – (optional) Tracking the percent complete progress information for the bulk operation.

Returns

The downloaded local bulk file path.

Return type

str

download_upload_result(operation, file_upload_parameters, progress=None)[source]
need_to_fall_back_to_async(response)[source]
need_to_try_upload_entity_records_sync_first(entity_upload_parameters)[source]
property poll_interval_in_milliseconds

The time interval in milliseconds between two status polling attempts.

Return type

int

read_bulkupsert_response(response)[source]
read_result_from_bulk_file(result_bulk_file)[source]
retry_with_BulkUpload(bulkupsert_response)[source]
property service_client

The internal bulk service client.

Return type

ServiceClient

submit_download(submit_download_parameters)[source]

Submits a download request to the Bing Ads bulk service with the specified parameters.

Parameters

submit_download_parameters (SubmitDownloadParameters) – Determines various download parameters, for example what entities to download.

Returns

The submitted download operation

Return type

BulkDownloadOperation

submit_upload(submit_upload_parameters)[source]

Submits a request for a URL where a bulk upload file may be posted.

Parameters

submit_upload_parameters (SubmitUploadParameters) –

Returns

The submitted upload operation.

Return type

BulkUploadOperation

property suds_options

suds option parameters

Returns

dict

upload_entities(entity_upload_parameters, progress=None)[source]

Uploads the specified Bulk entities.

Parameters

  • entity_upload_parameters (EntityUploadParameters) – Determines various upload parameters, for example what entities to upload.

  • progress (BulkOperationProgressInfo -> None) – (optional) Tracking the percent complete progress information for the bulk operation.

Returns

Bulk entity generator.

Return type

generator[BulkEntity]

upload_file(file_upload_parameters, progress=None)[source]

Uploads the specified Bulk file.

Parameters

  • file_upload_parameters (FileUploadParameters) – Determines various upload parameters.

  • progress (BulkOperationProgressInfo -> None) – (optional) Tracking the percent complete progress information for the bulk operation.

Returns

The download local bulk file path.

Return type

str

property working_directory

Directory for storing temporary files needed for some operations (for example upload_entities() creates a temporary upload file).

Return type

str

bingads.v13.bulk.download_parameters module

class bingads.v13.bulk.download_parameters.DownloadParameters(result_file_directory=None, result_file_name=None, overwrite_result_file=False, data_scope=None, download_entities=None, file_type='Csv', campaign_ids=None, last_sync_time_in_utc=None, timeout_in_milliseconds=None)[source]

Bases: object

Describes the related parameters when downloading file from server.

such as the type of entities and data scope that you want to download.

property campaign_ids

The campaigns to download.

You can specify a maximum of 1,000 campaigns. The campaigns that you specify must belong to the same account.

Return type

list[int]

property data_scope

The scope or types of data to download.

For possible values, see DataScope Value Set at https://go.microsoft.com/fwlink/?linkid=846127.

Return type

list[str]

property decompress_result_file

If need to decompress the result file after download.

This property is determined by the result_file_name, by default will do decompression. if the result_file_name has the extension of ‘.zip’ then do not do decompression.

Return type

bool

property download_entities

The type of entities to download.

For possible values, see BulkDownloadEntity Value Set at https://go.microsoft.com/fwlink/?linkid=846127.

Return type

list[str]

property file_type

The extension type of the downloaded file.

For possible values, see DownloadFileType Value Set at https://go.microsoft.com/fwlink/?linkid=846127.

Return type

str

property last_sync_time_in_utc

The last time that you requested a download.

The date and time is expressed in Coordinated Universal Time (UTC). Typically, you request a full download the first time you call the operation by setting this element to null. On all subsequent calls you set the last sync time to the time stamp of the previous download. The download file contains the time stamp of the download in the SyncTime column of the Account record. Use the time stamp to set LastSyncTimeInUTC the next time that you request a download. If you specify the last sync time, only those entities that have changed (been updated or deleted) since the specified date and time will be downloaded. However, if the campaign data has not been previously downloaded, the operation performs a full download.

Return type

datetime

property overwrite_result_file

Whether the local result file should be overwritten if it already exists.

Return type

bool

property result_file_directory

The directory where the file will be downloaded.

Return type

str

property result_file_name

The name of the download result file.

Return type

str

property timeout_in_milliseconds
class bingads.v13.bulk.download_parameters.SubmitDownloadParameters(data_scope=None, download_entities=None, file_type='Csv', campaign_ids=None, last_sync_time_in_utc=None)[source]

Bases: object

Describes the service request parameters such as the type of entities and data scope that you want to download.

property campaign_ids

The campaigns to download.

You can specify a maximum of 1,000 campaigns. The campaigns that you specify must belong to the same account.

Return type

list[int]

property data_scope

The scope or types of data to download.

For possible values, see DataScope Value Set at https://go.microsoft.com/fwlink/?linkid=846127.

Return type

list[str]

property download_entities

The type of entities to download.

For possible values, see BulkDownloadEntity Value Set at https://go.microsoft.com/fwlink/?linkid=846127.

Return type

list[str]

property file_type

The extension type of the downloaded file.

For possible values, see DownloadFileType Value Set at https://go.microsoft.com/fwlink/?linkid=846127.

Return type

str

property last_sync_time_in_utc

The last time that you requested a download.

The date and time is expressed in Coordinated Universal Time (UTC). Typically, you request a full download the first time you call the operation by setting this element to null. On all subsequent calls you set the last sync time to the time stamp of the previous download. The download file contains the time stamp of the download in the SyncTime column of the Account record. Use the time stamp to set LastSyncTimeInUTC the next time that you request a download. If you specify the last sync time, only those entities that have changed (been updated or deleted) since the specified date and time will be downloaded. However, if the campaign data has not been previously downloaded, the operation performs a full download.

Return type

datetime

bingads.v13.bulk.enums module

class bingads.v13.bulk.enums.ResultFileType(value)[source]

Bases: enum.Enum

Defines the possible types of result files.

full_download = 1

The result file represents the full sync of entities that were specified in the download request.

partial_download = 2

The result file represents the partial sync of entities that were specified in the download request.

upload = 3

The result file represents the entities specified in the upload request, or the corresponding errors, or both entities and errors.

bingads.v13.bulk.exceptions module

exception bingads.v13.bulk.exceptions.BulkDownloadException(message)[source]

Bases: bingads.exceptions.SdkException

exception bingads.v13.bulk.exceptions.BulkException(message, errors)[source]

Bases: bingads.exceptions.SdkException

property errors

The list of operation errors returned by the bulk service.

Return type

list[OperationError]

exception bingads.v13.bulk.exceptions.BulkUploadException(message)[source]

Bases: bingads.exceptions.SdkException

exception bingads.v13.bulk.exceptions.EntityReadException(message, row_values=None, inner_exception=None)[source]

Bases: bingads.exceptions.SdkException

property inner_exception
property row_values
exception bingads.v13.bulk.exceptions.EntityWriteException(message, inner_exception=None)[source]

Bases: bingads.exceptions.SdkException

property inner_exception
class bingads.v13.bulk.exceptions.OperationError(code=None, details=None, error_code=None, message=None)[source]

Bases: object

Defines an error object that contains the details that explain why the service operation failed.

property code

A numeric error code that identifies the error

Return type

int

property details

A message that provides additional details about the error. This string can be empty.

Return type

str

property error_code

A symbolic string constant that identifies the error. For example, UserIsNotAuthorized.

Return type

str

property message

A message that describes the error.

Return type

str

bingads.v13.bulk.file_reader module

class bingads.v13.bulk.file_reader.BulkFileReader(file_path, file_type='Csv', result_file_type=ResultFileType.full_download, encoding='utf-8-sig')[source]

Bases: bingads.v13.bulk.file_reader._BulkEntityReader

Provides a method to read bulk entities from a bulk file and make them accessible as an enumerable list.

For more information about the Bulk File Schema, see https://go.microsoft.com/fwlink/?linkid=846127.

property encoding

The encoding of bulk file.

Return type

str

property file_path

The path of the bulk file to read.

Return type

str

property file_type

The bulk file type.

Return type

str

property result_file_type

The result file type.

Return type

ResultFileType

class bingads.v13.bulk.file_reader.BulkRowsReader(csv_rows)[source]

Bases: bingads.v13.bulk.file_reader._BulkEntityReader

bingads.v13.bulk.file_writer module

class bingads.v13.bulk.file_writer.BulkFileWriter(file_path, file_type='Csv')[source]

Bases: object

Provides methods to write bulk entities to a file.

For more information about the Bulk File Schema, see https://go.microsoft.com/fwlink/?linkid=846127.

Parameters

  • file_path (str) – The file path of the bulk file to write.

  • file_type (str) – The bulk file type.

close()[source]
property file_path

The file path of the bulk file to write.

Return type

str

property file_type

The bulk file type.

Return type

str

write_entity(entity, exclude_readonly_data=False)[source]

Writes the specified BulkEntity to the file.

Bulk entities that are derived from _SingleRecordBulkEntity will be written to a single row in the file. Bulk entities that are derived from _MultiRecordBulkEntity will be written to multiple rows in the file.

Parameters

  • entity (BulkEntity) – The bulk entity to write to the file.

  • exclude_readonly_data (bool) – excludeReadonlyData indicates whether readonly data (such as errors, performance data etc.) should be excluded when writing to file

Return type

None

bingads.v13.bulk.upload_parameters module

class bingads.v13.bulk.upload_parameters.EntityUploadParameters(entities, result_file_directory=None, result_file_name=None, overwrite_result_file=False, response_mode='ErrorsAndResults', timeout_in_milliseconds=None)[source]

Bases: object

Describes the available parameters when submitting entities for upload, such as the entities that you want to upload.

property decompress_result_file
property entities

The list of bulk entities that you want to upload.

Return type

collections.Iterable[BulkEntity]

property overwrite_result_file

Whether the local result file should be overwritten if it already exists.

Return type

bool

property response_mode

Determines whether the bulk service should return upload errors with the corresponding entity data.

If not specified, this property is set by default to ErrorsAndResults.

Return type

str

property result_file_directory

The directory where the file will be downloaded.

Return type

str

property result_file_name

The name of the download result file.

Return type

str

property timeout_in_milliseconds
class bingads.v13.bulk.upload_parameters.FileUploadParameters(upload_file_path, result_file_directory=None, result_file_name=None, overwrite_result_file=False, compress_upload_file=True, response_mode='ErrorsAndResults', timeout_in_milliseconds=None, rename_upload_file_to_match_request_id=True)[source]

Bases: object

Describes the available parameters when submitting a file for upload, such as the path of the upload result file.

property compress_upload_file

Determines whether the upload file should be compressed before uploading. The default value is True.

Return type

bool

property decompress_result_file
property overwrite_result_file

Whether the local result file should be overwritten if it already exists.

Return type

bool

property response_mode

Determines whether the bulk service should return upload errors with the corresponding entity data.

If not specified, this property is set by default to ErrorsAndResults.

Return type

str

property result_file_directory

The directory where the file will be downloaded.

Return type

str

property result_file_name

The name of the download result file.

Return type

str

property timeout_in_milliseconds
property upload_file_path

The fully qualified local path of the upload file.

Return type

str

class bingads.v13.bulk.upload_parameters.SubmitUploadParameters(upload_file_path, compress_upload_file=True, response_mode='ErrorsAndResults', timeout_in_milliseconds=None, rename_upload_file_to_match_request_id=True)[source]

Bases: object

Describes the minimum available parameters when submitting a file for upload, such as the path of the upload file.

property compress_upload_file

Determines whether the upload file should be compressed before uploading. The default value is True.

Return type

bool

property rename_upload_file_to_match_request_id

rename the upload file to request id or not.

Return type

boolean

property response_mode

Determines whether the bulk service should return upload errors with the corresponding entity data.

If not specified, this property is set by default to ErrorsAndResults.

Return type

str

property timeout_in_milliseconds
property upload_file_path

The fully qualified local path of the upload file.

Return type

str

Module contents