|
|
Getting Started Guide: BulkService Overview
BulkService provides operations to download accounts or campaigns along with the complete hierarchy and to create or modify campaigns, adgroups and keywords by uploading a bulk file based on the YSM template. BulkService also provides an operation to download a bulk template with headers.
About Bulk
BulkService provides operations to upload/download accounts and campaigns.
Download:
The general process of downloading consists of requesting an account/campaign download,
polling on the status of downloaded job-id and finally, downloading the file using the
downloaded url. The download file contains the downloaded objects and its complete hierarchy. The download is in the form of a
file based on the YSM bulk template.
BulkService also has an operation that downloads the template with only the header information.
Upload:
The general process of uploading consists of requesting an upload url,
uploading the file based on the YSM bulk template to the url and polling on the
status of job-id.
A successful upload would show status as Successful. An in progress upload would show status as InProgress
Any other status of BulkUploadStatus, would mean an unsuccessful upload.
The user also gets a feedback file URL after the job is completed. Depending on the feedback file type parameter, the feedback file would contain either all data that changed
or only errors (if any).
Bulk Download Flow
The following steps are executed when a bulk download request is made. It is also depicted pictorially in the sequence diagram after the steps are listed.
- Initiate a bulk download request.
- A bulk download ID is returned.
- Use the bulk download ID returned in the step above to query the bulk download status.
- If the bulk download status is "Successful", the URL to download the file will be returned.
- If the bulk download status is "InProgress", keep polling till the URL to download the file is returned.
- If the bulk download status is "Failed", the URL to download the file will not be returned.
- If the bulk download status is "TimedOut", the bulk download is taking a long time to complete. Please retry the download. Please get in touch with your Technical Account Manager and report this incident.
Please note the following with respect to the flow provided above:
- The bulk download ID returned is valid for one day only.
- A bulk download request would time-out if it could not be processed within an hour. After one hour, a new bulk download ID must be obtained.
- For security reasons, the URLs returned to download files are saved for 15 minutes. After 15 minutes, you must use the getBulkDownloadStatus API to get a new URL.
- If you are trying to download accounts and campaigns, the entire hierarchy will be downloaded and will only contain non-deleted objects.
Bulk Upload Flow
The following steps are executed while uploading a bulk file.
- Request for an upload token URL.
- A job-id and upload token URL is returned.
- Upload the bulk file based on the YSM template to the above obtained token URL.
- Poll on the job-id to find the status of uploaded file.
- If the status is "CompletedWithErrors/FailedWithInternalError", the file upload has failed.
- If the status is "Successful", the file has been successfully uploaded.
- If the status is "FileInQueueForProcessing", the file is submitted but processing has not yet started.
- If the bulk download status is "FileNotSubmitted", the file has not been submitted. Please try uploading the file to the same URL.
- If the bulk download status is "FormatNotSupported", the upload is not supported for the specified file type.
- If the status is "InProgress", the upload operation is in progress. Continue polling.
- If the bulk download status is "Successful", the file upload has been successful.
Please note the following with respect to the flow provided above:
- For security reasons, the URLs returned to upload files are saved for 15 minutes. After 15 minutes, you must use the getBulkUploadTokenUrl API to get a new URL.
- A feedback file URL is returned at the completion (successful/failed) of file upload, and can be downloaded from the URL. For the description of feedback file, see Feedback File
File Types
Once the bulk download request is successful, it will return a URL to download the file. Based on the request you made, this file contains the account or campaign information,or it can simply be a template file with header information, if you made such a request.
You must specify the file format or type that you want when you make the request. You will have to choose from one of the file types supported by the BulkService. The file types supported are:
- EXCEL_XML: This is an XML format Excel (Excel XML) file type. This has Excel 2003 XML file format. These files are UTF 8 encoded.
- TSV: These are Tab Separated Values (TSV) file type. File extension is .CSV. These files are UTF16-LE encoded.
- GENERIC_XML: This is an XML format file type. For the schema file for this XML file type, see Bulk Upload Schema
File Encoding
For encoding examples, use any of the following resources.
Java
- Charset class from JDK : http://java.sun.com/javase/6/docs/api/java/nio/charset/Charset.html
- Conversion tutorial: http://java.sun.com/docs/books/tutorial/i18n/text/convertintro.html
- Character Encoding Conversion: http://java.sun.com/javase/technologies/core/basic/intl/faq.jsp#core-encoding
- Text Representation in Core Java : http://java.sun.com/javase/technologies/core/basic/intl/faq.jsp#core-textrep
Perl
Encode::Unicode - http://perldoc.perl.org/Encode/Unicode.html http://search.cpan.org/~rgarcia/perl-5.10.0/pod/perlunitut.pod
Python
http://www.reportlab.com/i18n/python_unicode_tutorial.html http://www.amk.ca/python/howto/unicode
PHP
.NET
http://msdn.microsoft.com/en-us/library/zs0350fy(VS.71).aspx http://www.yoda.arachsys.com/csharp/unicode.html
Download Hierarchy
If you are downloading accounts or campaings, the file returned will conatin data for the complete hierarchy. The hierarchy is shown in the diagram below. Note that only non-deleted objects will be included in the file returned.
Bulk Services
BulkService provides operations that allow you to request, retrieve or check the status of bulk downloads.
Download Accounts and Campaigns
To download the entire spend account, use the downloadAccount operation. This operation will download all the non-deleted items in the hierarchy under the spend account. The spend account downloaded will be for the account ID specified in the request header.
To download specific campaigns under the spend account, use the downloadCampaigns operation. This operation will download all the non-deleted items in the hierarchy under the campaigns. Only campaigns whose IDs are specified in the request, and those which belong to the spend account specified in the request header are downloaded.
Download Template
To download an empty bulk template, along with the headers, use the downloadBulkTemplate operation. The template is localized based on the locale of the user.
Check Download Status
To check the status of the bulk download request, use the getBulkDownloadStatus operation. The possible statuses are listed on the bulk download status page.
Check Download Status Info
To check the status of the bulk download request along with remaining time to download, use the getBulkDownloadStatusInfo operation. The possible statuses are listed on the bulk download status page.
Get Upload Token URL
To retrieve the upload token url, use the getBulkUploadTokenUrl operation. This operation will also return a job-id which is used to poll the status of a uploaded file.
Check Upload Status
To check the status of the bulk upload, use the getBulkUploadStatus operation. The possible status values are listed on the bulk upload status page.