Reports API: تقرير استخدام الكيانات
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يعرض تقرير استخدام الكيانات أنشطة خدمة Google Workspace المتعلّقة بالكيانات.
التي يستخدمها مستخدمو حسابك. يمكن تخصيص هذه التقارير وفلترتها حسب استخدام معيّن.
المعلومات. البيانات متاحة لآخر 30 يومًا.
لا يجوز استخدام تقرير استخدام الكيانات إلا لأغراض قانونية في
بما يتوافق مع اتفاقية العملاء. تنطبق هذه التقارير أيضًا على
Google Workspace وEducation
استرداد جميع أنشطة استخدام الكيانات
في الوقت الحالي، نوع الكيان الوحيد المتوافق مع واجهة برمجة التطبيقات هذه هو منتديات +Google. لاسترداد
تقرير بجميع الأنشطة المتعلقة بعناصر التطبيقات في حسابك، استخدِم ما يلي:
GET طلب HTTP وتضمين الرمز المميز للتفويض الموضح في
مستندات التفويض بالنسبة
سهولة القراءة، يتم تنسيق المثال التالي باستخدام إرجاع الأسطر:
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: قائمة بأزواج المفتاح/القيمة التي تقدّم معلومات تحذيرية مفصّلة
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Reports API: Entities Usage Report\n\nThe entities usage report returns Google Workspace service activities related to entities\nused by your account's users. These reports can be customized and filtered for specific usage\ninformation. Data is available for the past 30 days.\n\nThe entities usage report may be used only for lawful purposes in\naccordance with your Customer Agreement. These reports also apply to\nGoogle Workspace and Education.\n\nRetrieve all entities usage activities\n--------------------------------------\n\nCurrently, the only entity type supported by this API is Google+ communities. To retrieve a\nreport of all activities related to app entities in your account, use the following\n`GET` HTTP request and include the authorization token described in the\n[authorization documentation](/workspace/admin/reports/v1/guides/authorizing). For\nreadability, the following example is formatted with line returns: \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date\n?parameters=applicationParameters\n&filters=parameterFilters\n&maxResults=maxResults\n```\n\nThe \u003cvar translate=\"no\"\u003edate\u003c/var\u003e value is the date the usage occurred and the timestamp is in the\n[ISO 8601 format](http://en.wikipedia.org/wiki/ISO_8601), yyyy-mm-dd. We recommend you\nuse your account's time zone for this. For more information about the query string parameters and\nresponse properties, see the [API\nReference](/workspace/admin/reports/v1/reference/entityUsageReports/get). For information about the entities usage report parameters, see the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/entities).\n\n\u003cvar translate=\"no\"\u003eapplicationParameters\u003c/var\u003e is a comma-separated list of parameters you wish to retrieve.\nEach parameter is formatted as `application:parameter_name`, for example,\n`gplus:community_name`. The available parameters are documented in the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/entities). If no parameters are specified, all are returned.\n\n\u003cvar translate=\"no\"\u003eparameterFilters\u003c/var\u003e is a comma-separated list of filters to apply to the results. Each\nfilter is formatted as\n`application:parameter_name[relational_operator]parameter_value`. For example, the\nfilter `gplus:num_total_members\u003e100` filters the results to contain only results\nwhere the `gplus:num_total_members` parameter has a value greater than 100.\n\n\u003cvar translate=\"no\"\u003emaxResults\u003c/var\u003e is the maximum number of results to return in a single fetch. If the total\nnumber of results is greater than this, the response will be truncated and a\n`nextPageToken` will be included (see the\n[JSON response example](#example_response) below).\n\n### Examples\n\nThe following example gets a report containing all parameters\nfor all `gplus_communities` entities. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all\n/dates/2017-12-11\n```\n\nThe following example gets a report containing the `community_name` parameter\nfor all `gplus_communities` entities. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all\n/dates/2017-12-11?parameters=gplus:community_name\n```\n\nThe following example gets a report of `community_name` and\n`num_total_members` for each `gplus_communities` entity, filtered by\ncommunities with more than 100 members. For an example of an API response, see the\n[JSON response example](#example_response). \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11\n?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members\u003e100\n```\n\nRetrieve a report for a specific entity\n---------------------------------------\n\nTo retrieve a report for a specific entity, use the following `GET` HTTP request and\ninclude the authorization token described in the\n[authorization documentation](/workspace/admin/reports/v1/guides/authorizing). For\nreadability, the following example is formatted with line returns. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date\n?parameters=applicationParameters\n&filters=parameterFilters\n&maxResults=maxResults\n```\n\nThe \u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e is an entity identifier which is specific to the application where the\nentity lives. See the [API\nReference](/workspace/admin/reports/v1/reference/userUsageReport/get) for details on how to obtain the \u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e for the particular entity you\nare interested in. The other parameters are documented above under\n[Retrieve all entities usage activities](#get_all_entities_usage).\n\nFor more information about the query string parameters and response properties, see the [API Reference](/workspace/admin/reports/v1/reference/userUsageReport/get). For information\nabout the entities usage report parameters, see the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/users).\n\n### Examples\n\nThe following example gets the entity report for a `gplus_community` entity with the\n\u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e \"1234\". \n\n```\nhttps://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11\n```\n\nUsage report example JSON response\n----------------------------------\n\nA successful response returns an [HTTP 200 status code](http://wikipedia.org/wiki/List_of_HTTP_status_codes). Along with\nthe status code, the response returns a report. Some of the parameters in the response have been\nomitted for readability.\n\n#### Example JSON response for entities report\n\n```carbon\n{\n \"kind\": \"reports#usageReports\",\n \"nextPageToken\": \"NjQ1OTgwODk0MzkxNDAwNjQ0OA\",\n \"usageReports\": [\n {\n \"kind\": \"admin#reports#usageReport\",\n \"date\": \"2017-12-11\",\n \"entity\": {\n \"type\": \"OBJECT\",\n \"customerId\": \"C03az79cb\",\n \"objectType\": \"GPLUS_COMMUNITY\",\n \"objectId\": \"1234\",\n },\n \"parameters\": [\n {\n \"name\": \"gplus:community_name\",\n \"stringValue\": \"My Community\"\n },\n {\n \"name\": \"gplus:num_total_members\",\n \"intValue\": 37\n },\n {\n \"name\": \"gplus:num_7day_active_members\",\n \"intValue\": 12\n },\n {\n \"name\": \"gplus:num_30day_active_members\",\n \"intValue\": 17\n },\n ]\n }\n ]\n}\n```\n\n#### Example JSON response for entities report with warnings\n\nOne or more warnings may be returned in the response if the request cannot be fulfilled. In this example, the report is not available at the time the request is made. \n\n```scdoc\n{\n \"kind\": \"reports#usageReports\",\n \"warnings\": [\n {\n \"code\": \"PARTIAL_DATA_AVAILABLE\"\n \"message\": \"Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours.\"\n \"data\": [\n {\n \"key\": \"date\"\n \"value\": \"2017-12-11\"\n }\n ]\n }\n ],\n \"usageReports\": [],\n}\n```\nEach entry in the `warnings` array has the following parameters:\n\n- `code`: machine-readable warning code\n- `message`: human-readable warning message\n- `data`: list of key-value pairs which give detailed warning information"]]
