تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

كتابة طلب العميل الأول

مقدمة

وهذا المستند مخصّص للمطوّرين الذين يريدون كتابة تطبيقات يمكنها التفاعل مع PageSpeed Insights API.

إحصاءات PageSpeed هي أداة تسجّل مستوى الأداء الفعلي لصفحة على الأجهزة الجوّالة وأجهزة الكمبيوتر المكتبي، وتقدم اقتراحات حول كيفية تحسين تلك الصفحة لمساعدة المطوّرين على تحسين صفحات الويب لديهم. يمكنك استخدام PageSpeed Insights API لإنشاء نتيجة سرعة PageSpeed ونتيجة التحسين والاقتراحات بشكل آلي.

قبل البدء

الحصول على حساب Google

يجب أن يكون لديك حساب على Google لكي تتمكّن من الحصول على مفتاح واجهة برمجة التطبيقات لتعريف Google بتطبيقك. (انظر أدناه).

الإلمام بأدوات PageSpeed

إذا لم تكن معتادًا على استخدام PageSpeed، راجع أفضل ممارسات أداء الويب في PageSpeed.

التعرّف على كيفية التعرُّف على تطبيقك لدى Google

يحتاج تطبيقك إلى تحديد نفسه في كل مرة يرسل فيها طلبًا إلى واجهة برمجة التطبيقات لإحصاءات PageSpeed، وذلك من خلال تضمين مفتاح واجهة برمجة التطبيقات مع كل طلب.

الحصول على مفتاح واجهة برمجة التطبيقات واستخدامه

يمكنك بدلاً من ذلك إنشاء حساب في صفحة "بيانات الاعتماد".

بعد حصولك على مفتاح واجهة برمجة التطبيقات، يمكن لتطبيقك إلحاق معلَمة طلب البحث key=yourAPIKey بجميع عناوين URL للطلبات.

مفتاح واجهة برمجة التطبيقات آمن للتضمين في عناوين URL؛ ولا يحتاج إلى أي ترميز.

خلفية واجهة برمجة التطبيقات لإحصاءات PageSpeed

تتضمن النتائج التي تعرضها واجهة برمجة التطبيقات PageSpeed Insights API أنواع المعلومات التالية:

تجربة التحميل: يتضمّن قسم "تجربة التحميل" فئة السرعة الإجمالية ("FAST" أو "متوسط" أو "بطيء") وتوزيعات الفئات.
إحصاءات الصفحة: يحتوي قسم "إحصاءات الصفحة" على بعض النتائج الإحصائية المفيدة، مثل عدد مرات الإرسال والاستقبال المطلوبة وإجمالي وحدات البايت المستخدمة. ويشير ذلك إلى أنّه إذا كان من الممكن أن تكون الصفحة أسرع من خلال تعديل المظهر والوظائف.
نتيجة التحسين: تشير نتيجة تحسين PageSpeed (0-100) إلى مدى جودة تحسين الصفحة، حيث تشير النتيجة المرتفعة إلى قلة فرص التحسين، بينما تشير النتيجة المنخفضة إلى مجال أكبر للتحسين.
القاعدة: تحلل سرعة الصفحة صفحات الويب باستخدام القواعد. تستند كل قاعدة من قواعد سرعة الصفحة إلى المبادئ العامة لأداء صفحة الويب، مثل التخزين المؤقت للموارد وحجم تحميل البيانات وتنزيلها وأوقات إرسال البيانات واستقبالها على خادم العميل. تُنشئ قواعد PageSpeed نتائج القواعد وتأثيراتها، كما هو موضح أدناه.
نتيجة القاعدة: نتيجة القاعدة هي اقتراح يتم إنشاؤه بواسطة قاعدة إذا تم تنفيذها، ستجعل الصفحة أسرع وتزيد نتيجة PageSpeed لتلك الصفحة. على سبيل المثال، إذا تم عرض مورد قابل للضغط بدون ضغط، فستنشئ قاعدة تفعيل الضغط في PageSpeed نتيجة تقترح على مطوّر البرامج تفعيل الضغط لهذا المورد.
تأثير القاعدة: تنشئ كل قاعدة من قواعد سرعة الصفحة رقم تأثير (قيمة نقطة عائمة غير محدودة) يشير إلى أهمية أو أولوية تنفيذ اقتراحات نتيجة القاعدة بالنسبة إلى القواعد الأخرى. على سبيل المثال، إذا كان تفعيل الضغط سيؤدي إلى توفير 1 ميغابايت، بينما سيؤدي تحسين الصور إلى توفير 500 كيلوبايت، سيكون لقاعدة "تفعيل الضغط" قيمة تأثير أكبر بمرتين من قاعدة "تحسين الصور". يشير تأثير الصفر إلى أنه لا توجد اقتراحات لتحسين تلك القاعدة.

استدعاء واجهة برمجة التطبيقات

ولاستدعاء واجهة برمجة التطبيقات، يجب استدعاء الإجراء runPagespeed، مع تحديد عنوان URL ومفتاح واجهة برمجة التطبيقات والمَعلمات الأخرى في سلسلة طلب البحث. يُرجى الاطّلاع على المستندات المرجعية لواجهة برمجة التطبيقات للاطّلاع على مزيد من التفاصيل.

أمثلة على طلبات البيانات من واجهة برمجة التطبيقات

من سطر الأوامر

يمكنك استدعاء واجهة برمجة التطبيقات لإحصاءات PageSpeed من سطر الأوامر في Linux/UNIX باستخدام برنامج مثل curl.

يستخدم المثال التالي هذا الأسلوب لجلب نتائج PageSpeed على الأجهزة الجوّالة لعنوان URL https://developers.google.com/speed/pagespeed/insights/. يتم عرض نتيجة PageSpeed وإحصاءات الصفحة والنتائج المنسّقة في PageSpeed بتنسيق بيانات JSON.

يتم ربط النتائج المنسَّقة بمعرّفات القاعدة (مثل AvoidBadRequests أو MinifyJavaScript)، وتحتوي على النتيجة ومدى التأثير لتلك القاعدة، بالإضافة إلى الاقتراحات التي يتم إنشاؤها من خلال القاعدة التي تؤدي إلى تسريع عملية تحميل الصفحة في حال تطبيقها. لمعرفة المزيد من المعلومات عن الحقول في استجابة JSON، يمكنك الاطّلاع على المستند مرجع واجهة برمجة التطبيقات لإحصاءات PageSpeed.

الطلب:

$ curl 'https://www.googleapis.com/pagespeedonline/v4/runPagespeed?url=https://developers.google.com/speed/pagespeed/insights/&strategy=mobile&key=yourAPIKey'

الرد:

{
 "captchaResult": "CAPTCHA_NOT_NEEDED",
 "kind": "pagespeedonline#result",
 "id": "https://developers.google.com/speed/pagespeed/insights/",
 "responseCode": 200,
 "title": "PageSpeed Insights",
 "ruleGroups": {
  "SPEED": {
   "score": 99
  }
 },
 "loadingExperience": {
  "id": "https://developers.google.com/speed/pagespeed/insights/",
  "metrics": {
   "FIRST_CONTENTFUL_PAINT_MS": {
    "median": 678,
    "distributions": [
     {
      "min": 0,
      "max": 1567,
      "proportion": 0.8726942914078067
     },
     {
      "min": 1567,
      "max": 2963,
      "proportion": 0.07357226585394444
     },
     {
      "min": 2963,
      "proportion": 0.053733442738248746
     }
    ],
    "category": "FAST"
   },
   "DOM_CONTENT_LOADED_EVENT_FIRED_MS": {
    "median": 559,
    "distributions": [
     {
      "min": 0,
      "max": 2120,
      "proportion": 0.9287991742172268
     },
     {
      "min": 2120,
      "max": 4226,
      "proportion": 0.035877050120426655
     },
     {
      "min": 4226,
      "proportion": 0.0353237756623466
     }
    ],
    "category": "FAST"
   }
  },
  "overall_category": "FAST",
  "initial_url": "https://developers.google.com/speed/pagespeed/insights/"
 },
 "pageStats": {
  "numberResources": 11,
  "numberHosts": 6,
  "totalRequestBytes": "1874",
  "numberStaticResources": 6,
  "htmlResponseBytes": "72494",
  "overTheWireResponseBytes": "324002",
  "cssResponseBytes": "8467",
  "imageResponseBytes": "5363",
  "javascriptResponseBytes": "841488",
  "otherResponseBytes": "14548",
  "numberJsResources": 4,
  "numberCssResources": 1,
  "numTotalRoundTrips": 13,
  "numRenderBlockingRoundTrips": 0
 },
 "formattedResults": {
  "locale": "en_US",
  "ruleResults": {
   "AvoidLandingPageRedirects": {
    "localizedRuleName": "Avoid landing page redirects",
    "ruleImpact": 0.0,
    "groups": [
     "SPEED"
    ],
    "summary": {
     "format": "Your page has no redirects. Learn more about {{BEGIN_LINK}}avoiding landing page redirects{{END_LINK}}.",
     "args": [
      {
       "type": "HYPERLINK",
       "key": "LINK",
       "value": "https://developers.google.com/speed/docs/insights/AvoidRedirects"
      }
     ]
    }
   },
   "EnableGzipCompression": {
    "localizedRuleName": "Enable compression",
    "ruleImpact": 0.0,
    "groups": [
     "SPEED"
    ],
    "summary": {
     "format": "You have compression enabled. Learn more about {{BEGIN_LINK}}enabling compression{{END_LINK}}.",
     "args": [
      {
       "type": "HYPERLINK",
       "key": "LINK",
       "value": "https://developers.google.com/speed/docs/insights/EnableCompression"
      }
     ]
    }
   },
   ...
   "PrioritizeVisibleContent": {
    "localizedRuleName": "Prioritize visible content",
    "ruleImpact": 0.0,
    "groups": [
     "SPEED"
    ],
    "summary": {
     "format": "You have the above-the-fold content properly prioritized. Learn more about {{BEGIN_LINK}}prioritizing visible content{{END_LINK}}.",
     "args": [
      {
       "type": "HYPERLINK",
       "key": "LINK",
       "value": "https://developers.google.com/speed/docs/insights/PrioritizeVisibleContent"
      }
     ]
    }
   }
  }
 },
 "version": {
  "major": 1,
  "minor": 15
 }
}

من JavaScript

يمكنك استدعاء واجهة برمجة التطبيقات لإحصاءات PageSpeed من JavaScript في المتصفح، باستخدام مَعلمة طلب البحث callback ودالة الاستدعاء لإنشاء نتائج JSON-P. ويتيح لك هذا كتابة تطبيقات غنية تعرض بيانات PageSpeed بدون كتابة أي رمز من جانب الخادم.

يستخدم المثال التالي هذا الأسلوب لعرض نتائج PageSpeed ومعلومات أخرى لعنوان URL https://developers.google.com/speed/pagespeed/insights/. يستخدم هذا المثال أيضًا أدوات مخططات Google لعرض المعلومات التي يتم إنشاؤها بواسطة PageSpeed Insights API.

أولاً، حدِّد مفتاح Google API (تعرَّف على مزيد من المعلومات حول مفاتيح واجهة برمجة التطبيقات):

<script>
// Specify your actual API key here:
var API_KEY = 'yourAPIKey';

// Specify the URL you want PageSpeed results for here:
var URL_TO_GET_RESULTS_FOR = 'https://developers.google.com/speed/pagespeed/insights/';
</script>

بعد ذلك، استرجع نتائج PageSpeed من PageSpeed Insights API:

<script>
var API_URL = 'https://www.googleapis.com/pagespeedonline/v4/runPagespeed?';
var CHART_API_URL = 'http://chart.apis.google.com/chart?';

// Object that will hold the callbacks that process results from the
// PageSpeed Insights API.
var callbacks = {}

// Invokes the PageSpeed Insights API. The response will contain
// JavaScript that invokes our callback with the PageSpeed results.
function runPagespeed() {
  var s = document.createElement('script');
  s.type = 'text/javascript';
  s.async = true;
  var query = [
    'url=' + URL_TO_GET_RESULTS_FOR,
    'callback=runPagespeedCallbacks',
    'key=' + API_KEY,
  ].join('&');
  s.src = API_URL + query;
  document.head.insertBefore(s, null);
}

// Our JSONP callback. Checks for errors, then invokes our callback handlers.
function runPagespeedCallbacks(result) {
  if (result.error) {
    var errors = result.error.errors;
    for (var i = 0, len = errors.length; i < len; ++i) {
      if (errors[i].reason == 'badRequest' && API_KEY == 'yourAPIKey') {
        alert('Please specify your Google API key in the API_KEY variable.');
      } else {
        // NOTE: your real production app should use a better
        // mechanism than alert() to communicate the error to the user.
        alert(errors[i].message);
      }
    }
    return;
  }

  // Dispatch to each function on the callbacks object.
  for (var fn in callbacks) {
    var f = callbacks[fn];
    if (typeof f == 'function') {
      callbacks[fn](result);
    }
  }
}

// Invoke the callback that fetches results. Async here so we're sure
// to discover any callbacks registered below, but this can be
// synchronous in your code.
setTimeout(runPagespeed, 0);
</script>

باستخدام الرمز أعلاه لجلب النتائج من واجهة برمجة تطبيقات PageSpeed Insights، نحن الآن جاهزون لعرض معلومات مهمة في متصفح المستخدم باستخدام الأمثلة أدناه.

المثال 1: عرض أهم اقتراحات PageSpeed

يعرض هذا المثال أسماء أهم اقتراحات PageSpeed للصفحة التي يتم تحليلها، كقائمة غير مرتبة. مثال:

تحسين التخزين المؤقت للمتصفح
تأجيل تحليل JavaScript
تصغير HTML
تصغير JavaScript

ملاحظة: تتوفر البيانات اللازمة لعرض نتائج PageSpeed API بالكامل من خلال PageSpeed Insights API، ولكن لتبسيط المثال، لا يتم استخدام جميع هذه البيانات هنا.

<script>
callbacks.displayTopPageSpeedSuggestions = function(result) {
  var results = [];
  var ruleResults = result.formattedResults.ruleResults;
  for (var i in ruleResults) {
    var ruleResult = ruleResults[i];
    // Don't display lower-impact suggestions.
    if (ruleResult.ruleImpact < 3.0) continue;
    results.push({name: ruleResult.localizedRuleName,
                  impact: ruleResult.ruleImpact});
  }
  results.sort(sortByImpact);
  var ul = document.createElement('ul');
  for (var i = 0, len = results.length; i < len; ++i) {
    var r = document.createElement('li');
    r.innerHTML = results[i].name;
    ul.insertBefore(r, null);
  }
  if (ul.hasChildNodes()) {
    document.body.insertBefore(ul, null);
  } else {
    var div = document.createElement('div');
    div.innerHTML = 'No high impact suggestions. Good job!';
    document.body.insertBefore(div, null);
  }
};

// Helper function that sorts results in order of impact.
function sortByImpact(a, b) { return b.impact - a.impact; }
</script>

المثال 2: عرض رسم بياني دائري تفصيلي لحجم الموارد

يعرض هذا المثال مخططًا دائريًا يوضح تقسيم حجم الموارد للصفحة التي يتم تحليلها. مثال:

<script>
var RESOURCE_TYPE_INFO = [
  {label: 'JavaScript', field: 'javascriptResponseBytes', color: 'e2192c'},
  {label: 'Images', field: 'imageResponseBytes', color: 'f3ed4a'},
  {label: 'CSS', field: 'cssResponseBytes', color: 'ff7008'},
  {label: 'HTML', field: 'htmlResponseBytes', color: '43c121'},
  {label: 'Flash', field: 'flashResponseBytes', color: 'f8ce44'},
  {label: 'Text', field: 'textResponseBytes', color: 'ad6bc5'},
  {label: 'Other', field: 'otherResponseBytes', color: '1051e8'},
];

callbacks.displayResourceSizeBreakdown = function(result) {
  var stats = result.pageStats;
  var labels = [];
  var data = [];
  var colors = [];
  var totalBytes = 0;
  var largestSingleCategory = 0;
  for (var i = 0, len = RESOURCE_TYPE_INFO.length; i < len; ++i) {
    var label = RESOURCE_TYPE_INFO[i].label;
    var field = RESOURCE_TYPE_INFO[i].field;
    var color = RESOURCE_TYPE_INFO[i].color;
    if (field in stats) {
      var val = Number(stats[field]);
      totalBytes += val;
      if (val > largestSingleCategory) largestSingleCategory = val;
      labels.push(label);
      data.push(val);
      colors.push(color);
    }
  }
  // Construct the query to send to the Google Chart Tools.
  var query = [
    'chs=300x140',
    'cht=p3',
    'chts=' + ['000000', 16].join(','),
    'chco=' + colors.join('|'),
    'chd=t:' + data.join(','),
    'chdl=' + labels.join('|'),
    'chdls=000000,14',
    'chp=1.6',
    'chds=0,' + largestSingleCategory,
  ].join('&');
  var i = document.createElement('img');
  i.src = 'http://chart.apis.google.com/chart?' + query;
  document.body.insertBefore(i, null);
};
</script>

فيديو توضيحي

عرض توضيحي لواجهة برمجة تطبيقات PageSpeed Insights في مؤتمر Google I/O BootCamp 2011.