ร้องขอและดาวน์โหลดรายงาน
การรายงานเป็นกระบวนการแบบอะซิงโครนัส ต่อไปนี้คือโฟลว์ทั่วไปสําหรับการร้องขอรายงาน
- สร้างคําขอด้วยพารามิเตอร์รายงาน
- ส่งคําขอไปยังบริการการรายงาน
- บริการจะจัดคิวการร้องขอจนกว่าจะสามารถประมวลผลได้
- สํารวจบริการเป็นระยะ ๆ เพื่อรับสถานะของงานรายงาน
- เมื่อสถานะเป็น สําเร็จ ให้ใช้ URL ที่บริการให้ไว้เพื่อดาวน์โหลดรายงาน
ถ้าคุณกําลังใช้ภาษา .NET, Java หรือ Python คุณควรใช้ไลบรารีไคลเอ็นต์ Bing Ads API .NET, Java และ Python SDKs นามธรรมรายละเอียดระดับต่ําที่อธิบายไว้ด้านล่าง ตัวอย่างเช่น แทนที่จะเรียก SubmitGenerateReportRequest และ PollGenerateReportRequest เพื่อดาวน์โหลดรายงาน คุณสามารถใช้วิธีหนึ่งกับ Reporting Service Manager ได้
สําหรับตัวอย่างโค้ดที่สาธิตวิธีการดาวน์โหลดรายงาน ดูตัวอย่างรหัสคําขอรายงาน
ร้องขอรายงาน
กําหนดรายงานที่คุณต้องการร้องขอ สําหรับรายการของรายงานที่คุณสามารถร้องขอได้ ดูชนิดรายงาน
สร้างอินสแตนซ์ของวัตถุคําขอรายงาน องค์ประกอบบางอย่างของคําขอรายงานจําเป็นต้องมี และบางองค์ประกอบเป็นตัวเลือก ตั้งค่าองค์ประกอบตามความเหมาะสมสําหรับแอปพลิเคชันของคุณ องค์ประกอบของคําขอรายงานจะกําหนดขอบเขตของข้อมูลที่จะรวมไว้ในรายงาน คอลัมน์ของข้อมูลที่จะรวมไว้ในรายงาน และจะสร้างรายงานเฉพาะเมื่อข้อมูลทั้งหมดพร้อมใช้งานหรือไม่
หมายเหตุ
คุณต้องสร้างอินสแตนซ์ของหนึ่งในวัตถุที่สืบทอดมาจากวัตถุข้อมูล ReportRequest ถ้าคุณพยายามส่งผ่านวัตถุ ReportRequest ไปยังการดําเนินการ SubmitGenerateReport การเรียกจะล้มเหลว
สร้างอินสแตนซ์ของวัตถุ SubmitGenerateReportRequest และตั้งค่าองค์ประกอบ ReportRequest เป็นคําขอรายงานที่คุณเลือกในขั้นตอนก่อนหน้า
เรียกใช้การดําเนินการ SubmitGenerateReport เพื่อส่งคําขอ การดําเนินการเป็นการดําเนินการแบบอะซิงโครนัสที่ส่งกลับก่อนที่จะสร้างรายงาน การดําเนินการจะส่งกลับ ReportRequestId ที่คุณใช้ในขั้นตอนต่อไปนี้เพื่อกําหนดว่ารายงานจะเสร็จสมบูรณ์เมื่อใด ตัวระบุคําขอรายงานจะใช้ได้เป็นเวลาสองวัน หากคุณไม่ได้ดาวน์โหลดรายงานภายในสองวัน คุณต้องขอรายงานอีกครั้ง
สร้างอินสแตนซ์ของวัตถุ PollGenerateReportRequest และตั้งค่าตัวระบุคําขอรายงานเป็นตัวระบุที่ส่งกลับในขั้นตอนก่อนหน้า
หมายเหตุ
คุณต้องใช้ข้อมูลประจําตัวผู้ใช้เดียวกันสําหรับการดําเนินการ SubmitGenerateReport และ PollGenerateReport
เรียกใช้การดําเนินการ PollGenerateReport ในการวนรอบในขณะที่สถานะเป็นรอดําเนินการ การดําเนินการจะตั้งค่าสถานะเป็น สําเร็จ เมื่อการร้องขอเสร็จสมบูรณ์ สถานะอื่นนอกเหนือจาก รอดําเนินการ หรือ สําเร็จ แสดงว่ารายงานล้มเหลว
ระยะเวลาที่คําขอรายงานจะเสร็จสมบูรณ์ขึ้นอยู่กับตัวแปรจํานวนหนึ่ง เช่น ชนิดของรายงานที่คุณร้องขอ ค่าการรวม ขอบเขต และช่วงเวลาที่คุณระบุ จํานวนแถวที่คาดไว้ และจํานวนการร้องขอที่อยู่ในคิว เนื่องจากตัวแปรเหล่านี้ จึงเป็นเรื่องยากที่จะกําหนดช่วงเวลาการโพลล์ที่เหมาะสมสําหรับทุกกรณี เนื่องจากรายงานส่วนใหญ่ควรเสร็จสมบูรณ์ภายในไม่กี่นาที การโพลล์ในช่วงเวลาสองถึง 15 นาทีควรเหมาะสมสําหรับกรณีส่วนใหญ่ ถ้าระยะเวลาการโพลล์โดยรวมเกิน 60 นาที ให้ลองบันทึกตัวระบุรายงาน ออกจากการวนรอบ และลองอีกครั้งในภายหลัง
หากคําขอเสร็จสมบูรณ์ ให้ใช้ URL ในองค์ประกอบ ReportDownloadUrl เพื่อดาวน์โหลดไฟล์ที่มีรายงาน หลังจากรับ URL การดาวน์โหลดแล้ว คุณมีเวลาห้านาทีในการดาวน์โหลดรายงาน หากคุณไม่ดาวน์โหลดรายงานภายในห้านาทีเพื่อรับ URL คุณต้องสํารวจสําหรับ URL ใหม่เพื่อใช้ดาวน์โหลดรายงาน
ไฟล์รายงานถูกบีบอัด ดังนั้น คุณต้องคลายการบีบอัดเพื่ออ่านรายงาน
สร้างช่วงวันที่แบบกําหนดเอง
ขั้นตอนต่อไปนี้แสดงวิธีการระบุช่วงวันที่แบบกําหนดเองสําหรับคําขอรายงาน ซึ่งเป็นตัวเลือกสําหรับเวิร์กโฟลว์การร้องขอรายงานที่อธิบายไว้ข้างต้น ถ้าคุณระบุช่วงวันที่แบบกําหนดเอง คุณต้องไม่ตั้งค่าองค์ประกอบ ReportTime.PredefinedTime นอกจากนี้ โปรดทราบว่าองค์ประกอบ การรวม ของออบเจ็กต์คําขอรายงานจะกําหนดวิธีการรวมข้อมูลสําหรับช่วงเวลาที่ระบุ
สร้างอินสแตนซ์ของวัตถุ ReportTime กําหนดวัตถุ ReportTime ให้กับองค์ประกอบเวลาของวัตถุข้อมูล ReportRequest
สร้างวัตถุ วันที่ ที่ระบุวันที่เริ่มต้นของช่วงวันที่แบบกําหนดเอง กําหนดวัตถุวันที่ให้กับองค์ประกอบ ReportTime.CustomDateRangeStart
สร้างวัตถุ วันที่ อื่นที่ระบุวันที่สิ้นสุดของช่วงวันที่แบบกําหนดเอง กําหนดวัตถุวันที่ให้กับองค์ประกอบ ReportTime.CustomDateRangeEnd
ส่วนย่อยของโค้ดต่อไปนี้แสดงวิธีการเริ่มต้นวัตถุคําขอรายงานเพื่อร้องขอช่วงวันที่แบบกําหนดเอง
// Create an instance of the ReportTime class to hold the report date
// information.
request.Time = new ReportTime();
// Set the start date for the report to one month before today.
DateTime startDate = DateTime.Today.AddMonths(-1);
request.Time.CustomDateRangeStart = new Date();
request.Time.CustomDateRangeStart.Day = startDate.Day;
request.Time.CustomDateRangeStart.Month = startDate.Month;
request.Time.CustomDateRangeStart.Year = startDate.Year;
// Set the end date to today.
DateTime endDate = DateTime.Today;
request.Time.CustomDateRangeEnd = new Date();
request.Time.CustomDateRangeEnd.Day = endDate.Day;
request.Time.CustomDateRangeEnd.Month = endDate.Month;
request.Time.CustomDateRangeEnd.Year = endDate.Year;
report.setTime(new ReportTime());
Calendar calendar = Calendar.getInstance();
report.getTime().setCustomDateRangeStart(new Date());
report.getTime().getCustomDateRangeStart().setMonth(1);
report.getTime().getCustomDateRangeStart().setDay(1);
report.getTime().getCustomDateRangeStart().setYear(calendar.get(Calendar.YEAR)-1);
report.getTime().setCustomDateRangeEnd(new Date());
report.getTime().getCustomDateRangeEnd().setMonth(12);
report.getTime().getCustomDateRangeEnd().setDay(31);
report.getTime().getCustomDateRangeEnd().setYear(calendar.get(Calendar.YEAR)-1);
$report->Time = new ReportTime();
$report->Time->PredefinedTime = null;
date_default_timezone_set('UTC');
$LastYear = date("Y") - 1;
$report->Time->CustomDateRangeStart = new Date();
$report->Time->CustomDateRangeStart->Month = 1;
$report->Time->CustomDateRangeStart->Day = 1;
$report->Time->CustomDateRangeStart->Year = $LastYear;
$report->Time->CustomDateRangeEnd = new Date();
$report->Time->CustomDateRangeEnd->Month = 12;
$report->Time->CustomDateRangeEnd->Day = 31;
$report->Time->CustomDateRangeEnd->Year = $LastYear;
report_time=reporting_service.factory.create('ReportTime')
custom_date_range_start=reporting_service.factory.create('Date')
custom_date_range_start.Day=1
custom_date_range_start.Month=1
custom_date_range_start.Year=int(strftime("%Y", gmtime()))-1
report_time.CustomDateRangeStart=custom_date_range_start
custom_date_range_end=reporting_service.factory.create('Date')
custom_date_range_end.Day=31
custom_date_range_end.Month=12
custom_date_range_end.Year=int(strftime("%Y", gmtime()))-1
report_time.CustomDateRangeEnd=custom_date_range_end
report_time.PredefinedTime=None
report_request.Time=report_time