Published: Feb 7, 2023, Last updated: Apr 11, 2025
يعرّف هذا الدليل نقطة نهاية CrUX History API ، التي توفّر سلسلة زمنية لبيانات أداء الويب. يتم تعديل هذه البيانات أسبوعيًا، وتتيح لك الاطّلاع على بيانات سابقة تعود إلى 6 أشهر تقريبًا، مع 40 نقطة بيانات متباعدة بأسبوع.
عند استخدامها مع التعديلات اليومية من نقطة نهاية CrUX 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 للحزمة من 0 إلى 2500 ملّي ثانية لمقياس
سرعة عرض أكبر محتوى مرئي (LCP) هي
[0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. تم رصد كل من هذه الكثافات خلال إدخال collectionPeriods المقابل. على سبيل المثال، كانت الكثافة الخامسة، 0.9183، هي الكثافة لفترة جمع البيانات الخامسة، التي انتهت في 3 سبتمبر 2022، وكانت 0.9187 هي الكثافة في الفترة التي انتهت في الأسبوع الذي يلي ذلك.
بمعنى آخر، عند تفسير آخر إدخالات السلسلة الزمنية في المثال الخاص بـ web.dev، تبيّن أنّه في الفترة من 14 أغسطس 2022 حتى 10 سبتمبر 2022، كانت 91.87% من عمليات تحميل الصفحات تتضمّن قيم LCP أقل من 2500 ملّي ثانية، و5.27% تتضمّن قيمًا بين 2500 ملّي ثانية و4000 ملّي ثانية، و2.85% تتضمّن قيمًا أكبر من 4000 ملّي ثانية.
وبالمثل، هناك سلسلة زمنية لقيم الشريحة المئوية الـ 75: كانت الشريحة المئوية الـ 75 لـ LCP في الفترة من 14 أغسطس 2022 إلى 10 سبتمبر 2022 هي 1377. يعني ذلك أنّه خلال فترة جمع البيانات هذه، كانت 75% من تجارب المستخدمين تتضمّن سرعة عرض أكبر محتوى مرئي أقل من 1377 ملّي ثانية، و25% من تجارب المستخدمين تتضمّن سرعة عرض أكبر محتوى مرئي أكبر من 1377 ملّي ثانية.
على الرغم من أنّ المثال لا يعرض سوى 6 إدخالات للسلسلة الزمنية وفترات جمع البيانات، فإنّ الردود من واجهة برمجة التطبيقات توفّر 25 إدخالاً للسلسلة الزمنية تلقائيًا و40 كحد أقصى، وذلك عند تحديد "collectionPeriodCount": 40 في الطلب. بما أنّ تواريخ انتهاء كل من فترات جمع البيانات هذه هي أيام سبت متباعدة بـ 7 أيام، فإنّ "collectionPeriodCount": 40 يغطّي 10 أشهر.
في أي ردّ معيّن، سيكون طول السلسلة الزمنية لكثافات حزمة المدرّج التكراري وقيم الشريحة المئوية الـ 75 هو نفسه تمامًا طول المصفوفة في حقل collectionPeriods: هناك تطابق واحد لواحد استنادًا إلى الفهرس في هاتَين المصفوفتَين.
طلب بيانات على مستوى الصفحة
بالإضافة إلى البيانات على مستوى المصدر، تتيح CrUX History API الوصول إلى البيانات السابقة على مستوى الصفحة. على الرغم من أنّ البيانات على مستوى المصدر كانت متاحة سابقًا باستخدام الـ CrUX dataset على BigQuery، لم تكن البيانات السابقة على مستوى الصفحة متاحة إلا إذا جمعت المواقع الإلكترونية البيانات وخزّنتها بنفسها. تتيح واجهة برمجة التطبيقات الجديدة الآن الوصول إلى هذه البيانات السابقة على مستوى الصفحة.
يمكن طلب البيانات على مستوى الصفحة بالطريقة نفسها، ولكن باستخدام 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 وتنفيذها من داخل المتصفّح. يستخدم Colab الخاص بـ CrUX History API (المصدر) لغة Python لإجراء طلبات إلى واجهة برمجة التطبيقات ورسم البيانات بيانيًا.
يتيح لك Colab هذا إنشاء رسوم بيانية للشريحة المئوية الـ 75، ورسوم بيانية ثلاثية الحزم، والحصول على البيانات في شكل جدول، والاطّلاع على زوج الطلب والردّ لواجهة CrUX API، وذلك عن طريق ملء نموذج قصير. لست بحاجة إلى أن تكون مبرمجًا لاستخدام هذه الأداة، ولكن يمكنك الاطّلاع على رمز Python وتعديله ليصبح شيئًا مذهلاً.
هذا مجرد مثال واحد على كيفية استخدام واجهة برمجة التطبيقات الجديدة هذه. بما أنّ واجهة برمجة التطبيقات هي نقطة نهاية HTTP تستند إلى JSON، يمكن طلب بياناتها من أي تكنولوجيا.
الخاتمة
قبل طرح نقطة نهاية CrUX History API، كانت المعلومات السابقة التي يمكن لمالكي المواقع الإلكترونية الحصول عليها من CrUX محدودة. كانت البيانات على مستوى المصدر متاحة شهريًا باستخدام BigQuery، ولكن لم تكن البيانات الأسبوعية متاحة، وكذلك البيانات السابقة على مستوى الصفحة. كان بإمكان مالكي المواقع الإلكترونية تسجيل هذه البيانات بأنفسهم باستخدام واجهة برمجة التطبيقات اليومية، ولكن غالبًا ما لم يتم اكتشاف الحاجة إلى ذلك إلا بعد حدوث انخفاض في المقاييس.
نأمل من خلال طرح CrUX History API أن نتيح لمالكي المواقع الإلكترونية فهمًا أفضل لمقاييس مواقعهم الإلكترونية المتغيّرة، وأن نقدّم لهم أداة تشخيصية عند ظهور المشاكل. إذا كنت تستخدم واجهة برمجة التطبيقات الجديدة، يُرجى إرسال ملاحظاتك إلى مجموعة Google Chrome UX Report (Discussions).