YouTube Analytics API - Data Model

API ของ YouTube Analytics ช่วยให้คุณสร้างรายงานที่กําหนดเองซึ่งมีข้อมูล YouTube Analytics ได้ API รองรับรายงานสําหรับช่องและเจ้าของเนื้อหา ช่องรายงานจะมีลักษณะเป็นมิติข้อมูลหรือเมตริกดังนี้

• มิติข้อมูลเป็นเกณฑ์ทั่วไปที่ใช้รวบรวมข้อมูล เช่น วันที่ที่เกิดการดําเนินการ หรือประเทศที่ผู้ใช้อยู่

  ในรายงาน ข้อมูลแต่ละแถวจะมีชุดค่าผสมของค่ามิติข้อมูลที่ไม่ซ้ํากัน ด้วยเหตุนี้ มิติข้อมูลที่คุณเลือกสําหรับรายงานจะกําหนดวิธีที่ YouTube คํานวณค่าสําหรับเมตริกในรายงานนั้น

• เมตริก คือการวัดผลที่เกี่ยวข้องกับกิจกรรมของผู้ใช้ ประสิทธิภาพโฆษณา หรือรายได้โดยประมาณ เมตริกกิจกรรมของผู้ใช้ ได้แก่ จํานวนการดูและการให้คะแนนวิดีโอ (การกดชอบและไม่ชอบ)

Analytics API มีพารามิเตอร์การกรองและการจัดเรียง ดังนั้นแอปพลิเคชันการโทรจึงไม่จําเป็นต้องรองรับฟังก์ชันเหล่านั้นโดยค่าเริ่มต้น API ยังช่วยให้คุณดึงข้อมูลสําหรับกลุ่ม YouTube Analytics ได้ด้วย โดยกลุ่มคือคอลเล็กชันวิดีโอ เพลย์ลิสต์ ช่อง หรือเนื้อหาสูงสุด 500 รายการ

การเลือกพารามิเตอร์รายงาน

เมื่อคุณขอรายงาน การใช้เมธอด reports.query ของ API จะทําให้คําขอมีพารามิเตอร์ 5 รายการที่กําหนดวิธีคํานวณค่ารายงาน ดังนี้

• พารามิเตอร์ startDate และ endDate ระบุระยะเวลาที่รายงานจะมีข้อมูล อันที่จริง API จะตอบกลับเมื่อมีข้อมูลจนถึงวันสุดท้ายที่ระบุเมตริกทั้งหมดในการค้นหาในขณะที่ค้นหา

• พารามิเตอร์ metrics จะระบุการวัดที่จะรวมไว้ในรายงาน ในรายงานแชแนล เมตริกจะวัดกิจกรรมของผู้ใช้ และรวมค่าต่างๆ เช่น การดู และการกดชอบไว้ด้วย เมตริกบางรายการจะวัดประสิทธิภาพของโฆษณาหรือรายได้โดยประมาณด้วย

• พารามิเตอร์ dimensions อธิบายวิธีจัดกลุ่มเมตริก

• พารามิเตอร์ filters อธิบายวิธีกรองข้อมูลรายงาน เช่น แทนที่จะแสดงข้อมูลทั้งหมดของช่องหนึ่งๆ รายงานอาจถูกกรองออกเพื่อให้มีเฉพาะเมตริกสําหรับประเทศ วิดีโอ หรือกลุ่มวิดีโอที่กําหนดเท่านั้น

  หมายเหตุ: API ให้คุณระบุค่าหลายค่าสําหรับตัวกรองวิดีโอ เพลย์ลิสต์ และช่องได้ หากรวม คุณก็สามารถรวมตัวกรองนั้นไว้ในรายการมิติข้อมูลได้ เพื่อให้จัดกลุ่มเมตริกที่แสดงผลตามวิดีโอ เพลย์ลิสต์ หรือแชแนลได้อีกด้วย

ตัวอย่างตัวเลือกการรายงาน

ตัวอย่างเช่น สมมติว่าเจ้าของช่องต้องการเรียกดูรายงานประเภทอุปกรณ์วิดีโอเพื่อกําหนดยอดดูวิดีโอของช่องที่เกิดขึ้นบนอุปกรณ์เคลื่อนที่ คอนโซลเกม ทีวี และอื่นๆ

• เจ้าของช่องตั้งค่าพารามิเตอร์ startDate เป็น 2015-06-01 และพารามิเตอร์ endDate เป็น 2015-07-31 รายงานเหล่านี้จะมีข้อมูลระยะเวลา 2 เดือนตามค่าเหล่านี้

• รายงานประเภทอุปกรณ์รองรับเมตริกยอดดูและ estimatedMinutesWatched เพื่อให้เจ้าของช่องตั้งค่าพารามิเตอร์ metrics เป็น views,estimatedMinutesWatched

• สําหรับพารามิเตอร์ dimensions เจ้าของช่องมีตัวเลือกมากมาย พารามิเตอร์ 2 รายการแสดงไว้ในรายการต่อไปนี้ และรายการที่ 3 จะพูดถึงในคําอธิบายค่าพารามิเตอร์ filters ในภายหลังในส่วนนี้

  • การตั้งค่าพารามิเตอร์เป็น deviceType หมายความว่าระบบจะนับจํานวนยอดดูและเวลาในการรับชมตามประเภทอุปกรณ์ตลอดระยะเวลาที่รายงาน ดังนั้นด้วยค่านี้ ข้อมูลรายงานจะตอบคําถามต่างๆ เช่น

    • วิดีโอของช่องมีการรับชมบนอุปกรณ์เคลื่อนที่กี่ครั้งระหว่างวันที่ 1 มิถุนายน 2015 ถึง 31 กรกฎาคม 2015
    • วิดีโอของช่องดูระหว่างคอนโซลเกมระหว่างวันที่ 1 มิถุนายน 2015 ถึง 31 กรกฎาคม 2015 กี่ครั้ง

    รายงานจะประกอบด้วยจํานวนการดูและเวลาในการรับชมทั้งหมดสําหรับอุปกรณ์แต่ละประเภท

  • การตั้งค่าพารามิเตอร์เป็น day,deviceType หมายความว่าระบบจะคํานวณยอดดูและเวลาในการรับชมตามประเภทอุปกรณ์ในแต่ละวันในระหว่างระยะเวลาการรายงาน ดังนั้นด้วยค่านี้ ข้อมูลรายงานจะตอบคําถามต่างๆ เช่น

    • วิดีโอของช่องมียอดดูบนอุปกรณ์เคลื่อนที่กี่ครั้งในวันที่ 1 มิถุนายน 2015
    • วิดีโอของช่องมีการรับชมทางทีวีในวันที่ 14 กรกฎาคม 2015 กี่ครั้ง

• และสุดท้าย พารามิเตอร์ filters จะช่วยให้เจ้าของช่องสามารถจํากัดรายงานให้มีเฉพาะข้อมูลที่ตรงกับค่าตัวกรองบางรายการเท่านั้น รายงานนี้รองรับตัวเลือกการกรองที่จะอธิบายตัวเลือกเหล่านั้นทั้งหมดมากเกินไป ตัวอย่างเหล่านี้เป็นเพียงตัวอย่างของรายงานที่คุณสามารถสร้างได้

  • เจ้าของช่องสามารถกรองคําขอส่งคืนค่าสําหรับระบบปฏิบัติการ Android เท่านั้น (อุปกรณ์เคลื่อนที่มี Android เกิดขึ้นกี่ครั้งในระยะเวลาการรายงานนี้)

  • เจ้าของช่องสามารถกรองคําขอเพื่อแสดงเฉพาะค่าของประเทศนั้นๆ เท่านั้น (ในแต่ละวันที่มีการดูวิดีโอในแคนาดามีกี่ครั้ง)

  • เจ้าของช่องสามารถกรองคําขอเพื่อแสดงค่าเฉพาะสําหรับวิดีโอบางรายการ แต่ตัวกรองวิดีโอจะรองรับรายการค่าที่คั่นด้วยคอมมา ดังนั้นรายงานจึงอาจมีข้อมูลสําหรับวิดีโอหลายรายการ

    นอกจากนี้ หากตัวกรองวิดีโอระบุค่าหลายค่า ก็จะระบุวิดีโอเป็นมิติข้อมูลได้ด้วย ซึ่งหมายความว่าพารามิเตอร์ dimensions จะรองรับค่า deviceType,video และ day,deviceType,video ด้วย

    • หากเจ้าของช่องใส่วิดีโอในรายการมิติข้อมูล เมตริกจะระบุค่าแต่ละรายการสําหรับวิดีโอแต่ละรายการ (วิดีโอ XYZ มียอดดูบนคอนโซลเกมในวันที่ 1 มิถุนายน 2015 กี่ครั้ง)
    • หากเจ้าของช่องไม่มีวิดีโอในรายการมิติข้อมูล เมตริกจะระบุค่าทั้งหมดที่ครอบคลุมวิดีโอที่ระบุทั้งหมด (มีการดูวิดีโอ ABC, DEF และ XYZ บนคอนโซลเกมกี่ครั้งในวันที่ 1 มิถุนายน 2015)

กําลังเรียกรายงาน

หากต้องการเรียกข้อมูลรายงาน ให้ส่งคําขอ GET ที่ได้รับอนุญาตไปยังเมธอด reports.query ของ API โดยระบุพารามิเตอร์ที่กําหนดรายงานที่ต้องการเรียกข้อมูล

โปรดดูรายการรายงานที่ API รองรับในเอกสารรายงานช่องและรายงานเจ้าของเนื้อหา คําจํากัดความของรายงานแต่ละรายการจะระบุค่าที่รายงานอนุญาตสําหรับพารามิเตอร์ metrics, dimensions และ filters

แนวทางปฏิบัติแนะนำ

แอปพลิเคชันที่ใช้ YouTube Analytics API ควรทําตามแนวทางปฏิบัติต่อไปนี้เสมอ

• ใช้แถวส่วนหัวของการตอบกลับเพื่อกําหนดลําดับคอลัมน์ของรายงาน ตัวอย่างเช่น อย่าคิดไว้ว่ายอดดูจะเป็นเมตริกแรกที่ส่งคืนมาเพียงเพราะเป็นเมตริกแรกที่แสดงในคําอธิบายรายงาน แต่ให้ใช้แถวส่วนหัวของการตอบกลับเพื่อดูว่าคอลัมน์ใดมีข้อมูลดังกล่าวแทน
• ใช้ Data API ของ YouTube เพื่อดึงข้อมูลเมตาเพิ่มเติมสําหรับทรัพยากรที่ระบุไว้ในการตอบกลับของ YouTube Analytics API ตามที่ระบุไว้ในนโยบายนักพัฒนาซอฟต์แวร์บริการ API ของ YouTube (ส่วนที่ 3.E.4.b ถึง III.E.4.d) ไคลเอ็นต์ API จะต้องลบหรือรีเฟรชข้อมูลเมตาของทรัพยากรที่จัดเก็บไว้จาก API ดังกล่าวหลังจากผ่านไป 30 วัน

รวบรวมเมตริกและรายการที่ถูกลบ

การตอบกลับ API ของ YouTube Analytics ไม่มีรายละเอียดเมตริกสําหรับรายการที่ถูกลบ ตัวอย่างเช่น หากเจ้าของช่องลบวิดีโอ วิดีโอนั้นจะไม่ปรากฏในการตอบกลับ API ที่แสดงผลเมตริกเป็นรายวิดีโออีกต่อไป แต่รายงานที่รวมเมตริกสําหรับชุดทรัพยากรจะยังคงมีเมตริกที่เชื่อมโยงกับรายการที่ถูกลบอยู่

เช่น สมมติว่าเจ้าของช่องดึงข้อมูลรายงาน 2 ฉบับ รายงานแรกจะแสดงยอดดูรายวันทั้งหมดของวิดีโอทั้งหมดของช่องในระยะเวลาหนึ่ง รายงานที่ 2 แสดงยอดดูรายวันทั้งหมดแบบวิดีโอต่อรายการในช่วงเวลาเดียวกัน

ในกรณีนี้ ตัวเลขในรายงานแรกจะแสดงยอดดูของวิดีโอที่ถูกลบในภายหลังเนื่องจากรายงานแรกมีข้อมูลรวมรายวัน อย่างไรก็ตาม รายงานที่ 2 จะไม่รวมการดูที่เชื่อมโยงกับรายการที่ถูกลบเนื่องจากรายงานที่ 2 จะแสดงยอดดูแบบวิดีโอต่อวิดีโอ ดังนั้น หากช่องลบวิดีโอระหว่างระยะเวลาที่รายงานครอบคลุม จํานวนการดูรายวันทั้งหมดที่รายงานในรายงานแรกอาจสูงกว่าผลรวมของจํานวนการดูรายวันของแต่ละวิดีโอในรายงานที่ 2

การลบข้อมูลระบุตัวบุคคล

ระบบจะจํากัดข้อมูล YouTube Analytics บางรายการเมื่อเมตริกไม่เป็นไปตามเกณฑ์ที่กําหนด ปัญหานี้อาจเกิดขึ้นได้กับรายงานที่หลากหลาย ในทางปฏิบัติหมายความว่ารายงานอาจไม่มีข้อมูลของคุณทั้งหมด (หรือทั้งหมด) ในกรณีต่อไปนี้

1. วิดีโอหรือช่องมีการเข้าชมที่จํากัดในระยะเวลาที่ระบุ

   หรือ

2. คุณได้เลือกตัวกรองหรือมิติข้อมูล เช่น แหล่งที่มาของการเข้าชมหรือประเทศ ซึ่งค่าไม่เป็นไปตามเกณฑ์ที่กําหนด

ในกรณีที่ข้อมูลมีจํากัด ผลรวมในรายงานต่างๆ อาจแตกต่างกัน โดยขึ้นอยู่กับวิธีที่รายงานเหล่านั้นรวมข้อมูล

เช่น สมมติว่าเจ้าของช่องดึงข้อมูลรายงาน 2 ฉบับ รายงานฉบับแรกแสดงยอดดูทั้งหมดของวิดีโอหนึ่งๆ และรายงานที่ 2 จะแสดงยอดดูทั้งหมดของวิดีโอนั้นตามประเทศ ในระหว่างช่วงเวลาที่ระบุ ให้สมมติว่าวิดีโอมียอดดู 1,000 ครั้ง โดยมียอดดู 500 ครั้งในสหรัฐอเมริกา 498 ครั้งในแคนาดาและ 2 ครั้งเกิดขึ้นในฝรั่งเศส

ในตัวอย่างนี้ รายงานฉบับแรกจะระบุว่ามียอดดูวิดีโอ 1, 000 ครั้ง รายงานฉบับที่ 2 จะระบุว่าวิดีโอดังกล่าวมียอดดูในสหรัฐอเมริกา 500 ครั้งและอีก 498 ครั้งในแคนาดา ด้วยเหตุนี้ ยอดดูทั้งหมดในรายงานทั้ง 2 รายการจึงแตกต่างกัน โปรดทราบว่ารายงานที่ 2 จะไม่มีการระบุว่ามีการดูอีก 2 ครั้ง (หรือการดูเกิดขึ้นในฝรั่งเศส)

YouTube จะไม่เผยแพร่เกณฑ์จริงที่ทําให้ข้อมูลถูกจํากัดหรืออาจเปลี่ยนแปลงได้ตามการพิจารณาตามที่เห็นสมควรของ YouTube

ประเภทข้อมูลที่จํากัด

ข้อมูลต่อไปนี้อาจถูกจํากัดในรายงาน YouTube Analytics

• ข้อมูลประชากร เช่น อายุและเพศ
• ข้อมูลทางภูมิศาสตร์ ซึ่งรวมถึงเมตริกหรือมิติข้อมูลที่เกี่ยวข้องกับประเทศหรือภูมิภาคที่ผู้ชมอาศัยอยู่ เช่น ประเทศหรือภูมิภาค อย่างไรก็ตาม โปรดทราบว่ารายงานจะไม่นําเกณฑ์ทางภูมิศาสตร์ไปใช้กับเมตริกรายได้
• เมตริกที่เกี่ยวข้องกับแหล่งที่มาของการเข้าชมที่เฉพาะเจาะจง เช่น ข้อความค้นหาหรือ URL ภายนอกที่นําไปสู่ยอดดูวิดีโอ เช่น ข้อความค้นหาและ URL ที่นําไปสู่ยอดดูจํานวนน้อยจะไม่ปรากฏในรายงาน แต่คุณยังคงเห็นข้อความค้นหาและ URL ที่นําผู้ชมจํานวนมากไปยังเนื้อหาของคุณ

ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อมูลที่จํากัดในรายงาน YouTube Analytics ได้ที่ศูนย์ช่วยเหลือของ YouTube

การใช้โควต้า

คําขอ API แต่ละรายการที่คุณส่งจะนับเป็น 1 หน่วยของโควต้าการใช้งาน API ขีดจํากัดโควต้าจะแสดงในแผงโควต้าในคอนโซล Google API