API de informes: Informe de uso de entidades

El informe de uso de entidades muestra las actividades del servicio de Google Workspace relacionadas con las entidades que usan los usuarios de tu cuenta. Estos informes se pueden personalizar y filtrar para obtener información de uso específica. Los datos están disponibles para los últimos 30 días.

El informe de uso de entidades solo se puede utilizar para fines lícitos de conformidad con el Acuerdo del Cliente. Estos informes también se aplican a Google Workspace y Education.

Recupera todas las actividades de uso de entidades

El único tipo de entidad que admite esta API son las comunidades de Google+. Para recuperar un informe de todas las actividades relacionadas con las entidades de la app en tu cuenta, usa la siguiente solicitud HTTP GET e incluye el token de autorización que se describe en la documentación de autorización. Para facilitar la lectura, el siguiente ejemplo tiene saltos de línea:

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults

El valor de date es la fecha en que se produjo el uso, y la marca de tiempo está en formato ISO 8601, aaaa-mm-dd. Te recomendamos que uses la zona horaria de tu cuenta. Para obtener más información sobre los parámetros de la cadena de consulta y las propiedades de respuesta, consulta la Referencia de la API. Para obtener información sobre los parámetros del informe de uso de entidades, consulta la referencia de los parámetros de uso de entidades.

applicationParameters es una lista de parámetros separados por comas que deseas recuperar. Cada parámetro tiene el formato application:parameter_name, por ejemplo, gplus:community_name. Los parámetros disponibles se documentan en la referencia de los parámetros de uso de entidades. Si no se especifican parámetros, se devuelven todos.

parameterFilters es una lista de filtros separados por comas que se aplicarán a los resultados. Cada filtro tiene el formato application:parameter_name[relational_operator]parameter_value. Por ejemplo, el filtro gplus:num_total_members>100 filtra los resultados para que solo contengan aquellos en los que el parámetro gplus:num_total_members tiene un valor superior a 100.

maxResults es la cantidad máxima de resultados que se devolverán en una sola recuperación. Si la cantidad total de resultados es mayor que este valor, la respuesta se truncará y se incluirá un nextPageToken (consulta el ejemplo de respuesta JSON a continuación).

Ejemplos

En el siguiente ejemplo, se obtiene un informe que contiene todos los parámetros de todas las entidades gplus_communities.

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11

En el siguiente ejemplo, se obtiene un informe que contiene el parámetro community_name para todas las entidades gplus_communities.

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name

En el siguiente ejemplo, se obtiene un informe de community_name y num_total_members para cada entidad gplus_communities, filtrado por comunidades con más de 100 miembros. Para ver un ejemplo de respuesta de la API, consulta el ejemplo de respuesta JSON.

GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11
?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members>100

Recupera un informe para una entidad específica

Para recuperar un informe de una entidad específica, utiliza la siguiente solicitud HTTP GET e incluye el token de autorización que se describe en la documentación de autorización. Para facilitar la lectura, el siguiente ejemplo tiene saltos de línea.

GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults

entityKey es un identificador de entidad específico de la aplicación en la que reside la entidad. Consulta la Referencia de la API para obtener detalles sobre cómo obtener el entityKey de la entidad específica que te interesa. Los demás parámetros se documentaron anteriormente en la sección Cómo recuperar todas las actividades de uso de entidades.

Para obtener más información sobre los parámetros de cadena de consulta y las propiedades de respuesta, consulta la Referencia de la API. Para obtener información sobre los parámetros del informe de uso de entidades, consulta la referencia de los parámetros de uso de entidades.

Ejemplos

En el siguiente ejemplo, se obtiene el informe de la entidad para una entidad gplus_community con el entityKey "1234".

https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11

Ejemplo de respuesta JSON del informe de uso

Una respuesta correcta devuelve un código de estado HTTP 200. Junto con el código de estado, la respuesta devuelve un informe. Algunos de los parámetros de la respuesta se omitieron para facilitar la lectura.

Ejemplo de respuesta JSON para el informe de entidades

{
 "kind": "reports#usageReports",
 "nextPageToken": "NjQ1OTgwODk0MzkxNDAwNjQ0OA",
 "usageReports": [
 {
   "kind": "admin#reports#usageReport",
   "date": "2017-12-11",
   "entity": {
    "type": "OBJECT",
    "customerId": "C03az79cb",
    "objectType": "GPLUS_COMMUNITY",
    "objectId": "1234",
   },
   "parameters": [
    {
      "name": "gplus:community_name",
      "stringValue": "My Community"
    },
    {
     "name": "gplus:num_total_members",
     "intValue": 37
    },
    {
     "name": "gplus:num_7day_active_members",
     "intValue": 12
    },
    {
     "name": "gplus:num_30day_active_members",
     "intValue": 17
    },
   ]
  }
 ]
}

Ejemplo de respuesta JSON para un informe de entidades con advertencias

Es posible que se muestre una o más advertencias en la respuesta si no se puede completar la solicitud. En este ejemplo, el informe no está disponible en el momento en que se realiza la solicitud. 
{
 "kind": "reports#usageReports",
 "warnings": [
    {
      "code": "PARTIAL_DATA_AVAILABLE"
      "message": "Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours."
      "data": [
        {
          "key": "date"
          "value": "2017-12-11"
        }
      ]
    }
  ],
 "usageReports": [],
}
 Cada entrada del array warnings tiene los siguientes parámetros:
  • code: Código de advertencia legible por máquina
  • message: Mensaje de advertencia legible
  • data: Lista de pares clave-valor que brindan información detallada sobre la advertencia