گزارش استفاده از نهادها، فعالیت‌های خدمات Google Workspace مربوط به نهادهای مورد استفاده توسط کاربران حساب شما را برمی‌گرداند. این گزارش ها را می توان برای اطلاعات استفاده خاص سفارشی و فیلتر کرد. داده های 30 روز گذشته در دسترس است.
گزارش استفاده از نهادها ممکن است فقط برای اهداف قانونی مطابق با توافق نامه مشتری شما استفاده شود. این گزارش‌ها برای Google Workspace و Education نیز اعمال می‌شود.
همه فعالیت‌های استفاده از موجودیت‌ها را بازیابی کنید
در حال حاضر، تنها نوع موجودی که توسط این API پشتیبانی می‌شود، انجمن‌های +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 است. توصیه می کنیم برای این کار از منطقه زمانی حساب خود استفاده کنید. برای اطلاعات بیشتر در مورد پارامترهای رشته پرس و جو و خواص پاسخ، به مرجع API مراجعه کنید. برای اطلاعات در مورد پارامترهای گزارش استفاده از نهادها، به مرجع پارامترهای استفاده از نهادها مراجعه کنید.
applicationParameters لیستی از پارامترهای جدا شده با کاما است که می خواهید بازیابی کنید. هر پارامتر به عنوان application:parameter_name ، برای مثال، gplus:community_name قالب‌بندی می‌شود. پارامترهای موجود در مرجع Entities Usage Parameters مستند شده اند. اگر هیچ پارامتری مشخص نشده باشد، همه برگردانده می شوند.
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 عضو فیلتر شده است. برای مثالی از پاسخ API، به مثال پاسخ 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
بازیابی گزارش برای یک نهاد خاص
برای بازیابی یک گزارش برای یک نهاد خاص، از درخواست GET HTTP زیر استفاده کنید و کد مجوز شرح داده شده در اسناد مجوز را اضافه کنید. برای خوانایی، مثال زیر با بازگشت خط فرمت شده است.
GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date ?parameters=applicationParameters &filters=parameterFilters &maxResults=maxResults
entityKey یک شناسه موجودیت است که مخصوص برنامه ای است که موجودیت در آن زندگی می کند. برای جزئیات نحوه به دست آوردن entityKey برای نهاد خاصی که به آن علاقه دارید، به مرجع API مراجعه کنید.
برای اطلاعات بیشتر در مورد پارامترهای رشته پرس و جو و خواص پاسخ، به مرجع API مراجعه کنید. برای اطلاعات در مورد پارامترهای گزارش استفاده از نهادها، به مرجع پارامترهای استفاده از نهادها مراجعه کنید.
مثال ها
مثال زیر گزارش موجودیت را برای یک موجودیت 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: فهرست جفت‌های کلید-مقدار که اطلاعات هشدار دقیقی را ارائه می‌دهد