วิธีใช้ CrUX History API

Johannes Henkel

Jasmine Yan

Barry Pollard

Published: Feb 7, 2023, Last updated: Apr 11, 2025

คู่มือนี้จะแนะนำปลายทาง Chrome UX Report (CrUX) History API ซึ่งแสดงอนุกรมเวลาของข้อมูลประสิทธิภาพของเว็บ ข้อมูลนี้จะอัปเดตทุกสัปดาห์ และช่วยให้คุณดูประวัติข้อมูลย้อนหลังได้ประมาณ 6 เดือน โดยมีจุดข้อมูล 40 จุดที่เว้นระยะห่างกัน 1 สัปดาห์

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

ลองใช้ API ในหน้านี้

ลองใช้งาน

ค้นหา CrUX API รายวัน

สรุปจากบทความก่อนหน้าเกี่ยวกับ CrUX API คุณสามารถดูภาพรวมของข้อมูลภาคสนามสำหรับต้นทางหนึ่งๆ ได้ด้วยวิธีต่อไปนี้

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [{
          "start": 0, "end": 2500, "density": 0.9192
        }, {
          "start": 2500, "end": 4000, "density": 0.0513
        }, {
          "start": 4000, "density": 0.0294
        }],
        "percentiles": {
          "p75": 1303
        }
      }
      // ...
    },
    "collectionPeriod": {
      "firstDate": { "year": 2022, "month": 12, "day": 27 },
      "lastDate": { "year": 2023, "month": 1, "day": 23 }
    }
  }
}

ภาพรวมนี้ประกอบด้วยค่าความหนาแน่นของฮิสโทแกรมและค่าเปอร์เซ็นไทล์สำหรับระยะเวลาการเก็บรวบรวมข้อมูล 28 วันหนึ่งๆ ซึ่งในกรณีนี้คือตั้งแต่วันที่ 27 ธันวาคม 2022 ถึง 23 มกราคม 2023

ค้นหา CrUX History API

หากต้องการเรียกปลายทางประวัติ ให้เปลี่ยน queryRecord ใน URL เป็น queryHistoryRecord ในคำสั่ง curl การใช้ คีย์ CrUX API เดียวกันกับการเรียกก่อนหน้าจะใช้ได้ collectionPeriodCount จะระบุจำนวนรายการอนุกรมเวลาที่จะแสดง โดยค่าสูงสุดคือ 40 หากไม่ระบุ ระบบจะตั้งค่าเริ่มต้นเป็น 25

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'

รูปร่างโดยรวมของการตอบกลับจะคล้ายกัน แต่มีข้อมูลมากขึ้น ตอนนี้ฟิลด์ที่มีค่าเปอร์เซ็นไทล์ที่ 75 (p75) และค่าความหนาแน่นของฮิสโทแกรมจะมีอนุกรมเวลาแทนที่จะเป็นจุดข้อมูลเดียว

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377
          ]
        }
      }
      // ...
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]
  }
}

ในตัวอย่างนี้ อนุกรมเวลา densities สำหรับ Bucket 0 ถึง 2, 500 มิลลิวินาทีของ Largest Contentful Paint (LCP) เมตริกคือ [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. ความหนาแน่นแต่ละค่านี้ สังเกตได้ในรายการ collectionPeriods ที่เกี่ยวข้อง เช่น ความหนาแน่นค่าที่ 5 ซึ่งคือ 0.9183 เป็นความหนาแน่นสำหรับระยะเวลาการเก็บรวบรวมข้อมูลที่ 5 ซึ่งสิ้นสุดในวันที่ 3 กันยายน 2022 และ 0.9187 เป็นความหนาแน่นในระยะเวลาที่สิ้นสุดในสัปดาห์ถัดมา

กล่าวอีกนัยหนึ่งคือ จากการตีความรายการอนุกรมเวลาล่าสุดในตัวอย่างสำหรับ web.dev พบว่าตั้งแต่วันที่ 14 สิงหาคม 2022 ถึง 10 กันยายน 2022 การโหลดหน้าเว็บ 91.87% มีค่า LCP น้อยกว่า 2,500 มิลลิวินาที, 5.27% มีค่าระหว่าง 2,500 มิลลิวินาทีถึง 4,000 มิลลิวินาที และ 2.85% มีค่ามากกว่า 4,000 มิลลิวินาที

เช่นเดียวกัน ค่า p75 ก็มีอนุกรมเวลาด้วย โดยค่า LCP p75 ตั้งแต่วันที่ 14 สิงหาคม 2022 ถึง 10 กันยายน 2022 คือ 1377 ซึ่งหมายความว่าสำหรับระยะเวลาการเก็บรวบรวมข้อมูลนี้ ประสบการณ์ของผู้ใช้ 75% มีค่า LCP น้อยกว่า 1,377 มิลลิวินาที และประสบการณ์ของผู้ใช้ 25% มีค่า LCP มากกว่า 1,377 มิลลิวินาที

แม้ว่าตัวอย่างจะแสดงรายการอนุกรมเวลาและระยะเวลาการเก็บรวบรวมข้อมูลเพียง 6 รายการ แต่การตอบกลับจาก API จะแสดงรายการอนุกรมเวลา 25 รายการโดยค่าเริ่มต้น และสูงสุด 40 รายการเมื่อระบุ "collectionPeriodCount": 40 ในคำขอ เนื่องจากวันที่สิ้นสุดของระยะเวลาการเก็บรวบรวมข้อมูลแต่ละรายการเป็นวันเสาร์ที่ห่างกัน 7 วัน ดังนั้น "collectionPeriodCount": 40 จะครอบคลุม 10 เดือน

ในการตอบกลับใดๆ ความยาวของอนุกรมเวลาสำหรับความหนาแน่นของ Bucket ฮิสโทแกรมและค่า p75 จะเท่ากับความยาวของอาร์เรย์ในฟิลด์ collectionPeriods อย่างแน่นอน โดยจะมีการจับคู่แบบหนึ่งต่อหนึ่งตามดัชนีในอาร์เรย์เหล่านี้

ค้นหาข้อมูลระดับหน้าเว็บ

นอกจากข้อมูลระดับต้นทางแล้ว CrUX History API ยังให้สิทธิ์เข้าถึงข้อมูลระดับหน้าเว็บย้อนหลังด้วย แม้ว่าข้อมูลระดับต้นทางจะใช้ได้ก่อนหน้านี้โดยใช้ ชุดข้อมูล CrUX ใน BigQuery แต่ข้อมูลย้อนหลังระดับหน้าเว็บ จะใช้ได้ก็ต่อเมื่อเว็บไซต์เก็บรวบรวมและจัดเก็บข้อมูลด้วยตนเอง ตอนนี้ API ใหม่จะปลดล็อกข้อมูลย้อนหลังระดับหน้าเว็บดังกล่าว

คุณสามารถค้นหาข้อมูลระดับหน้าเว็บได้ในลักษณะเดียวกัน แต่ใช้ url แทน origin ในเพย์โหลด

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"url": "https://web.dev/blog/"}'

ข้อมูลย้อนหลังระดับหน้าเว็บ (และระดับต้นทาง) เป็นไปตาม ข้อกำหนดด้านสิทธิ์เดียวกันกับ ส่วนอื่นๆ ของ CrUX ดังนั้นบางหน้าเว็บอาจไม่มีบันทึกย้อนหลังที่สมบูรณ์ ในกรณีเหล่านี้ ระบบจะแสดงข้อมูลที่ "ขาดหายไป" เป็น "NaN" สำหรับความหนาแน่น histogramTimeseries และ null สำหรับ percentilesTimeseries เหตุผลที่แตกต่างกันคือความหนาแน่นของฮิสโทแกรมจะเป็นตัวเลขเสมอ ในขณะที่เปอร์เซ็นไทล์อาจเป็นตัวเลขหรือสตริง (CLS ใช้สตริง แม้ว่าจะมีลักษณะเป็นตัวเลข)

แสดงข้อมูลเป็นภาพ

วิธีที่ง่ายที่สุดในการแสดงข้อมูลเป็นภาพคือผ่าน CrUX Vis ซึ่งเป็นเครื่องมือที่สร้างขึ้นมาโดยเฉพาะเพื่อ แสดงให้เห็นถึงประสิทธิภาพของ CrUX History API อ่านเพิ่มเติมใน เอกสารประกอบของ CrUX Vis

เราได้สร้าง Colab ตัวอย่าง เพื่อให้คุณสร้างแผนภูมิที่คล้ายกันด้วยตนเอง Colab หรือ "Colaboratory" ช่วยให้คุณเขียนและเรียกใช้ Python จากภายในเบราว์เซอร์ได้ The CrUX History API Colab (แหล่งที่มา) ใช้ Python เพื่อเรียก API และสร้างแผนภูมิข้อมูล

Colab นี้ช่วยให้คุณสร้างแผนภูมิ p75, แผนภูมิ 3 Bucket, รับข้อมูลในรูปแบบตาราง และดูคู่คำขอและการตอบกลับสำหรับ CrUX API ได้โดยการกรอกแบบฟอร์มสั้นๆ คุณไม่จำเป็นต้องเป็นโปรแกรมเมอร์จึงจะใช้ Colab นี้ได้ แต่คุณสามารถดูโค้ด Python และแก้ไขให้เป็นสิ่งที่น่าทึ่งได้

นี่เป็นเพียงตัวอย่างหนึ่งของวิธีใช้ API ใหม่นี้ API นี้เป็นปลายทาง HTTP ที่อิงตาม JSON จึงค้นหาได้จากเทคโนโลยีใดก็ได้

บทสรุป

ก่อนที่จะมีการเปิดตัวปลายทาง CrUX History API เจ้าของเว็บไซต์จะได้รับข้อมูลย้อนหลังจาก CrUX ได้อย่างจำกัด ข้อมูลระดับต้นทางรายเดือนใช้ได้โดยใช้ BigQuery แต่ข้อมูลรายสัปดาห์และข้อมูลย้อนหลังระดับหน้าเว็บไม่พร้อมใช้งาน เจ้าของเว็บไซต์สามารถบันทึกข้อมูลนี้ได้ด้วยตนเองโดยใช้ API รายวัน แต่โดยส่วนใหญ่แล้วความจำเป็นในการดำเนินการนี้จะพบหลังจากที่เมตริกถดถอยลง

เราหวังว่าการเปิดตัว CrUX History API นี้จะช่วยให้เจ้าของเว็บไซต์เข้าใจเมตริกของเว็บไซต์ที่เปลี่ยนแปลงไปได้ดียิ่งขึ้น และเป็นเครื่องมือวินิจฉัยเมื่อเกิดปัญหา หากคุณใช้ API ใหม่นี้ โปรดส่งความคิดเห็นมาที่ กลุ่ม Google รายงาน Chrome UX (Discussions)