Modelo de datos de la API de actividad de Drive

En esta guía, se explican los componentes principales de una respuesta en la API de actividad de Google Drive, se muestran ejemplos y cómo interpretarlos.

Objetos

• DriveActivity: Este es el recurso principal que muestran las consultas a la API de Drive Activity. Se describe uno o más actores que realizan una o más acciones que afectan a uno o más objetivos.

• Timestamp y TimeRange: Describen, respectivamente, un momento individual en el que ocurrió la actividad, o el inicio y el final de cuando la actividad ocurrió durante un período.

• Actor: Por lo general, un Actor es un usuario final. Sin embargo, a veces, un evento del sistema puede activar una Action cuando un administrador actúa como usuario o como él mismo, o cuando lo realiza una persona no identificable. El mensaje Actor encapsula cada uno de estos casos.

• Target: Un Target es el objeto de una actividad, como un archivo, una carpeta, una unidad compartida o un comentario de archivo. Ten en cuenta que muchos tipos de acciones admiten más de un tipo de objetivo. Por ejemplo, aunque Edit generalmente se aplica a los archivos de Drive, otras acciones como Rename y Create también se pueden aplicar a las carpetas y unidades compartidas de Drive. Los destinos que no son elementos de Drive pueden hacer referencia a uno solo, como la carpeta raíz de una unidad o el documento superior que contiene un comentario de archivo.

• Action: Cada recurso DriveActivity tiene una o más acciones relacionadas. Un Action es independiente, al igual que un evento, en el sentido de que comprende no solo el tipo y la información detallados sobre la acción, sino también un Actor, un Target y un Timestamp o TimeRange. Para evitar redundancias, una Action no propaga sus propios campos de Target, Actor o de hora cuando estos son los mismos que los del DriveActivity general.

• ActionDetail: Es el tipo específico y la información detallada sobre un Action. Por ejemplo, un detalle de la acción Move tiene una ubicación de origen y de destino, y una PermissionChange especifica quién ahora puede acceder a un documento y con qué privilegios.

Respuestas de ejemplo

Un usuario editó un archivo en Drive:

Un recurso DriveActivity simple puede incluir solo una acción, como que un usuario edite un archivo.

"activities":[{
  "primary_action_detail":{ "edit":{} },
  "actors":[ { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID" } } } ],
  "targets":[ { "drive_item":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } } ],
  "timestamp":{ "seconds":"1536794657", "nanos":791000000 },
  "actions":[ { "detail":{ "edit":{} } } ]
}]

En esta salida, se incluyen los siguientes valores:

• ACCOUNT_ID: Es el ID del usuario. Se puede usar con la API de Personas para obtener más información.
• ITEM_ID: Es el ID del elemento de Drive.
• TITLE: Es el título del elemento de Drive.

Ten en cuenta que el Action en esta respuesta no incluye el Actor, el Target ni el TimeStamp porque son los mismos que los DriveActivity en general.

Dos usuarios editaron el mismo archivo en momentos similares:

Cuando la consolidación está activada, las acciones relacionadas se agrupan en un DriveActivity. En este ejemplo, se agrupan 2 acciones similares: un tipo de acción Edit de 2 usuarios diferentes.

"activities":[{
  "primary_action_detail":{ "edit":{} },
  "actors":[
    { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_1" } } },
    { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_2" } } }
  ],
  "targets":[
    { "drive_item":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
  ],
  "time_range":{
    "start_time":{ "seconds":"1541089823", "nanos":712000000 },
    "end_time":{ "seconds":"1541089830", "nanos":830000000 }
  },
  "actions":[
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_1" } } },
      "timestamp":{ "seconds":"1541089830", "nanos":830000000 }
    },
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_2" } } },
      "timestamp":{ "seconds":"1541089823", "nanos":712000000 }
    }
  ]
}]

En esta salida, se incluyen los siguientes valores:

• ACCOUNT_ID_1: Es el ID del primer usuario. Se puede usar con la API de People para obtener más información.
• ACCOUNT_ID_2: Es el ID del segundo usuario.
• ITEM_ID: Es el ID del elemento de Drive.
• TITLE: Es el título del elemento de Drive.

Ten en cuenta que las acciones de esta respuesta no incluyen el Target, ya que es lo mismo que el DriveActivity general.

En el ejemplo, también se ilustra cómo las apps podrían usar solo la información de resumen en DriveActivity, sin mirar las acciones individuales. La respuesta indica que 2 usuarios editaron un archivo determinado durante un período.

Un usuario movió 2 archivos a un directorio nuevo:

En este ejemplo, la estrategia de consolidación agrupó 2 acciones Move relacionadas porque los archivos se trasladaron de la misma fuente al mismo destino al mismo tiempo.

"activities":[{
  "primary_action_detail":{
    "move":{
      "added_parents":[ { ... } ]
      "removed_parents":[ { ... } ]
    }
  },
  "actors":[ { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID" } } } ],
  "targets":[
    { "drive_item":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
    { "drive_item":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
  ],
  "timestamp":{ "seconds":"1541090960", "nanos":985000000 },
  "actions":[
    {
      "detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
      "target":{ "drive_item":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
    },
    {
      "detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
      "target":{ "drive_item":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
    }
  ]
}]

En esta salida, se incluyen los siguientes valores:

• ACCOUNT_ID: Es el ID del usuario. Se puede usar con la API de Personas para obtener más información.
• ITEM_ID_1: Es el ID del primer elemento de Drive.
• ITEM_ID_2: Es el ID del segundo elemento de Drive.
• TITLE_1: Es el título del primer elemento de Drive.
• TITLE_2: Es el título del segundo elemento de Drive.

Ten en cuenta que las acciones en esta respuesta no incluyen Actor ni TimeStamp porque son las mismas que las DriveActivity en general.