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 attività: per elemento di Google Drive o per tutto ciò che si trova 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, verrà visualizzata l'attività relativa alla cartella, ad esempio quando è stata creata o rinominata.

  • ancestorName: il formato di questa chiave è "items/ITEM_ID" e la risposta include 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 mostrata l'attività per tutti gli elementi nel tuo Drive.

Impaginazione

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

Le dimensioni della pagina sono limitate. Se la tua app ha bisogno di molte attività, effettua più richieste utilizzando l'impaginazione, anziché impostare un valore elevato per pageSize. In particolare, se potrebbero esserci più attività da recuperare rispetto a quelle incluse nella risposta, la risposta conterrà anche un valore nextPageToken. Per recuperare altri 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 attiva una modifica dell'autorizzazione.

Puoi anche specificare un elemento ConsolidationStrategy (a volte chiamato aggregazione o raggruppamento) nella richiesta. In questo modo vengono attivati altri raggruppamenti di oggetti Action correlati, ad esempio più attori che modificano un elemento o un solo elemento Actor che sposta più file in una nuova cartella di Drive.

Mentre un singolo Action ha un Actor e un'Target, dopo il raggruppamento, il risultante DriveActivity può avere più attori e più target. Tuttavia, anche dopo il raggruppamento, è sempre presente 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, potrebbe essere sufficiente che molti client visualizzino solo i contenuti di primo livello di una risorsa DriveActivity (come gli attori e i target collettivi all'interno di primaryActionDetail) e ignorino le azioni dettagliate nella risposta.

Filtri

Puoi limitare le azioni che potrebbero essere restituite nella risorsa DriveActivity costruendo una stringa filter nella richiesta activity.query. Sono supportati due campi: 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 utilizzando operatori numerici per i valori delle date, 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 "has" (:). Utilizza un valore singolare o un elenco di tipi di azioni consentiti racchiusi tra parentesi e separati da uno spazio. Per trovare un elenco dei tipi di azione, esamina gli oggetti ActionDetail.

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

Ecco alcuni esempi di tipi 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 in una cartella dei predecessori:

{
  "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à a partire dal 1° gennaio 2018 EST:

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

Richiedi tutte le attività, tranne le 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"
}