YouTube Reporting API - System-Managed Reports

YouTube จะสร้างชุดรายงานรายได้จากโฆษณาที่จัดการโดยระบบโดยอัตโนมัติสำหรับเจ้าของเนื้อหาที่มีสิทธิ์เข้าถึงรายงานที่เกี่ยวข้องใน Creator Studio รายงานเหล่านี้ออกแบบมาเพื่อให้คุณเข้าถึงข้อมูลด้วยโปรแกรมอัจฉริยะซึ่งยังอยู่ในรายงานที่ดาวน์โหลดได้ด้วยตนเองซึ่งเข้าถึงได้ในเมนูรายงานของ YouTube Creator Studio

หมายเหตุ: API ให้สิทธิ์เข้าถึงชุดรายงานที่แตกต่างจาก Creator Studio แม้ว่ารายงานจะมีข้อมูลที่คล้ายกันก็ตาม รายงาน API อาจมีช่องแตกต่างกัน และยังใช้ชื่อช่องต่างจากรายงานใน Creator Studio ด้วย

เนื่องจาก YouTube จะสร้างรายงานที่จัดการโดยระบบโดยอัตโนมัติ กระบวนการเรียกรายงานเหล่านี้จึงแตกต่างจากรายงานข้อมูลจำนวนมากของ YouTube Analytics ที่ให้บริการผ่าน API

การเรียกดูรายงาน

ขั้นตอนต่อไปนี้อธิบายวิธีเรียกรายงานที่จัดการโดยระบบผ่าน API

ขั้นตอนที่ 1: เรียกข้อมูลเข้าสู่ระบบการให้สิทธิ์

คำขอ API การรายงานของ YouTube ทั้งหมดต้องได้รับอนุญาต คู่มือการให้สิทธิ์จะอธิบายวิธีใช้โปรโตคอล OAuth 2.0 เพื่อเรียกโทเค็นการให้สิทธิ์

คำขอ API การรายงานของ YouTube ใช้ขอบเขตการให้สิทธิ์ต่อไปนี้

ขอบเขต
https://www.googleapis.com/auth/yt-analytics.readonly	ดูรายงาน Analytics ของ YouTube สำหรับเนื้อหา YouTube ของคุณ ขอบเขตนี้ให้สิทธิ์เข้าถึงเมตริกกิจกรรมของผู้ใช้ เช่น ยอดดูและการนับคะแนน
https://www.googleapis.com/auth/yt-analytics-monetary.readonly	ดูรายงานการเงินของ YouTube Analytics สำหรับเนื้อหา YouTube ของคุณ ขอบเขตนี้ให้สิทธิ์เข้าถึงเมตริกกิจกรรมของผู้ใช้ เมตริกรายได้โดยประมาณและเมตริกประสิทธิภาพโฆษณา

ขั้นตอนที่ 2: ดึงรหัสงานสำหรับรายงานที่ต้องการ

เรียกใช้เมธอด jobs.list เพื่อเรียกรายการงานที่จัดการโดยระบบ ตั้งค่าพารามิเตอร์ includeSystemManaged เป็น true

พร็อพเพอร์ตี้ reportTypeId ในทรัพยากร Job ที่แสดงผลแต่ละรายการจะระบุประเภทของรายงานที่จัดการโดยระบบซึ่งเชื่อมโยงกับงานนั้น แอปพลิเคชันของคุณต้องใช้ค่าพร็อพเพอร์ตี้ id จากทรัพยากรเดียวกันในขั้นตอนต่อไปนี้

เอกสารรายงานจะแสดงรายงานที่ใช้ได้ รหัสประเภทรายงาน และช่องที่มี คุณยังใช้เมธอด reportTypes.list เพื่อเรียกข้อมูลรายการประเภทรายงานที่รองรับได้ด้วย

ขั้นตอนที่ 3: ดึง URL สำหรับดาวน์โหลดรายงาน

เรียกใช้เมธอด jobs.reports.list เพื่อดึงรายการรายงานที่สร้างขึ้นสําหรับงาน ในคำขอ ให้ตั้งค่าพารามิเตอร์ jobId เป็นรหัสงานของรายงานที่ต้องการดึงข้อมูล

คุณสามารถกรองรายการรายงานโดยใช้พารามิเตอร์ต่อไปนี้อันใดอันหนึ่งหรือทั้งหมดก็ได้

• ใช้พารามิเตอร์ 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-3 วิธี

  • เมื่อเรียกเมธอด reports.list ให้ใช้พารามิเตอร์ createdAfter เพื่อดึงเฉพาะรายงานที่สร้างหลังจากวันที่ที่กำหนดเท่านั้น (ละเว้นพารามิเตอร์ createdAfter ในครั้งแรกที่เรียกดูรายงาน)

    ทุกครั้งที่คุณเรียกดูและประมวลผลรายงานสำเร็จ ให้จัดเก็บการประทับเวลาที่สอดคล้องกับวันที่และเวลาเมื่อมีการสร้างรายงานใหม่ที่สุด จากนั้นอัปเดตค่าพารามิเตอร์ createdAfter ในการเรียกเมธอด reports.list แบบต่อเนื่องกันแต่ละครั้งเพื่อให้แน่ใจว่าคุณจะดึงเฉพาะรายงานใหม่ ซึ่งรวมถึงรายงานใหม่ที่มีข้อมูลทดแทนทุกครั้งที่คุณเรียกใช้ API

    เพื่อเป็นการป้องกัน ก่อนเรียกรายงาน ให้ตรวจสอบว่า ID ของรายงานไม่ได้แสดงอยู่ในฐานข้อมูลของคุณอยู่แล้ว

  • จัดเก็บรหัสของรายงานแต่ละฉบับที่คุณได้ดาวน์โหลดและประมวลผลแล้ว คุณยังจัดเก็บข้อมูลเพิ่มเติม เช่น วันที่และเวลาที่สร้างรายงานแต่ละฉบับหรือ startTime และ endTime ของรายงาน ซึ่งเมื่อรวมกันแล้วจะระบุระยะเวลาที่รายงานมีข้อมูล สําหรับรายงานที่ดึงข้อมูลจํานวนมากสําหรับ YouTube Analytics งานแต่ละงานมีแนวโน้มที่จะมีรายงานจํานวนมาก เนื่องจากรายงานแต่ละฉบับมีข้อมูลระยะเวลา 24 ชั่วโมง งานที่จัดการโดยระบบซึ่งครอบคลุมระยะเวลาที่นานกว่าจะมีรายงานน้อยลง

    ใช้รหัสรายงานเพื่อระบุรายงานที่คุณยังต้องดาวน์โหลดและนำเข้า อย่างไรก็ตาม หากรายงานใหม่ 2 รายการมีค่าพร็อพเพอร์ตี้ startTime และ endTime เหมือนกัน ให้นำเข้าเฉพาะรายงานที่มีค่า createTime ที่ใหม่กว่าเท่านั้น

ลักษณะเฉพาะของรายงาน

รายงาน API คือไฟล์ .csv (ค่าที่คั่นด้วยคอมมา) เวอร์ชันที่มีลักษณะเฉพาะต่อไปนี้

• แต่ละรายงานจะมีข้อมูลสำหรับช่วงเวลาที่ไม่ซ้ำ ซึ่งมีตั้งแต่ 00:00 น. ตามเวลาแปซิฟิกในวันที่เริ่มต้นของรายงาน จนถึง 23:59 น. ตามเวลาแปซิฟิกในวันที่สิ้นสุดของรายงาน

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