الاستعلام عن مجموعات المقاييس

بعد إعداد كل شيء، يمكنك إرسال طلبات إلى واجهة برمجة التطبيقات Google Play Developer Reporting API لاسترداد البيانات الوصفية حول مجموعات المقاييس والاستعلام عن مقاييسها.

توضّح نماذج الرموز البرمجية التالية كيفية إرسال بعض الطلبات البسيطة. على سبيل المثال، توضّح الطرق أدناه كيفية استرداد مقاييس مختلفة لتطبيقك. هناك بعض مَعلمات طلب البحث المختلفة التي يمكن استخدامها لتضييق نطاق طلب البحث.

استرداد البيانات الوصفية لمجموعة المقاييس

يسترد المثال التالي البيانات الوصفية لمجموعة مقاييس نسبة الأعطال الخاصة بتطبيق وهمي، com.example.app.

طلب بسيط:

يحدّد طلب HTTP GET هذا مَعلمة اسم التطبيق ويعرض مورد المقاييس الكامل المرتبط بتطبيقك.

GET https://playdeveloperreporting.googleapis.com/v1beta1/apps/com.example.app/crashRateMetricSet

استجابة معلومات المقياس:

يتضمّن الردّ الحقول التالية ذات الصلة بمجموعة المقاييس:

{
  "freshness_info": {
    "freshness": [
      "aggregation_period": "DAILY"
      "latest_end_time": { year: "2021" month: "7" day: "22" time_zone: "America/Los_Angeles" }
    ]
  }
}

استخدام ميزة طلب البحث

يستخدم طلب HTTP POST التالي للمرجع نفسه نقطة النهاية query لاسترداد بيانات معيّنة من مجموعة المقاييس.

POST https://playdeveloperreporting.googleapis.com/v1beta1/apps/com.example.app/crashRateMetricSet:query

في نص الطلب، مرِّر خيارات الاستعلام لاسترداد المقاييس استنادًا إلى معايير محدّدة.

{
  "timeline_spec": {
    "aggregation_period": "DAILY"
    "start_time": { year: "2021" month: "7" day: "1" time_zone: "America/Los_Angeles" }
    "end_time": { year: "2021" month: "7" day: "3" time_zone: "America/Los_Angeles" }
   }
  "dimensions": ["apiLevel"]
  "metrics": ["errorReportCount", "distinctUsers"]
  "page_size": "10"
}

في ما يلي بعض الأمثلة على مستوى المجموعة:

الحقول
timelineSpec	object (TimelineSpec) تحديد مَعلمات تجميع المخطّط الزمني يُرجى الاطّلاع على مستندات كل مجموعة مقاييس للحصول على قائمة بفترات التجميع المتاحة.
dimensions[]	string السمات التي سيتم تقسيم المقاييس حسبها. يُرجى الاطّلاع على مستندات كل مجموعة مقاييس للحصول على قائمة بالسمات المتوافقة.
metrics[]	string المقاييس التي سيتم تجميعها
pageSize	integer الحد الأقصى لحجم البيانات المعروضة إذا لم يتم تحديدها، سيتم عرض 1, 000 صف كحد أقصى. الحدّ الأقصى للقيمة هو 100,000، وسيتم فرض القيمة 100,000 على القيم التي تتجاوز هذا الحدّ.

التعامل مع الردود

بعد أن يعالج الخادم طلبًا صالحًا يتضمّن حقولاً صالحة، يرسل رمز الحالة 200 OK الخاص ببروتوكول HTTP مع البيانات المطلوبة. إذا كان مَعلمة طلب البحث fields تتضمّن خطأ أو غير صالحة، يعرض الخادم رمز حالة HTTP 400 Bad Request، بالإضافة إلى رسالة خطأ تُعلم المستخدم بالمشكلة في اختيار الحقول (على سبيل المثال، "Invalid field timeline_spec").

في ما يلي مثال على الردّ المعروض في القسم التمهيدي أعلاه.

POST https://playdeveloperreporting.googleapis.com/v1beta1/apps/com.example.app/crashRateMetricSet:query

ستبدو الاستجابة على النحو التالي:

200 OK

{
  rows: [
    {
      aggregation_period: "DAILY"
      start_time: { year: "2021" month: "7" day: "1" time_zone: "America/Los_Angeles" }
      dimensions: [{dimension: "apiLevel" int64_value: "20"}]
      metrics: [
        {metric: "errorReportCount" decimal_value: "100"},
        {metric: "distinctUsers" decimal_value: "57"},
      ]
    }, {
      aggregation_period: "DAILY"
      start_time: { year: "2021" month: "7" day: "1" time_zone: "America/Los_Angeles" }
      dimensions: [{dimension: "apiLevel" int64_value: "21"}]
      metrics: [
        {metric: "errorReportCount" decimal_value: "123"},
        {metric: "distinctUsers" decimal_value: "65"},
      ]
    },
    ...
  ]
  next_page_token: "eW91IGhhdmUgdG9vIG11Y2ggZnJlZSB0aW1l"
}

ملاحظة: بالنسبة إلى واجهات برمجة التطبيقات التي تتيح مَعلمات طلب البحث لتصفّح البيانات على عدّة صفحات (maxResults وnextPageToken، على سبيل المثال)، استخدِم هذه المَعلمات لتقليل نتائج كل طلب بحث إلى حجم يمكن إدارته.