API Reports: report Utilizzo entità

Il report sull'utilizzo delle entità restituisce le attività dei servizi Google Workspace correlate alle entità utilizzate dagli utenti dell'account. Questi report possono essere personalizzati e filtrati per informazioni sull'utilizzo specifiche. I dati sono disponibili per gli ultimi 30 giorni.

Il report sull'utilizzo delle entità può essere utilizzato solo per scopi leciti in conformità al Contratto con il cliente. Questi report si applicano anche a Google Workspace ed Education.

Recuperare tutte le attività di utilizzo delle entità

L'unico tipo di entità supportato da questa API sono le community di Google+. Per recuperare un report di tutte le attività correlate alle entità delle app nel tuo account, utilizza la seguente GET richiesta HTTP e includi il token di autorizzazione descritto nella documentazione sull'autorizzazione. Per una maggiore leggibilità, l'esempio seguente è formattato con 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 è nel formato ISO 8601, AAAA-MM-GG. Ti consigliamo di utilizzare il fuso orario del tuo account per questo. Per ulteriori informazioni sui parametri della stringa di query e sulle proprietà della risposta, consulta il Riferimento API. Per informazioni sui parametri del report sull'utilizzo delle entità, consulta il riferimento Parametri di utilizzo delle entità.

applicationParameters è un elenco di parametri separati da virgole che vuoi recuperare. Ogni parametro è formattato come application:parameter_name, ad esempio gplus:community_name. I parametri disponibili sono documentati nel riferimento Parametri di utilizzo delle entità. Se non vengono specificati parametri, vengono restituiti tutti.

parameterFilters è un elenco separato da virgole di filtri da applicare ai risultati. Ogni filtro è formattato come application:parameter_name[relational_operator]parameter_value. Ad esempio, il filtro gplus:num_total_members>100 filtra i risultati in modo che contengano solo i 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 numero totale di risultati è maggiore di questo, la risposta verrà troncata e verrà incluso un nextPageToken (vedi l'esempio di risposta JSON di seguito).

Esempi

L'esempio seguente recupera 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 recupera un report contenente il community_name parametro per tutte le gplus_communities entità.

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name

L'esempio seguente recupera un report di community_name e num_total_members per ogni entità gplus_communities, filtrato in base alle community con più di 100 membri. Per un esempio di risposta dell'API, consulta l' 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 GET richiesta HTTP e includi il token di autorizzazione descritto nella documentazione sull'autorizzazione. Per una maggiore leggibilità, l'esempio seguente è formattato con ritorni a capo.

GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults

Il entityKey è un identificatore di entità specifico per l'applicazione in cui risiede l'entità. Consulta il Riferimento API per i dettagli su come ottenere il entityKey per l'entità specifica di cui ti interessa. Gli altri parametri sono documentati in precedenza nella sezione Recuperare tutte le attività di utilizzo delle entità.

Per ulteriori informazioni sui parametri della stringa di query e sulle proprietà della risposta, consulta il Riferimento API. Per informazioni sui parametri del report sull'utilizzo delle entità, consulta il riferimento Parametri di utilizzo delle entità.

Esempi

L'esempio seguente recupera il report sull'entità per un'entità gplus_community con il entityKey "1234".

https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11

Esempio di risposta JSON del report sull'utilizzo

Una risposta riuscita restituisce un codice di stato HTTP 200. Oltre al codice di stato, la risposta restituisce un report. Alcuni dei parametri nella risposta sono stati omessi per una maggiore 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

Nella risposta possono essere restituiti uno o più avvisi se la richiesta non può essere soddisfatta. In questo esempio, il report non è disponibile al momento della 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 dalla macchina
  • message: messaggio di avviso leggibile da una persona
  • data: elenco di coppie chiave-valore che forniscono informazioni dettagliate sull'avviso