Reports API: تقرير استخدام الكيانات

يعرض تقرير استخدام الكيانات أنشطة خدمات Google Workspace المرتبطة بالكيانات التي يستخدمها مستخدمو حسابك. يمكن تخصيص هذه التقارير وفلترتها للحصول على معلومات استخدام معيّنة. وتتوفّر البيانات لآخر 30 يومًا.

لا يجوز استخدام تقرير استخدام الكيانات إلا لأغراض قانونية بما يتوافق مع "اتفاقية العملاء". تنطبق هذه التقارير أيضًا على Google Workspace وEducation.

استرداد كل أنشطة استخدام الكيانات

إن نوع الكيان الوحيد الذي تدعمه واجهة برمجة التطبيقات هذه في الوقت الحالي هو منتديات +Google. لاسترداد تقرير بجميع الأنشطة ذات الصلة بكيانات التطبيق في حسابك، استخدِم طلب HTTP GET التالي وأدرِج رمز التفويض المميز الموضّح في مستندات التفويض. لتسهيل القراءة، يتم تنسيق المثال التالي بإرجاع الأسطر:

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults

تمثّل القيمة date تاريخ حدوث الاستخدام ويكون الطابع الزمني بتنسيق ISO 8601، yyyy-mm-dd. ننصحك باستخدام المنطقة الزمنية لحسابك في هذا الشأن. لمزيد من المعلومات عن معلَمات سلسلة طلب البحث وخصائص الاستجابة، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات. للحصول على معلومات عن مَعلمات تقرير استخدام الكيانات، اطّلِع على مرجع مَعلمات استخدام الكيانات.

applicationParameters هي قائمة مفصولة بفواصل تضمّ المَعلمات التي تريد استردادها. ويتم تنسيق كل مَعلمة على النحو التالي: application:parameter_name، على سبيل المثال، gplus:community_name. ويتم توثيق المَعلمات المتاحة في مرجع مَعلمات استخدام الكيانات. إذا لم يتم تحديد أي معلَمات، سيتم عرض كل المَعلمات.

"parameterFilters" هي قائمة من الفلاتر المفصولة بفواصل ليتم تطبيقها على النتائج. يتم تنسيق كل فلتر على النحو التالي: application:parameter_name[relational_operator]parameter_value. على سبيل المثال، يؤدّي الفلتر gplus:num_total_members>100 إلى فلترة النتائج لكي لا تتضمّن سوى النتائج التي تكون فيها قيمة المعلَمة gplus:num_total_members أكبر من 100.

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

أمثلة

يحصل المثال التالي على تقرير يحتوي على جميع المَعلمات لجميع كيانات gplus_communities.

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11

يحصل المثال التالي على تقرير يحتوي على المَعلمة community_name لجميع كيانات gplus_communities.

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name

يتضمّن المثال التالي تقريرًا عن community_name وnum_total_members لكل كيان gplus_communities، وتتم فلترته حسب المنتديات التي تضمّ أكثر من 100 عضو. للاطّلاع على مثال لاستجابة واجهة برمجة التطبيقات، راجِع مثال استجابة JSON.

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11
?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members>100

استرداد تقرير لكيان محدّد

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

GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults

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

للمزيد من المعلومات عن معلَمات سلسلة طلب البحث وخصائص الاستجابة، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات. للحصول على معلومات حول معلَمات تقرير استخدام الكيانات، يمكنك الاطّلاع على مرجع معلَمات استخدام الكيانات.

أمثلة

يحصل المثال التالي على تقرير الكيانات الخاص بكيان gplus_community الذي يحمل entityKey "1234".

https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11

مثال على استجابة JSON في تقرير الاستخدام

تعرض الاستجابة الناجحة رمز حالة HTTP 200. وإلى جانب رمز الحالة، يتم عرض تقرير للاستجابة. تم حذف بعض المعلَمات في الرد لتسهيل قراءتها.

مثال على استجابة JSON لتقرير الكيانات

{
 "kind": "reports#usageReports",
 "nextPageToken": "NjQ1OTgwODk0MzkxNDAwNjQ0OA",
 "usageReports": [
 {
   "kind": "admin#reports#usageReport",
   "date": "2017-12-11",
   "entity": {
    "type": "OBJECT",
    "customerId": "C03az79cb",
    "objectType": "GPLUS_COMMUNITY",
    "objectId": "1234",
   },
   "parameters": [
    {
      "name": "gplus:community_name",
      "stringValue": "My Community"
    },
    {
     "name": "gplus:num_total_members",
     "intValue": 37
    },
    {
     "name": "gplus:num_7day_active_members",
     "intValue": 12
    },
    {
     "name": "gplus:num_30day_active_members",
     "intValue": 17
    },
   ]
  }
 ]
}

مثال على استجابة JSON لتقرير الكيانات الذي يتضمّن تحذيرات

وقد يظهر تحذير واحد أو أكثر في الردّ في حال تعذّر تلبية الطلب. في هذا المثال، لا يكون التقرير متاحًا في وقت تقديم الطلب.

{
 "kind": "reports#usageReports",
 "warnings": [
    {
      "code": "PARTIAL_DATA_AVAILABLE"
      "message": "Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours."
      "data": [
        {
          "key": "date"
          "value": "2017-12-11"
        }
      ]
    }
  ],
 "usageReports": [],
}

يحتوي كل إدخال في صفيف warnings على المعلَمات التالية:

• code: رمز تحذير يمكن للآلة قراءته
• message: رسالة تحذير يمكن لشخص عادي قراءتها
• data: قائمة بأزواج المفتاح/القيمة التي تقدّم معلومات تحذيرية مفصّلة