Export (0) Print
Expand All

GetDownloadStatus Service Operation

Gets the status of a bulk download request.

Request | Response

Example Code | Error Codes | Remarks

Service: BulkService.svc v8 | Namespace: https://adcenter.microsoft.com/v8

GetDownloadStatusRequest Message

Request Elements

The GetDownloadStatusRequest object defines the elements of the request’s body. The elements must be in the same order as shown in the SOAP example.

Element

Description

Data Type

DownloadRequestId

The identifier of the download request.

The DownloadCampaignsByAccountIds and DownloadCampaignsByCampaignIds operations return this identifier.

string

Request Headers

For information about the values you set the DeveloperToken, Password, and UserName elements to, see Getting Started With the Bing Ads API.

Element

Description

Data Type

ApplicationToken

The application-access token. This header element is not used and should be null.

string

AuthenticationToken

The authentication token. This header element is not used and should be null.

string

CustomerAccountId

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

string

CustomerId

The identifier of the customer that owns the account. This header element is not used and should be null.

string

DeveloperToken

The caller's developer-access token.

string

Password

The user's sign-in password.

string

UserName

The user's sign-in user name. You cannot set this element to a Microsoft account (formerly known as Windows Live ID).

string

Request SOAP

The following example shows the complete request envelope.

<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://adcenter.microsoft.com/v8">
    <Action mustUnderstand="1">GetDownloadStatus</Action>
    <ApplicationToken i:nil="false"></ApplicationToken>
    <CustomerAccountId i:nil="false"></CustomerAccountId>
    <CustomerId i:nil="false"></CustomerId>
    <DeveloperToken i:nil="false"></DeveloperToken>
    <Password i:nil="false"></Password>
    <UserName i:nil="false"></UserName>
  </s:Header>
  <s:Body>
    <GetDownloadStatusRequest xmlns="https://adcenter.microsoft.com/v8">
      <DownloadRequestId i:nil="false"></DownloadRequestId>
    </GetDownloadStatusRequest>
  </s:Body>
</s:Envelope>

GetDownloadStatusResponse Message

Response Elements

Element

Description

Data Type

DownloadUrl

The URL that contains the download data. This element contains the URL when the Status element is Success.

You have five minutes from the time that GetDownloadStatus returns success to start downloading the file. If you do not start the download within this time period, you will need to call GetDownloadStatus again to get a new URL.

You have five days to download the file. If you do not download the file within five days, you must call the download operation again to download the file.

The download file is compressed (in zip format), so you must unzip the file to access the data.

The content of the file is XML. For details, see Download Schema.

string

Status

The status of the download. For possible values, see the DownloadStatus value set.

DownloadStatus

Response Headers

Element

Description

Data Type

TrackingId

The identifier of the log entry that contains the details of the API call.

string

Response SOAP

The following example shows the complete response envelope.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://adcenter.microsoft.com/v8">
    <TrackingId p4:nil="false" xmlns:p4="http://www.w3.org/2001/XMLSchema-instance"></TrackingId>
  </s:Header>
  <s:Body>
    <GetDownloadStatusResponse xmlns="https://adcenter.microsoft.com/v8">
      <DownloadUrl p4:nil="false" xmlns:p4="http://www.w3.org/2001/XMLSchema-instance"></DownloadUrl>
      <Status></Status>
    </GetDownloadStatusResponse>
  </s:Body>
</s:Envelope>

The time that it takes the download to complete depends on a number of variables, such as the number of campaigns that you requested and the number of requests that are already in the queue. Because of these variables, the frequency by which you should call this operation varies. However, most small requests should complete within minutes, so consider polling at one to two minute intervals for small requests. For medium requests, consider polling at one to two minute intervals after waiting five to 15 minutes. For large requests, consider polling at one to two minute intervals after waiting 30 minutes. If the overall polling period exceeds 60 minutes, consider exiting the loop and trying again later.

Example Code

For example code that shows how to call this operation to get the status of a download request, see the GetDownloadUrl method in the following examples: C# | Java | PHP.

Error Codes

If the service operation fails, it throws a FaultException exception, which contains one or more of the Bing Ads API error data objects. For information about the fault detail objects, see Bulk Error Data Objects and Handling Service Errors and Exceptions.

The following are the possible error codes and messages that the fault objects can include. The list does not include common, operation-related error codes shared by the services (for example, UserIsNotAuthorized or InvalidCredentials). For a list common error codes, Common Error Codes.

Error code

Symbolic

Description

3205

CampaignServiceInvalidDownloadRequestId

The download request ID is not valid.

Community Additions

Show:
© 2014 Microsoft