API de informes: Informe de uso de entidades

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

El informe de uso de las entidades solo se puede utilizar con fines legales de conformidad con el Acuerdo con el Cliente. Estos informes también se aplican a Google Workspace y Education.

Recupera todas las actividades de uso de entidades

Actualmente, el único tipo de entidad compatible con esta API son las comunidades de Google+. Para recuperar un informe de todas las actividades relacionadas con las entidades de la app de tu cuenta, usa la siguiente solicitud HTTP GET e incluye el token de autorización descrito en la documentación de autorización. Para facilitar la lectura, el siguiente ejemplo está formateado con líneas que muestran lo siguiente:

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

El valor date es la fecha en que se produjo el uso, y la marca de tiempo está en formato ISO 8601, aaaa-mm-dd. Para ello, le recomendamos que utilice la zona horaria de su cuenta. Si deseas 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 de los informes de uso de las entidades, consulta la referencia de parámetros de uso de las 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 están documentados en la referencia de parámetros de uso de entidades. Si no se especifican parámetros, se muestran todos.

parameterFilters es una lista de filtros separados por comas para aplicar 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 contengan solo los resultados 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 mostrarán en una sola recuperación. Si la cantidad total de resultados es mayor que este valor, la respuesta se truncará y se incluirá una 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 para 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 por cada entidad gplus_communities, filtrado por comunidades con más de 100 miembros. Para ver un ejemplo de una respuesta a la API, consulta el ejemplo de respuesta de 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 de una entidad específica

Para recuperar un informe de una entidad específica, usa la siguiente solicitud HTTP GET e incluye el token de autorización descrito en la documentación de autorización. Para facilitar la lectura, el siguiente ejemplo está formateado con resultados de líneas.

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 que es 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 para la entidad específica que te interesa. Los demás parámetros se documentaron anteriormente en Recupera todas las actividades de uso de las entidades.

Si deseas 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 de los informes de uso de las entidades, consulta la referencia de parámetros de uso de las entidades.

Ejemplos

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

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

Ejemplo de respuesta JSON de informe de uso

Una respuesta correcta muestra un código de estado HTTP 200. Junto con el código de estado, la respuesta muestra 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 informes de entidades con advertencias

Si no se puede completar la solicitud, es posible que se muestren una o más advertencias en la respuesta. 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 por humanos
  • data: Lista de pares clave-valor que brindan información de advertencia detallada