Fazer solicitações na API Google Drive Activity

Neste guia, explicamos como fazer solicitações na API Google Drive Activity usando o método activity.query.

Chave de consulta

Há duas maneiras de solicitar atividade: por item do Google Drive ou para tudo em uma hierarquia de pastas.

• itemName: o formato da chave é "items/ITEM_ID". Normalmente, esse é um arquivo no Drive. Se você especificar uma pasta para essa chave, ela mostrará a atividade da pasta, por exemplo, quando ela foi criada ou renomeada.

• ancestorName: o formato dessa chave é "items/ITEM_ID", e a resposta inclui a atividade em todos os itens na subárvore abaixo desta pasta.

Quando nenhuma chave é definida, o padrão é usar o ancestorName de "items/root" e mostra a atividade de todos os itens no Drive.

Paginação

O campo pageSize permite solicitar um número aproximado de atividades a serem retornadas em cada resposta. A contagem real de atividades retornadas varia. Por isso, seu app precisa processar quantidades arbitrárias na resposta.

O tamanho das páginas é limitado. Se o app precisar de muitas atividades, faça várias solicitações usando paginação em vez de definir um valor grande para pageSize. Especificamente, se houver mais atividades para buscar do que está incluída na resposta, ela também conterá uma nextPageToken. Para recuperar mais resultados, repita a mesma solicitação, mas adicione um campo pageToken com o valor de nextPageToken da resposta anterior.

Consolidação

Objetos Action geralmente são agrupados e retornados em um único recurso DriveActivity. Alguns agrupamentos Action ocorrem espontaneamente, como ao mover um item para uma pasta compartilhada acionando uma mudança de permissão.

Também é possível especificar um ConsolidationStrategy (às vezes chamado de agregação ou lote) na solicitação. Isso permite outros agrupamentos de objetos Action relacionados, como vários atores editando um item ou um Actor movendo vários arquivos para uma nova pasta do Drive.

Enquanto uma Action individual tem um Actor e um Target, após o agrupamento, a DriveActivity resultante pode ter vários atores e vários destinos. No entanto, mesmo após o agrupamento, sempre há uma ação "principal" que é representativa, ou a mais importante, de todas as ações no recurso DriveActivity, dependendo da estratégia de consolidação solicitada.

Como resultado, mesmo que a consolidação esteja ativada, pode ser suficiente para muitos clientes visualizarem apenas o conteúdo de nível superior de um recurso DriveActivity (como os atores e destinos coletivos na primaryActionDetail) e ignorar as ações detalhadas na resposta.

Filtros

É possível restringir as ações que podem ser retornadas no recurso DriveActivity criando uma string filter na solicitação activity.query. Há dois campos compatíveis: time e detail.action_detail_case.

Filtrar por tempo

Para restringir ações por período, especifique o nome do campo time com operadores numéricos em valores de data, unidos por um "AND" opcional. Usar milissegundos desde 1o de janeiro de 1970 ou o formato RFC 3339, como:

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

Filtrar por tipo

Para restringir por tipo de ação, aplique o nome do campo detail.action_detail_case com o operador "tem" (:). Use um valor singular ou uma lista de tipos de ação permitidos entre parênteses e separados por um espaço. Para encontrar uma lista de tipos de ação, consulte os objetos ActionDetail.

Para excluir um tipo de ação da resposta, inclua um hífen (-) no início da string de filtro.

Veja alguns exemplos de tipos de ação:

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

Combinações

Essas condições de filtragem podem ser combinadas em uma única string filter, como:

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

Exemplos de solicitação

Solicitar as 10 atividades mais recentes de um item do Drive:

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

Solicite atividades consolidadas para cada item do Drive abaixo de uma pasta ancestral:

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

Solicitar todas as ações MOVE e RENAME em um item do Drive:

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

Solicite todas as atividades desde 1o de janeiro de 2018 EST:

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

Solicitar todas as atividades, exceto as ações EDIT, durante o horário UTC de junho de 2017:

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