Reports API: Nutzungsbericht zu Entitäten
Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Im Bericht zur Nutzung von Entitäten werden Google Workspace-Dienstaktivitäten zurückgegeben, die mit Entitäten zusammenhängen
die von den Nutzern Ihres Kontos verwendet werden. Diese Berichte können für bestimmte Anwendungsfälle angepasst und gefiltert werden.
Informationen. Es sind Daten für die letzten 30 Tage verfügbar.
Der Bericht zur Nutzung von Entitäten darf nur für rechtmäßige Zwecke in
gemäß Ihrer Kundenvereinbarung erfolgen. Diese Berichte gelten auch für
Google Workspace und Education
Alle Nutzungsaktivitäten für Entitäten abrufen
Derzeit werden nur Google+ Communitys von dieser API unterstützt. So rufen Sie eine
Bericht aller Aktivitäten im Zusammenhang mit App-Entitäten in Ihrem Konto enthalten, verwenden Sie
GET-HTTP-Anfrage senden und das Autorisierungstoken angeben, das im
Dokumentation zur Autorisierung. Für
ist das folgende Beispiel mit Zeilenumbrüchen formatiert:
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults
Der Wert date gibt das Datum an, an dem die Nutzung stattgefunden hat, und der Zeitstempel befindet sich in der
ISO 8601-Format, jjjj-mm-tt. Wir empfehlen Ihnen,
Verwenden Sie hierfür die Zeitzone Ihres Kontos. Weitere Informationen zu Abfragestringparametern und
finden Sie in der API
Referenz. Informationen zu den Parametern für den Bericht zur Entitätsnutzung finden Sie in der
Parameter für die Nutzung von Entitäten
Referenz.
applicationParameters ist eine durch Kommas getrennte Liste von Parametern, die Sie abrufen möchten.
Jeder Parameter hat das Format application:parameter_name, z. B.:
gplus:community_name. Die verfügbaren Parameter sind in der
Parameter für die Entitätsnutzung
Referenz. Wenn keine Parameter angegeben sind, werden alle zurückgegeben.
parameterFilters ist eine durch Kommas getrennte Liste von Filtern, die auf die Ergebnisse angewendet werden sollen. Jedes
Filter ist formatiert als
application:parameter_name[relational_operator]parameter_value Beispiel: Der Parameter
Filter gplus:num_total_members>100 filtert die Ergebnisse so, dass sie nur Ergebnisse enthalten
Dabei hat der Parameter gplus:num_total_members einen Wert größer als 100.
maxResults ist die maximale Anzahl der Ergebnisse, die in einem einzelnen Abruf zurückgegeben werden sollen. Wenn die Summe
Anzahl der Ergebnisse größer als dieser Wert ist, wird die Antwort abgeschnitten und
nextPageToken werden eingeschlossen (siehe
Beispiel für eine JSON-Antwort unten).
Beispiele
Im folgenden Beispiel wird ein Bericht abgerufen, der alle Parameter enthält
für alle gplus_communities-Entitäten.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11
Im folgenden Beispiel wird ein Bericht mit dem Parameter community_name abgerufen
für alle gplus_communities-Entitäten.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name
Im folgenden Beispiel wird ein Bericht von community_name und
num_total_members für jede gplus_communities-Entität, gefiltert nach
Communitys mit mehr als 100 Mitgliedern. Ein Beispiel für eine API-Antwort finden Sie in der
Beispiel für eine JSON-Antwort
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
Bericht für eine bestimmte Entität abrufen
Um einen Bericht für eine bestimmte Entität abzurufen, verwenden Sie die folgende GET-HTTP-Anfrage und
das Autorisierungstoken enthalten, das im
Dokumentation zur Autorisierung. Für
ist das folgende Beispiel
mit Zeilenumbruch formatiert.
GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults
Die entityKey ist eine Entitäts-ID, die für die Anwendung spezifisch ist, in der der
das Leben der Entität. Weitere Informationen finden Sie in der API
Weitere Informationen dazu, wie Sie die entityKey für die jeweilige Rechtspersönlichkeit erhalten, finden Sie hier:
an denen Sie interessiert sind. Die anderen Parameter sind oben unter
Alle Nutzungsaktivitäten für Entitäten abrufen
Weitere Informationen zu Abfragestringparametern und Antworteigenschaften finden Sie in der API-Referenz. Weitere Informationen
zu den Parametern des Berichts zur Entitätsnutzung finden Sie in der
Parameter für die Entitätsnutzung
Referenz.
Beispiele
Im folgenden Beispiel wird der Entitätsbericht für eine gplus_community-Entität mit folgendem Wert abgerufen:
entityKey „1234“.
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
Beispiel für eine JSON-Antwort für Nutzungsbericht
Bei einer erfolgreichen Antwort wird der Statuscode HTTP 200 zurückgegeben. Zusammen mit
der Statuscode enthält, wird ein Bericht zurückgegeben. Einige der Parameter in der Antwort wurden
zur besseren Lesbarkeit weggelassen werden.
Beispiel für eine JSON-Antwort für einen Entitätsbericht
{
"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
},
]
}
]
}
Beispiel für eine JSON-Antwort für einen Entitätsbericht mit Warnungen
Wenn die Anfrage nicht erfüllt werden kann, werden in der Antwort möglicherweise eine oder mehrere Warnungen zurückgegeben. In dieser
Beispiel: Der Bericht ist zum Zeitpunkt der Anfrage nicht verfügbar.
{
"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": [],
}
Jeder Eintrag im warnings-Array hat die folgenden Parameter:
<ph type="x-smartling-placeholder"></ph>
code: maschinenlesbarer Warncode
message: visuell lesbare Warnmeldung
data: Liste der Schlüssel/Wert-Paare, die detaillierte Warninformationen enthalten
Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.
Zuletzt aktualisiert: 2025-08-29 (UTC).
[null,null,["Zuletzt aktualisiert: 2025-08-29 (UTC)."],[],[],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"]]
