實體使用情形報表會傳回與帳戶使用者所用實體相關的 Google Workspace 服務活動。您可以針對特定使用資訊自訂及篩選這些報表。系統目前提供過去 30 天內的資料。
實體使用情形報表只能依《客戶協議》的合法用途使用。這些報告也適用於 Google Workspace 和 Google Workspace for 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。如要瞭解可用的參數，請參閱實體使用參數參考資料。如未指定參數，系統會傳回所有參數。
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
以下範例產生的報表包含所有 gplus_communities 實體的 community_name 參數。
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all /dates/2017-12-11?parameters=gplus:community_name
以下範例會根據成員超過 100 名的社群，取得每個 gplus_communities 實體的 community_name 和 num_total_members 報表。如需 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 是實體 ID，專屬於實體所在的應用程式。請參閱 API 參考資料，進一步瞭解如何取得特定實體的 entityKey。其他參數請參閱上方的「 擷取所有實體使用活動」一節。
如要進一步瞭解查詢字串參數和回應屬性，請參閱 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：提供詳細警告資訊的鍵/值組合清單