|
|
Getting Started Guide: EWS Responses
To use the Enterprise Web Services (EWS), you make service and operation requests to the EWS web server and then process the responses that are returned. Responses in EWS are constructed in XML format using the SOAP protocol. This page provides information about the format of the EWS response.
Introduction
An EWS SOAP response that is returned by the EWS server contains an Envelope element with a Header element and a Body element:
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V5">
<soap:Header>
...
</soap:Header>
<soap:Body>
...
</soap:Body>
</soap:Envelope>
The header contains transaction information about the request, regardless of whether the request has succeeded or failed. If the request was successful, the body will contain either the return elements and data, or the empty string, for those operations that do not return data. If the request was not successful, the body will contain an error code and error message.
Response SOAP Header
The SOAP header in the response contains elements that provide information about the response, the command group and your quota:
- remainingQuota: The quota remaining for the command group.
- quotaUsedForThisRequest: The quota deducted for this request. If a system error occurs during the request, no quota is deducted.
- commandGroup: The command group to which the operation belongs.
- timeTakenMillis: How long the operation took to complete inside the service backend, excluding network latency.
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V5">
<soap:Header>
<remainingQuota>9999974</remainingQuota>
<quotaUsedForThisRequest>532</quotaUsedForThisRequest>
<commandGroup>Marketing</commandGroup>
<timeTakenMillis>2813</timeTakenMillis>
</soap:Header>
<soap:Body>
...
</soap:Body>
</soap:Envelope>
Tracking Quota
Your EWS license specifies your command groups and quota. See Command Groups and Quota. Each EWS request includes either an operation or list-based operation that counts against your quota.See Request SOAP Body. As noted, each EWS response includes four elements in the SOAP header; use the remainingQuota and commandGroup elements to track your quota consumption.
Response SOAP Body
The SOAP body in the response contains the response elements and data. For example, the response for the BasicReport getReportList operation might look like this:
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V5">
<soap:Header>
...
</soap:Header>
<soap:Body>
<getReportListResponse>
<out>
<ReportInfo>
<createDate>2006-07-18T19:11:41.943-07:00</createDate>
<reportID>243</reportID>
<reportName>MultiChannelCampaign Report</reportName>
<status>COMPLETE</status>
</ReportInfo>
<ReportInfo>
<createDate>2006-07-18T19:08:48.394-07:00</createDate>
<reportID>242</reportID>
<reportName>MultiChannelMarketingActivity
Report</reportName>
<status>COMPLETE</status>
</ReportInfo>
</out>
</getReportListResponse>
</soap:Body>
</soap:Envelope>
To capture errors for individual objects, some operations have responses that contain error elements as part of the response data. This is particularly useful for list-based operations that include multiple objects. For example, see the CampaignResponse data object. Given this, the response for the CampaignService addCampaigns operation might look like this:
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V5">
<soap:Header>
...
</soap:Header>
<soap:Body>
<addCampaignsResponse>
<out>
<CampaignResponse>
<campaign>
<ID>5354501</ID>
<accountID>9901673</accountID>
<advancedMatchON>true</advancedMatchON>
<campaignOptimizationON>false</campaignOptimizationON>
<contentMatchON>true</contentMatchON>
...
</campaign>
<errors xsi:nil="true" />
<operationSucceeded>true</operationSucceeded>
</CampaignResponse>
<CampaignResponse>
<campaign>
<ID xsi:nil="true" />
<accountID>9901673</accountID>
<advancedMatchON>true</advancedMatchON>
<campaignOptimizationON>false</campaignOptimizationON>
<contentMatchON>true</contentMatchON>
...
</campaign>
<errors>
<Error>
<code>E2012</code>
<message>Name exceeds maximum allowed length
of 50.</message>
</Error>
</errors>
<operationSucceeded>false</operationSucceeded>
</CampaignResponse>
</out>
</addCampaignsResponse>
</soap:Body>
</soap:Envelope>
Empty Response
If an operation does not return any data, the SOAP body will contain an empty response element. For example, the response for the BasicReportService deleteReport operation would look like this:
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V5">
<soap:Header>
...
</soap:Header>
<soap:Body>
<deleteReportResponse/>
</soap:Body>
</soap:Envelope>
List-Based Operations
List-based operations allow you to operate on multiple objects in the same response. When you set up a list-based operation, you list the objects in a specific order. EWS guarantees that the operation's response will maintain this order when the response objects are returned. See List-Based Operations for EWS Requests.
This is particularly important when you are working with add operations, such as addCampaigns or addAdGroups, which do not include the IDs as identifiers because the objects have not yet been created.
For example, suppose you use the addAds operation to create three new ads. And, suppose that one of these ads has an error in it. Because the operation's response maintains your ordering, you will be able to identify which ad has the error: if the second ad contains the error then the second response object will indicate that the operation failed, operationSucceeded = false.
Lists of Elements
Lists of elements in the response are enclosed by a single element. For example, getCampaigns, which returns a list of Campaign elements, has a response body like this:
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V5">
<soap:Header>
...
</soap:Header>
<soap:Body>
<getCampaignsResponse>
<out>
<Campaign>
...
</Campaign>
<Campaign>
...
</Campaign>
</out>
</getCampaignsResponse>
</soap:Body>
</soap:Envelope>
Warnings, Errors and Exceptions
If your SOAP request is successful, the EWS web server will return an HTTP 200 OK response code and the SOAP response as described above.
If a warning occurs during the processing of your SOAP request, the EWS web server will return a warning code and a message. See Warnings.
If an error or exception occurs during the processing of your SOAP request, the EWS web server will return an error code and message as shown here:
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:yns="http://marketing.ews.yahooapis.com/V5">
<soap:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Quota exceeded</faultstring>
<detail>
<yns:ApiFault>
<yns:code>E1015</yns:code>
<yns:message>Quota exceeded</yns:message>
</yns:ApiFault>
</detail>
</soap:Fault>
</soap:Body>
</soap:Envelope>
Complete Example
This example shows a complete SOAP response for adding campaigns.
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V5">
<soap:Header>
<remainingQuota>9999974</remainingQuota>
<commandGroup>Marketing</commandGroup>
<timeTakenMillis>2813</timeTakenMillis>
</soap:Header>
<soap:Body>
<addCampaignsResponse>
<out>
<CampaignResponse>
<campaign>
<ID>5354501</ID>
<accountID>9901673</accountID>
<advancedMatchON>true</advancedMatchON>
<campaignOptimizationON>false</campaignOptimizationON>
<contentMatchON>true</contentMatchON>
...
</campaign>
<errors xsi:nil="true" />
<operationSucceeded>true</operationSucceeded>
</CampaignResponse>
<CampaignResponse>
<campaign>
<ID>5355001</ID>
<accountID>9901673</accountID>
<advancedMatchON>true</advancedMatchON>
<campaignOptimizationON>false</campaignOptimizationON>
<contentMatchON>true</contentMatchON>
...
</campaign>
<errors xsi:nil="true" />
<operationSucceeded>true</operationSucceeded>
</CampaignResponse>
</out>
</addCampaignsResponse>
</soap:Body>
</soap:Envelope>