locked
Report Request Example

    General discussion

  • The following C# code example demonstrates how to request and download a keyword performance report with the new optional columns and measures features. An example of the SOAP created by the Reporting.RequestBIReport method in this example is also given below.

     

    Example code:

     

    Code Snippet

    static public void GetKeywordPerformanceReport(
        string userName,
        string password,
        string userAccessKey,
        int accountId,
        string zipFileName)
    {
        int apiFlags = 0;
       
        // Create and initialize the KeywordPerformanceReportRequest object.
        KeywordPerformanceReportRequest reportRequest = new KeywordPerformanceReportRequest();
        reportRequest.AccountId = accountId;
        reportRequest.ReportLanguage = ReportLanguageType.English;
        reportRequest.Format = APIResultFileType.XML;
        reportRequest.ReportDateRange = ReportDateRangeType.Last6Months;
        reportRequest.ReportAggregation = ReportAggregationType.Day;
        reportRequest.AllNone = false;

       

       // Setup the optional columns.
        reportRequest.OptionalColumns = new KeywordPerformanceReportOptionalColumn[2];
        reportRequest.OptionalColumns[0] = KeywordPerformanceReportOptionalColumn.DestinationURL;
        reportRequest.OptionalColumns[1] = KeywordPerformanceReportOptionalColumn.KeywordOrderName;

       

       // Setup the optional measures.
        reportRequest.OptionalMeasures = new KeywordPerformanceReportOptionalMeasure[3];
        reportRequest.OptionalMeasures[0] = KeywordPerformanceReportOptionalMeasure.ConversionRate;
        reportRequest.OptionalMeasures[1] = KeywordPerformanceReportOptionalMeasure.Conversions;
        reportRequest.OptionalMeasures[2] = KeywordPerformanceReportOptionalMeasure.CostPerConversion;

       

       // Create and initialize the ApiUserAuthHeader object.
        ApiUserAuthHeader authHeader = new ApiUserAuthHeader();
        authHeader.UserName = userName;
        authHeader.Password = password;
        authHeader.UserAccessKey = userAccessKey;

       

       // Create and initialize the Reporting object to request the report with.
        Reporting reportAPI = new Reporting();
        reportAPI.ApiUserAuthHeaderValue = authHeader;

       

       // Request the report.
        string reportId = reportAPI.RequestBIReport(apiFlags, reportRequest);
       
        // Poll for the report until it is completed.
        APIReportStatusType requestResult = null;
        int waitMinutes = 3;
        int maxWaitMinutes = 120;
        DateTime startWaiting = DateTime.Now;
        int elapsedMinutes = DateTime.Now.Subtract(startWaiting).Minutes;
        do
        {
            // Get the current status of the report.
            requestResult = reportAPI.GetAPIReportStatus(apiFlags, reportId);

           

           if (APIStatusType.SUCCESS == requestResult.ReportStatus)
            {
                // The report is complete, so break out of the loop.
                break;
            }
            else if ((APIStatusType.REQUEST_PENDING == requestResult.ReportStatus) ||
                (APIStatusType.REQUEST_IN_PROGRESS == requestResult.ReportStatus))
            {
                // The report is not ready yet. Wait the specified number of minutes

               // before polling again.
                System.Threading.Thread.Sleep(waitMinutes * 1000);
            }
            else
            {
                // Everything else is a failure.
                throw new ApplicationException(requestResult.ReportStatus.ToString());
            }

            elapsedMinutes = DateTime.Now.Subtract(startWaiting).Minutes;
        } while (elapsedMinutes < maxWaitMinutes);

     

       // If the report was created, download it.
        if ((null != requestResult) && (APIStatusType.SUCCESS == requestResult.ReportStatus))
        {
            // Open a connection to the URL where the report is available.
            HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create(requestResult.ReportDownloadURL);
            HttpWebResponse response = (HttpWebResponse)webRequest.GetResponse();
            Stream httpStream = response.GetResponseStream();

     

           // Open the report file.
            FileStream fileStream = new FileStream(zipFileName, FileMode.Create);
            BinaryWriter binaryWriter = new BinaryWriter(fileStream);
            BinaryReader binaryReader = new BinaryReader(httpStream);

     

           // Read the report and save it to the file.
            while (true)
            {
                int bufferSize = 100000;

     

               // Read report data from API.
                byte[] buffer = binaryReader.ReadBytes(bufferSize);

     

               // Write report data to file.
                binaryWriter.Write(buffer);

     

               // If the end of the report is reached, break out of the loop.
                if (buffer.Length != bufferSize)
                {
                    break;
                }
            }

     

           // Clean up.
            binaryWriter.Close();
            binaryReader.Close();
            fileStream.Close();
            httpStream.Close();
        }
    }

     

    This is the SOAP request that is created by the Reporting.RequestBIReport method above.

     

    Code Snippet

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope xmlns:soap="
    http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <soap:Header>
            <ApiUserAuthHeader xmlns="
    http://adcenter.microsoft.com/syncapis">
                <UserName>*****</UserName>
                <Password>*****</Password>
                <UserAccessKey>*****</UserAccessKey>
            </ApiUserAuthHeader>
        </soap:Header>
        <soap:Body>
            <RequestBIReport xmlns="
    http://adcenter.microsoft.com/syncapis">
                <APIFlags>0</APIFlags>
                <request xsi:type="KeywordPerformanceReportRequest">
                    <StartDate xsi:nil="true" />
                    <EndDate xsi:nil="true" />
                    <ReportLanguage>English</ReportLanguage>
                    <Format>XML</Format>
                    <AllNone>false</AllNone>
                    <ReportDateRange>Last6Months</ReportDateRange>
                    <ReportAggregation>Day</ReportAggregation>
                    <AccountId>*****</AccountId>
                    <OptionalMeasures>
                        <KeywordPerformanceReportOptionalMeasure>ConversionRate</KeywordPerformanceReportOptionalMeasure>
                        <KeywordPerformanceReportOptionalMeasure>Conversions</KeywordPerformanceReportOptionalMeasure>
                        <KeywordPerformanceReportOptionalMeasure>CostPerConversion</KeywordPerformanceReportOptionalMeasure>
                    </OptionalMeasures>
                    <OptionalColumns>
                        <KeywordPerformanceReportOptionalColumn>DestinationURL</KeywordPerformanceReportOptionalColumn>
                        <KeywordPerformanceReportOptionalColumn>KeywordOrderName</KeywordPerformanceReportOptionalColumn>
                    </OptionalColumns>
                </request>
            </RequestBIReport>
        </soap:Body>
    </soap:Envelope>

     

    Wednesday, May 02, 2007 8:23 PM

All replies

  • There was an error in the code. I had to remove the following line otherwise an exception would be thrown at run time because the requestResult variable is null.

     

    Code Snippet
        requestResult.ReportStatus = APIStatusType.FAILED_APPLICATION_ERROR;

     

    Sorry for the error. I have corrected the example.

     

    Strohm Armstrong

    Programming Writer - Microsoft adCenter API

    Thursday, May 03, 2007 3:42 PM