YouTube Reporting API - Get Bulk Data Reports

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 น. ตามเวลาแปซิฟิกในวันที่สิ้นสุดของรายงาน

  • ไม่ได้จัดเรียงข้อมูลรายงาน