API Reports: report Utilizzo entità
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Il report sull'utilizzo delle entità restituisce le attività del servizio Google Workspace relative alle entità
utilizzati dagli utenti del tuo account. Questi report possono essere personalizzati e filtrati per utilizzo specifico
informazioni. I dati sono disponibili per gli ultimi 30 giorni.
Il report sull'utilizzo delle entità può essere usato solo per scopi legittimi in
in conformità con il Contratto con il cliente. Questi report si applicano anche
Google Workspace ed Education.
Recupera le attività di utilizzo di tutte le entità
Attualmente, l'unico tipo di entità supportato da questa API sono le community Google+. Per recuperare un
di tutte le attività relative alle entità dell'app nel tuo account, usa quanto segue
GET Richiesta HTTP e includi il token di autorizzazione descritto nell'
documentazione sull'autorizzazione. Per
la leggibilità, l'esempio seguente è formattato con i ritorni a capo:
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults
Il valore date è la data in cui si è verificato l'utilizzo e il timestamp si trova nella
Formato ISO 8601, aaaa-mm-gg. Ti consigliamo
utilizza il fuso orario del tuo account. Per ulteriori informazioni sui parametri della stringa di query e
proprietà della risposta, consulta le
Riferimento. Per informazioni sui parametri dei report sull'utilizzo delle entità, consulta
Parametri di utilizzo delle entità
riferimento.
applicationParameters è un elenco di parametri separati da virgole che vuoi recuperare.
Ogni parametro ha il formato application:parameter_name, ad esempio
gplus:community_name. I parametri disponibili sono documentati in
Parametri di utilizzo delle entità
riferimento. Se non viene specificato nessun parametro, vengono restituiti tutti i parametri.
parameterFilters è un elenco di filtri separati da virgole da applicare ai risultati. Ciascuna
il filtro è formattato come
application:parameter_name[relational_operator]parameter_value. Ad esempio,
filtro gplus:num_total_members>100 filtra i risultati in modo che contengano solo risultati
in cui il parametro gplus:num_total_members ha un valore maggiore di 100.
maxResults è il numero massimo di risultati da restituire in un singolo recupero. Se il totale
di risultati è maggiore di questo valore, la risposta verrà troncata
Verranno inclusi nextPageToken (vedi il
esempio di risposta JSON di seguito).
Esempi
L'esempio seguente restituisce un report contenente tutti i parametri
per tutte le entità gplus_communities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11
L'esempio seguente restituisce un report contenente il parametro community_name
per tutte le entità gplus_communities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name
L'esempio seguente restituisce un report di community_name
num_total_members per ogni entità gplus_communities, filtrato in base a
community con più di 100 membri. Per un esempio di risposta dell'API, consulta
Esempio di risposta 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
Recuperare un report per un'entità specifica
Per recuperare un report per un'entità specifica, utilizza la seguente richiesta HTTP GET e
includere il token di autorizzazione descritto
documentazione sull'autorizzazione. Per
la leggibilità, l'esempio seguente è formattato con i ritorni a riga di comando.
GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults
entityKey è un identificatore di entità specifico per l'applicazione in cui
la vita dell'entità. Consulta l'API
Riferimento per i dettagli su come ottenere il entityKey per l'entità specifica che
a cui sono interessati. Gli altri parametri sono indicati sopra in
Recupera tutte le attività di utilizzo delle entità.
Per ulteriori informazioni sui parametri della stringa di query e sulle proprietà della risposta, consulta Riferimento API. Per informazioni
sui parametri dei report sull'utilizzo delle entità, consulta
Parametri di utilizzo delle entità
riferimento.
Esempi
L'esempio seguente restituisce il report sulle entità per un'entità gplus_community con
entityKey "1234".
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
Esempio di risposta JSON per il report sull'utilizzo
Una risposta corretta restituisce un codice di stato HTTP 200. Insieme a
il codice di stato, la risposta restituisce un report. Alcuni dei parametri della risposta sono stati
omessi per migliorare la leggibilità.
Esempio di risposta JSON per il report sulle entità
{
"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
},
]
}
]
}
Esempio di risposta JSON per il report sulle entità con avvisi
Se la richiesta non può essere soddisfatta, è possibile che nella risposta vengano restituiti uno o più avvisi. In questo
Ad esempio, il report non è disponibile nel momento in cui viene effettuata la richiesta.
{
"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": [],
}
Ogni voce nell'array warnings ha i seguenti parametri:
code: codice di avviso leggibile dal computer
message: messaggio di avviso leggibile
data: elenco di coppie chiave/valore che forniscono informazioni di avviso dettagliate
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2025-08-29 UTC.
[null,null,["Ultimo aggiornamento 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"]]
