Fazer solicitações na API Google Drive Activity

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

Chave de consulta

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

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

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

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

Paginação

O campo pageSize permite solicitar um número aproximado de atividades para retornar em cada resposta. A contagem real de atividades retornadas vai variar. Portanto, seu app precisa processar quantidades arbitrárias na resposta.

Os tamanhos de página são limitados. Se o app precisar de muitas atividades, faça várias solicitações usando a paginação em vez de definir um valor grande para pageSize. Especificamente, se houver mais atividades a serem buscadas do que as incluídas na resposta, ela também conterá um 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

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

Também é possível especificar um ConsolidationStrategy (às vezes chamado de agregação ou agrupamento) 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 "primária" que é representativa ou a mais importante de todas as ações no recurso DriveActivity, dependendo da estratégia de consolidação solicitada.

Como resultado, independentemente de a consolidação estar ativada ou não, 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 no 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 aceitos: 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. Use milissegundos desde 1º 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 de campo detail.action_detail_case com o operador "has" (:). Use um valor singular ou uma lista de tipos de ação permitidos, ambos 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, adicione um hífen (-) ao início da string de filtro.

Confira 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

Solicite 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": {}
  }
}

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

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

Solicitar todas as atividades desde 1º de janeiro de 2018 (horário de verão):

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

Solicitar todas as atividades, exceto ações EDIT, durante junho de 2017 (UTC):

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