Modelo de dados da API Drive Activity

Este guia explica os principais componentes de uma resposta na API Google Drive Activity, mostrando exemplos e como interpretá-los.

Objetos

  • DriveActivity: é o recurso principal retornado por consultas à API Drive Activity. Ele descreve um ou mais atores realizando uma ou mais ações que afetam um ou mais alvos.

  • Timestamp e TimeRange: descrevem, respectivamente, um único ponto no tempo em que a atividade ocorreu ou o início e o fim em que a atividade ocorreu em um período.

  • Actor: normalmente, um Actor é um usuário final. No entanto, às vezes, um evento do sistema pode acionar um Action quando um administrador está agindo como um usuário ou como ele mesmo ou quando é realizado por uma pessoa não identificável. A mensagem Actor encapsula cada um desses casos.

  • Target: um Target é o objeto de uma atividade, como um arquivo, uma pasta, um drive compartilhado ou um comentário de arquivo. Muitos tipos de ação são compatíveis com mais de um tipo de destino. Por exemplo, embora Edit geralmente se aplique a arquivos do Drive, outras ações, como Rename e Create, também podem ser aplicadas a pastas e drives compartilhados do Drive. Os destinos que não são itens do Drive ainda podem se referir a um, como a pasta raiz de uma unidade ou o documento pai que contém um comentário de arquivo.

  • Action: cada recurso DriveActivity tem uma ou mais ações relacionadas. Um Action é independente, como um evento, porque compreende não apenas o tipo e as informações detalhadas sobre a ação, mas também um Actor, um Target e um Timestamp ou TimeRange. Para evitar redundância, um Action não preenche os próprios campos Target, Actor ou de tempo quando eles são iguais ao DriveActivity geral.

  • ActionDetail: é o tipo específico e informações detalhadas sobre um Action. Por exemplo, um detalhe de ação Move tem um local de origem e destino, e um PermissionChange especifica quem pode acessar um documento e com quais privilégios.

Exemplos de respostas

Confira os exemplos de respostas a seguir.

Um usuário editou um arquivo no Drive

Um recurso DriveActivity pode incluir apenas uma ação, como um usuário editando um arquivo.

"activities":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[ { "driveItem":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } } ],
  "timestamp":{ "seconds":"1536794657", "nanos":791000000 },
  "actions":[ { "detail":{ "edit":{} } } ]
}]

Esta saída inclui os seguintes valores:

  • ACCOUNT_ID: o ID do usuário. Ele pode ser usado com a API People para ter mais informações.
  • ITEM_ID: o ID do item do Drive.
  • TITLE: o título do item do Drive.

O objeto Action nesta resposta não inclui Actor, Target ou timestamp porque eles são iguais ao DriveActivity geral.

Dois usuários editaram o mesmo arquivo em horários semelhantes

Quando um ConsolidationStrategy é usado, as ações relacionadas são agrupadas em um DriveActivity combinado. Nesse exemplo, duas ações semelhantes são agrupadas: um tipo de ação Edit de dois usuários diferentes.

"activities":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } }
  ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
  ],
  "timeRange":{
    "startTime":{ "seconds":"1541089823", "nanos":712000000 },
    "endTime":{ "seconds":"1541089830", "nanos":830000000 }
  },
  "actions":[
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
      "timestamp":{ "seconds":"1541089830", "nanos":830000000 }
    },
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } },
      "timestamp":{ "seconds":"1541089823", "nanos":712000000 }
    }
  ]
}]

Esta saída inclui os seguintes valores:

  • ACCOUNT_ID_1: o ID do primeiro usuário. Ele pode ser usado com a API People para ter mais informações.
  • ACCOUNT_ID_2: o ID do segundo usuário.
  • ITEM_ID: o ID do item do Drive.
  • TITLE: o título do item do Drive.

O objeto Action nesta resposta não inclui Target porque ele é igual ao DriveActivity geral.

O exemplo também ilustra como os apps podem usar apenas as informações resumidas em DriveActivity, sem analisar as ações individuais. A resposta indica que dois usuários editaram um determinado arquivo em um período.

Um usuário moveu dois arquivos para um novo diretório

Neste exemplo, o ConsolidationStrategy agrupou duas ações Move relacionadas porque os arquivos foram movidos da mesma origem para o mesmo destino ao mesmo tempo.

"activities":[{
  "primaryActionDetail":{
    "move":{
      "addedParents":[ { ... } ]
      "removedParents":[ { ... } ]
    }
  },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
    { "driveItem":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
  ],
  "timestamp":{ "seconds":"1541090960", "nanos":985000000 },
  "actions":[
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
    },
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
    }
  ]
}]

Esta saída inclui os seguintes valores:

  • ACCOUNT_ID: o ID do usuário. Ele pode ser usado com a API People para ter mais informações.
  • ITEM_ID_1: o ID do primeiro item do Drive.
  • ITEM_ID_2: o ID do segundo item do Drive.
  • TITLE_1: o título do primeiro item do Drive.
  • TITLE_2: o título do segundo item do Drive.

O objeto Action nesta resposta não inclui Actor ou timestamp porque eles são iguais ao DriveActivity geral.