YouTube จะสร้างชุดรายงานรายได้จากโฆษณาที่ระบบจัดการโดยอัตโนมัติสำหรับเจ้าของเนื้อหาที่มีสิทธิ์เข้าถึงรายงานที่เกี่ยวข้องใน Creator Studio รายงานเหล่านี้ออกแบบมาเพื่อให้สิทธิ์เข้าถึงข้อมูลแบบเป็นโปรแกรม ซึ่งเป็นข้อมูลเดียวกันกับที่อยู่ในรายงานแบบดาวน์โหลดด้วยตนเองที่เข้าถึงได้ในเมนูรายงานของ YouTube Creator Studio
หมายเหตุ: API ให้สิทธิ์เข้าถึงรายงานชุดอื่นที่ไม่ใช่ Creator Studio แม้ว่ารายงานจะมีข้อมูลที่คล้ายกันก็ตาม รายงาน API อาจมีช่องที่แตกต่างกันและใช้ชื่อช่องที่แตกต่างจากรายงาน Creator Studio ด้วย
เนื่องจาก YouTube สร้างรายงานที่ระบบจัดการโดยอัตโนมัติ กระบวนการดึงข้อมูลรายงานเหล่านี้จึงแตกต่างจากรายงานข้อมูลจำนวนมากของข้อมูลวิเคราะห์ YouTube ที่พร้อมใช้งานผ่าน API
การเรียกข้อมูลรายงาน
ขั้นตอนต่อไปนี้อธิบายวิธีดึงข้อมูลรายงานที่ระบบจัดการผ่าน API
ขั้นตอนที่ 1: ดึงข้อมูลเข้าสู่ระบบการให้สิทธิ์
คำขอทั้งหมดของ YouTube Reporting API ต้องได้รับอนุญาต คู่มือการให้สิทธิ์จะอธิบายวิธีใช้โปรโตคอล OAuth 2.0 เพื่อดึงโทเค็นการให้สิทธิ์
คำขอ YouTube Reporting API ใช้ขอบเขตการให้สิทธิ์ต่อไปนี้
ขอบเขต | |
---|---|
https://www.googleapis.com/auth/yt-analytics.readonly | ดูรายงานข้อมูลวิเคราะห์ YouTube สำหรับเนื้อหา YouTube ของคุณ ขอบเขตนี้ให้สิทธิ์เข้าถึงเมตริกกิจกรรมของผู้ใช้ เช่น จำนวนการดูและจำนวนการให้คะแนน |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | ดูรายงานด้านการเงินของข้อมูลวิเคราะห์ YouTube สำหรับเนื้อหา YouTube ของคุณ ขอบเขตนี้ให้สิทธิ์เข้าถึงเมตริกกิจกรรมของผู้ใช้ รวมถึงเมตริกรายได้และประสิทธิภาพโฆษณาโดยประมาณ |
ขั้นตอนที่ 2: ดึงข้อมูลรหัสงานสำหรับรายงานที่ต้องการ
เรียกใช้เมธอด jobs.list
เพื่อดึงข้อมูลรายการงานที่ระบบจัดการ ตั้งค่าพารามิเตอร์ includeSystemManaged
เป็น true
พร็อพเพอร์ตี้ reportTypeId
ในทรัพยากร Job
ที่ส่งคืนแต่ละรายการจะระบุประเภทของรายงานที่ระบบจัดการซึ่งเชื่อมโยงกับงานนั้น แอปพลิเคชันของคุณต้องมีค่าพร็อพเพอร์ตี้ id
จากแหล่งข้อมูลเดียวกันในขั้นตอนต่อไปนี้
เอกสารรายงานจะแสดงรายงานที่มีอยู่ รหัสประเภทรายงาน และฟิลด์ที่อยู่ในรายงาน นอกจากนี้ คุณยังใช้เมธอด reportTypes.list
เพื่อดึงข้อมูลรายการประเภทรายงานที่รองรับได้ด้วย
ขั้นตอนที่ 3: ดึง URL การดาวน์โหลดของรายงาน
เรียกใช้เมธอด jobs.reports.list
เพื่อดึงข้อมูลรายการรายงานที่สร้างขึ้นสำหรับงาน ในคำขอ ให้ตั้งค่าพารามิเตอร์ jobId
เป็นรหัสงานของรายงานที่ต้องการดึงข้อมูล
คุณกรองรายการรายงานได้โดยใช้พารามิเตอร์ต่อไปนี้อย่างน้อย 1 รายการ
-
ใช้พารามิเตอร์
createdAfter
เพื่อระบุว่า API ควรแสดงเฉพาะรายงานที่สร้างขึ้นหลังจากเวลาที่ระบุ คุณใช้พารามิเตอร์นี้เพื่อให้แน่ใจว่า API จะแสดงเฉพาะรายงานที่คุณยังไม่ได้ประมวลผล -
ใช้พารามิเตอร์
startTimeBefore
เพื่อระบุว่าการตอบกลับของ API ควรมีเฉพาะรายงานที่ข้อมูลที่เก่าที่สุดในรายงานอยู่ก่อนวันที่ที่ระบุ ในขณะที่พารามิเตอร์createdAfter
เกี่ยวข้องกับเวลาที่สร้างรายงาน วันที่นี้เกี่ยวข้องกับข้อมูลในรายงาน -
ใช้พารามิเตอร์
startTimeAtOrAfter
เพื่อระบุว่าการตอบกลับของ API ควรมีเฉพาะรายงานที่มีข้อมูลที่เก่าที่สุดในรายงานเป็นวันที่ที่ระบุหรือหลังจากนั้น ค่าพารามิเตอร์นี้จะสอดคล้องกับข้อมูลในรายงาน ไม่ใช่เวลาที่สร้างรายงาน เช่นเดียวกับพารามิเตอร์startTimeBefore
การตอบกลับของ API มีรายการทรัพยากร Report
สำหรับงานนั้น แหล่งข้อมูลแต่ละรายการจะอ้างอิงถึงรายงานที่มีข้อมูลสำหรับระยะเวลาที่ไม่ซ้ำกัน
- พร็อพเพอร์ตี้
startTime
และendTime
ของทรัพยากรจะระบุระยะเวลาที่ข้อมูลของรายงานครอบคลุม - พร็อพเพอร์ตี้
downloadUrl
ของทรัพยากรจะระบุ URL ที่ดึงข้อมูลรายงานได้ - พร็อพเพอร์ตี้
createTime
ของทรัพยากรจะระบุวันที่และเวลาที่สร้างรายงาน แอปพลิเคชันควรจัดเก็บค่านี้และใช้เพื่อพิจารณาว่ารายงานที่ดาวน์โหลดก่อนหน้านี้มีการเปลี่ยนแปลงหรือไม่
ขั้นตอนที่ 4: ดาวน์โหลดรายงาน
ส่งคำขอ HTTP GET ไปยัง downloadUrl
ที่ได้รับในขั้นตอนที่ 4 เพื่อดึงข้อมูลรายงาน
รายงานการประมวลผล
แนวทางปฏิบัติแนะนำ
แอปพลิเคชันที่ใช้ YouTube Reporting API ควรปฏิบัติตามแนวทางต่อไปนี้เสมอ
-
ใช้แถวส่วนหัวของรายงานเพื่อกำหนดลำดับของคอลัมน์ในรายงาน เช่น อย่าคิดว่ายอดดูจะเป็นเมตริกแรกที่แสดงในรายงานเพียงเพราะเป็นเมตริกแรกที่ระบุไว้ในคำอธิบายรายงาน แต่ให้ใช้แถวส่วนหัวของรายงานเพื่อระบุว่าคอลัมน์ใดมีข้อมูลนั้น
-
บันทึกรายงานที่คุณดาวน์โหลดไว้เพื่อหลีกเลี่ยงการประมวลผลรายงานเดียวกันซ้ำๆ รายการต่อไปนี้แสดงวิธีดำเนินการ 2 วิธี
-
เมื่อเรียกใช้เมธอด
reports.list
ให้ใช้พารามิเตอร์ createdAfter เพื่อดึงข้อมูลเฉพาะรายงานที่สร้างขึ้นหลังจากวันที่ที่ระบุ (ละเว้นพารามิเตอร์createdAfter
ในครั้งแรกที่คุณดึงข้อมูลรายงาน)ทุกครั้งที่คุณดึงและประมวลผลรายงานสำเร็จ ให้จัดเก็บการประทับเวลาที่สอดคล้องกับวันที่และเวลาที่สร้างรายงานล่าสุด จากนั้นอัปเดตค่าพารามิเตอร์
createdAfter
ในการเรียกใช้เมธอดreports.list
แต่ละครั้งเพื่อให้แน่ใจว่าคุณจะเรียกข้อมูลเฉพาะรายงานใหม่ รวมถึงรายงานใหม่ที่มีข้อมูลที่เติมแบ็กเท่านั้นทุกครั้งที่เรียกใช้ APIเพื่อเป็นการป้องกัน ก่อนที่จะดึงข้อมูลรายงาน ให้ตรวจสอบด้วยว่ารหัสของรายงานไม่ได้อยู่ในฐานข้อมูลของคุณแล้ว
-
จัดเก็บรหัสของรายงานแต่ละรายการที่คุณดาวน์โหลดและประมวลผล คุณยังจัดเก็บข้อมูลเพิ่มเติมได้ เช่น วันที่และเวลาที่สร้างรายงานแต่ละฉบับ หรือ
startTime
และendTime
ของรายงาน ซึ่งระบุระยะเวลาที่รายงานมีข้อมูลร่วมกัน สำหรับรายงานที่ดึงข้อมูลจำนวนมากสำหรับข้อมูลวิเคราะห์ YouTube แต่ละงานมักจะมีรายงานหลายรายการ เนื่องจากแต่ละรายงานมีข้อมูลสำหรับระยะเวลา 24 ชั่วโมง งานที่ระบบจัดการซึ่งครอบคลุมระยะเวลาที่นานขึ้นจะมีรายงานน้อยลงใช้รหัสรายงานเพื่อระบุรายงานที่คุณยังต้องดาวน์โหลดและนำเข้า อย่างไรก็ตาม หากรายงานใหม่ 2 รายการมีค่าพร็อพเพอร์ตี้
startTime
และendTime
เหมือนกัน ให้นําเข้ารายงานที่มีค่าcreateTime
ใหม่กว่าเท่านั้น
-
ลักษณะของรายงาน
รายงาน API เป็นไฟล์ .csv
(ค่าที่คั่นด้วยคอมมา) ที่มีการกำหนดเวอร์ชันซึ่งมีลักษณะดังนี้
-
รายงานแต่ละฉบับจะมีข้อมูลสำหรับระยะเวลาที่ไม่ซ้ำกันซึ่งเริ่มตั้งแต่เวลา 00:00 น. ตามเวลาแปซิฟิกในวันที่เริ่มต้นของรายงานจนถึงเวลา 23:59 น. ตามเวลาแปซิฟิกในวันที่สิ้นสุดของรายงาน
-
ไม่ได้จัดเรียงข้อมูลรายงาน