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: قائمة بأزواج المفتاح/القيمة التي تقدّم معلومات تفصيلية عن التحذير