Effettuare richieste nell'API Google Drive Activity

Questa guida spiega come effettuare richieste nell'API Google Drive Activity utilizzando il metodo activity.query.

Chiave query

Esistono due modi per richiedere l'attività: per elemento di Google Drive o per tutto al di sotto di una gerarchia di cartelle.

• itemName: il formato di questa chiave è "items/ITEM_ID". In genere si tratta di un file su Drive. Se specifichi una cartella per questa chiave, vengono mostrate le attività per la cartella, ad esempio quando è stata creata o rinominata.

• ancestorName: il formato di questa chiave è "items/ITEM_ID" e la risposta include l'attività su tutti gli elementi del sottoalbero sotto questa cartella.

Se non è impostata alcuna chiave, per impostazione predefinita viene utilizzato il ancestorName di "items/root" e viene visualizzata l'attività per tutti gli elementi di Drive.

Impaginazione

Il campo pageSize consente di richiedere un numero approssimativo di attività da restituire in ogni risposta. Il conteggio effettivo delle attività restituite varia, quindi la tua app deve gestire quantità arbitrarie nella risposta.

Le dimensioni delle pagine sono limitate. Se la tua app richiede molte attività, effettua più richieste utilizzando l'impaginazione anziché impostare un valore elevato per pageSize. Nello specifico, se potrebbe esserci più attività da recuperare rispetto a quanto incluso nella risposta, la risposta conterrà anche un nextPageToken. Per recuperare più risultati, ripeti la stessa richiesta, ma aggiungi un campo pageToken con il valore nextPageToken della risposta precedente.

Consolidamento

Gli oggetti Action vengono spesso raggruppati e restituiti all'interno di una singola risorsa DriveActivity. Alcuni raggruppamenti Action si verificano spontaneamente, ad esempio lo spostamento di un elemento in una cartella condivisa che attiva una modifica delle autorizzazioni.

Nella richiesta puoi anche specificare un ConsolidationStrategy (a volte chiamato aggregazione o raggruppamento). In questo modo, è possibile creare altri raggruppamenti di oggetti Action correlati, ad esempio più utenti che modificano un elemento o un Actor che sposta più file in una nuova cartella di Drive.

Un singolo Action ha un Actor e un Target, ma dopo il raggruppamento, il DriveActivity risultante può avere più attori e più target. Tuttavia, anche dopo il raggruppamento, esiste sempre un'azione "principale" che è rappresentativa o la più importante di tutte le azioni nella risorsa DriveActivity, a seconda della strategia di consolidamento richiesta.

Di conseguenza, indipendentemente dal fatto che il consolidamento sia attivo o meno, per molti clienti potrebbe essere sufficiente visualizzare solo i contenuti di primo livello di una risorsa DriveActivity (ad esempio gli attori e i target collettivi all'interno del primaryActionDetail) e ignorare le azioni dettagliate nella risposta.

Filtri

Puoi limitare le azioni che potrebbero essere restituite nella risorsa DriveActivity construendo una stringa filter nella richiesta activity.query. Esistono due campi supportati: time e detail.action_detail_case.

Filtra per ora

Per limitare le azioni in base all'intervallo di tempo, specifica il nome del campo time con operatori numerici per i valori di data, uniti da un "AND" facoltativo. Utilizza i millisecondi dal 1° gennaio 1970 o il formato RFC 3339, ad esempio:

• time > 1452409200000 AND time <= 1492812924310
• time >= "2016-01-10T01:02:03-05:00"

Filtra per tipo

Per limitare in base al tipo di azione, applica il nome del campo detail.action_detail_case con l'operatore "ha" (:). Utilizza un valore singolare o un elenco di tipi di azioni consentiti racchiusi tra parentesi, separati da uno spazio. Per trovare un elenco di tipi di azioni, esamina gli oggetti ActionDetail.

Per escludere un tipo di azione dalla risposta, premetti un trattino (-) all'inizio della stringa del filtro.

Ecco alcuni esempi di tipo di azione:

• detail.action_detail_case:RENAME
• detail.action_detail_case:(CREATE RESTORE)
• -detail.action_detail_case:MOVE

Combinazioni

Queste condizioni di filtro possono essere combinate all'interno di una singola stringa filter, ad esempio:

• detail.action_detail_case:(CREATE EDIT RESTORE) time > 1452409200000

Richieste di esempio

Richiedi le 10 attività più recenti per un elemento di Drive:

{
  "itemName": "items/ITEM_ID",
  "pageSize": 10
}

Richiedi attività consolidate per ogni elemento di Drive sotto una cartella principale:

{
  "ancestorName": "items/ITEM_ID",
  "consolidationStrategy": {
    "legacy": {}
  }
}

Richiedi tutte le azioni MOVE e RENAME su un elemento di Drive:

{
  "itemName": "items/ITEM_ID",
  "filter": "detail.action_detail_case:(MOVE RENAME)"
}

Richiedi tutte le attività dal 1° gennaio 2018 EST:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-01-01T00:00:00-05:00\""
}

Richiedi tutte le attività, ad eccezione delle azioni EDIT, durante il mese di giugno 2017 UTC:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-06-01T00:00:00Z\" time < \"2018-07-01T00:00:00Z\" -detail.action_detail_case:EDIT"
}