API Reports: rapport sur l'utilisation des entités

Le rapport sur l'utilisation des entités renvoie les activités des services Google Workspace liées aux entités utilisées par les utilisateurs de votre compte. Ces rapports peuvent être personnalisés et filtrés pour obtenir des informations spécifiques sur l'utilisation. Les données sont disponibles pour les 30 derniers jours.

Le rapport sur l'utilisation des entités ne peut être utilisé qu'à des fins légales, conformément à votre contrat client. Ces rapports s'appliquent également à Google Workspace et Education.

Récupérer toutes les activités d'utilisation des entités

Le seul type d'entité accepté par cette API est celui des communautés Google+. Pour récupérer un rapport de toutes les activités liées aux entités d'application dans votre compte, utilisez la requête HTTP GET suivante et incluez le jeton d'autorisation décrit dans la documentation sur l'autorisation. Pour plus de lisibilité, l'exemple suivant est mis en forme avec des retours à la ligne :

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

La valeur date correspond à la date à laquelle l'utilisation a eu lieu. Le code temporel est au format ISO 8601 (aaaa-mm-jj). Nous vous recommandons d'utiliser le fuseau horaire de votre compte. Pour en savoir plus sur les paramètres de chaîne de requête et les propriétés de réponse, consultez la documentation de référence de l'API. Pour en savoir plus sur les paramètres du rapport sur l'utilisation des entités, consultez la documentation de référence sur les paramètres d'utilisation des entités.

applicationParameters est une liste de paramètres à récupérer, séparés par une virgule. Chaque paramètre est au format application:parameter_name, par exemple gplus:community_name. Les paramètres disponibles sont documentés dans la documentation de référence sur les paramètres d'utilisation des entités. Si aucun paramètre n'est spécifié, tous sont renvoyés.

parameterFilters est une liste de filtres séparés par une virgule à appliquer aux résultats. Chaque filtre est mis en forme comme suit : application:parameter_name[relational_operator]parameter_value. Par exemple, le filtre gplus:num_total_members>100 filtre les résultats pour n'inclure que ceux où le paramètre gplus:num_total_members a une valeur supérieure à 100.

maxResults correspond au nombre maximal de résultats à renvoyer lors d'une même récupération. Si le nombre total de résultats est supérieur à cette valeur, la réponse sera tronquée et un nextPageToken sera inclus (voir l'exemple de réponse JSON ci-dessous).

Exemples

L'exemple suivant récupère un rapport contenant tous les paramètres pour toutes les entités gplus_communities.

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

L'exemple suivant récupère un rapport contenant le paramètre community_name pour toutes les entités gplus_communities.

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

L'exemple suivant récupère un rapport sur community_name et num_total_members pour chaque entité gplus_communities, filtré par les communautés comptant plus de 100 membres. Pour obtenir un exemple de réponse d'API, consultez l'exemple de réponse 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

Récupérer un rapport pour une entité spécifique

Pour récupérer un rapport pour une entité spécifique, utilisez la requête HTTP GET suivante et incluez le jeton d'autorisation décrit dans la documentation sur l'autorisation. Pour plus de lisibilité, l'exemple suivant est mis en forme avec des retours à la ligne.

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

entityKey est un identifiant d'entité spécifique à l'application dans laquelle réside l'entité. Pour savoir comment obtenir le entityKey de l'entité qui vous intéresse, consultez la documentation de référence de l'API. Les autres paramètres sont décrits plus haut dans la section Récupérer toutes les activités d'utilisation des entités.

Pour en savoir plus sur les paramètres de chaîne de requête et les propriétés de réponse, consultez la documentation de référence de l'API. Pour en savoir plus sur les paramètres du rapport sur l'utilisation des entités, consultez la documentation de référence sur les paramètres d'utilisation des entités.

Exemples

L'exemple suivant obtient le rapport sur l'entité gplus_community avec entityKey "1234".

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

Exemple de réponse JSON du rapport sur l'utilisation

Une réponse réussie renvoie un code d'état HTTP 200. En plus du code d'état, la réponse renvoie un rapport. Certains paramètres de la réponse ont été omis pour des raisons de lisibilité.

Exemple de réponse JSON pour un rapport sur les entités

{
 "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
    },
   ]
  }
 ]
}

Exemple de réponse JSON pour un rapport sur les entités avec des avertissements

Une ou plusieurs mises en garde peuvent être renvoyées dans la réponse si la demande ne peut pas être satisfaite. Dans cet exemple, le rapport n'est pas disponible au moment de la demande. 
{
 "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": [],
}
 Chaque entrée du tableau warnings comporte les paramètres suivants :
  • code : code d'avertissement lisible par machine
  • message : message d'avertissement lisible par l'utilisateur
  • data : liste de paires clé/valeur qui fournissent des informations détaillées sur l'avertissement