API Reports: rapport sur l'utilisation des entités
Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Le rapport d'utilisation des entités affiche les activités des services Google Workspace liées aux entités
utilisés par les utilisateurs de votre compte. Vous pouvez personnaliser et filtrer ces rapports pour une utilisation spécifique
des informations. Des données sont disponibles pour les 30 derniers jours.
Le rapport d'utilisation des entités ne peut être utilisé qu'à des fins légales dans
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
Actuellement, le seul type d'entité compatible avec cette API est les communautés Google+. Pour récupérer un
de toutes les activités liées aux entités d'application de votre compte, utilisez
GET et inclure le jeton d'autorisation décrit dans la
documents d'autorisation. Pour
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 et l'horodatage se trouve au
Format ISO 8601, aaaa-mm-jj. Nous vous recommandons
utilisez pour cela le fuseau horaire de votre compte. Pour en savoir plus sur les paramètres de chaîne de requête et
de réponse, consultez les API
Documentation de référence. Pour en savoir plus sur les paramètres du rapport d'utilisation des entités, consultez les
Paramètres d'utilisation des entités
référence.
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 décrits dans la
Paramètres d'utilisation des entités
référence. Si aucun paramètre n'est spécifié, tous sont renvoyés.
parameterFilters est une liste de filtres à appliquer aux résultats, séparés par une virgule. Chaque
Le filtre a le format suivant :
application:parameter_name[relational_operator]parameter_value Par exemple,
filtrer gplus:num_total_members>100 filtre les résultats pour qu'ils ne contiennent que les résultats
où le paramètre gplus:num_total_members a une valeur supérieure à 100.
maxResults correspond au nombre maximal de résultats à renvoyer en une seule extraction. Si la valeur
de résultats est supérieur à cette valeur, la réponse est tronquée et un
nextPageToken sera inclus (consultez les
exemple de réponse JSON ci-dessous).
Exemples
Dans l'exemple suivant, la requête 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
Dans l'exemple suivant, la requête 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 permet d'obtenir un rapport de community_name et
num_total_members pour chaque entité gplus_communities, filtrée par
communautés comptant plus de 100 membres. Pour obtenir un exemple de réponse de l'API, consultez la
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 concernant une entité spécifique, utilisez la requête HTTP GET suivante et
incluez le jeton d'autorisation décrit dans
documents d'autorisation. Pour
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 le
chaque entité. Voir l'API
Référence pour savoir comment obtenir l'identifiant entityKey pour l'entité spécifique que vous
qui vous intéressent. Les autres paramètres sont décrits ci-dessus dans
Récupérez 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 plus d'informations
sur les paramètres du rapport d'utilisation des entités, consultez la
Paramètres d'utilisation des entités
référence.
Exemples
Dans l'exemple suivant, la requête récupère le rapport d'entité pour une entité gplus_community avec le paramètre
entityKey "1234".
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
Exemple de réponse JSON à un rapport sur l'utilisation
Les réponses positives affichent un code d'état HTTP 200. ainsi que
le code d'état, la réponse renvoie un rapport. Certains paramètres de la réponse ont été
sont 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 contenant des avertissements
Un ou plusieurs avertissements peuvent s'afficher dans la réponse si la requête ne peut pas être satisfaite. Dans ce
exemple, le rapport n'est pas disponible au moment où la demande est effectuée.
{
"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:
<ph type="x-smartling-placeholder"></ph>
code: code d'avertissement lisible par un ordinateur
message: message d'avertissement lisible
data: liste de paires clé/valeur fournissant des informations d'avertissement détaillées
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/08/29 (UTC).
[null,null,["Dernière mise à jour le 2025/08/29 (UTC)."],[],[],null,["# Reports API: Entities Usage Report\n\nThe entities usage report returns Google Workspace service activities related to entities\nused by your account's users. These reports can be customized and filtered for specific usage\ninformation. Data is available for the past 30 days.\n\nThe entities usage report may be used only for lawful purposes in\naccordance with your Customer Agreement. These reports also apply to\nGoogle Workspace and Education.\n\nRetrieve all entities usage activities\n--------------------------------------\n\nCurrently, the only entity type supported by this API is Google+ communities. To retrieve a\nreport of all activities related to app entities in your account, use the following\n`GET` HTTP request and include the authorization token described in the\n[authorization documentation](/workspace/admin/reports/v1/guides/authorizing). For\nreadability, the following example is formatted with line returns: \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date\n?parameters=applicationParameters\n&filters=parameterFilters\n&maxResults=maxResults\n```\n\nThe \u003cvar translate=\"no\"\u003edate\u003c/var\u003e value is the date the usage occurred and the timestamp is in the\n[ISO 8601 format](http://en.wikipedia.org/wiki/ISO_8601), yyyy-mm-dd. We recommend you\nuse your account's time zone for this. For more information about the query string parameters and\nresponse properties, see the [API\nReference](/workspace/admin/reports/v1/reference/entityUsageReports/get). For information about the entities usage report parameters, see the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/entities).\n\n\u003cvar translate=\"no\"\u003eapplicationParameters\u003c/var\u003e is a comma-separated list of parameters you wish to retrieve.\nEach parameter is formatted as `application:parameter_name`, for example,\n`gplus:community_name`. The available parameters are documented in the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/entities). If no parameters are specified, all are returned.\n\n\u003cvar translate=\"no\"\u003eparameterFilters\u003c/var\u003e is a comma-separated list of filters to apply to the results. Each\nfilter is formatted as\n`application:parameter_name[relational_operator]parameter_value`. For example, the\nfilter `gplus:num_total_members\u003e100` filters the results to contain only results\nwhere the `gplus:num_total_members` parameter has a value greater than 100.\n\n\u003cvar translate=\"no\"\u003emaxResults\u003c/var\u003e is the maximum number of results to return in a single fetch. If the total\nnumber of results is greater than this, the response will be truncated and a\n`nextPageToken` will be included (see the\n[JSON response example](#example_response) below).\n\n### Examples\n\nThe following example gets a report containing all parameters\nfor all `gplus_communities` entities. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all\n/dates/2017-12-11\n```\n\nThe following example gets a report containing the `community_name` parameter\nfor all `gplus_communities` entities. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all\n/dates/2017-12-11?parameters=gplus:community_name\n```\n\nThe following example gets a report of `community_name` and\n`num_total_members` for each `gplus_communities` entity, filtered by\ncommunities with more than 100 members. For an example of an API response, see the\n[JSON response example](#example_response). \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/2017-12-11\n?parameters=gplus:community_name,gplus:num_total_members&filters=gplus:num_total_members\u003e100\n```\n\nRetrieve a report for a specific entity\n---------------------------------------\n\nTo retrieve a report for a specific entity, use the following `GET` HTTP request and\ninclude the authorization token described in the\n[authorization documentation](/workspace/admin/reports/v1/guides/authorizing). For\nreadability, the following example is formatted with line returns. \n\n```\nGET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date\n?parameters=applicationParameters\n&filters=parameterFilters\n&maxResults=maxResults\n```\n\nThe \u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e is an entity identifier which is specific to the application where the\nentity lives. See the [API\nReference](/workspace/admin/reports/v1/reference/userUsageReport/get) for details on how to obtain the \u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e for the particular entity you\nare interested in. The other parameters are documented above under\n[Retrieve all entities usage activities](#get_all_entities_usage).\n\nFor more information about the query string parameters and response properties, see the [API Reference](/workspace/admin/reports/v1/reference/userUsageReport/get). For information\nabout the entities usage report parameters, see the\n[Entities Usage Parameters\nreference](/workspace/admin/reports/v1/reference/usage-ref-appendix-a/users).\n\n### Examples\n\nThe following example gets the entity report for a `gplus_community` entity with the\n\u003cvar translate=\"no\"\u003eentityKey\u003c/var\u003e \"1234\". \n\n```\nhttps://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11\n```\n\nUsage report example JSON response\n----------------------------------\n\nA successful response returns an [HTTP 200 status code](http://wikipedia.org/wiki/List_of_HTTP_status_codes). Along with\nthe status code, the response returns a report. Some of the parameters in the response have been\nomitted for readability.\n\n#### Example JSON response for entities report\n\n```carbon\n{\n \"kind\": \"reports#usageReports\",\n \"nextPageToken\": \"NjQ1OTgwODk0MzkxNDAwNjQ0OA\",\n \"usageReports\": [\n {\n \"kind\": \"admin#reports#usageReport\",\n \"date\": \"2017-12-11\",\n \"entity\": {\n \"type\": \"OBJECT\",\n \"customerId\": \"C03az79cb\",\n \"objectType\": \"GPLUS_COMMUNITY\",\n \"objectId\": \"1234\",\n },\n \"parameters\": [\n {\n \"name\": \"gplus:community_name\",\n \"stringValue\": \"My Community\"\n },\n {\n \"name\": \"gplus:num_total_members\",\n \"intValue\": 37\n },\n {\n \"name\": \"gplus:num_7day_active_members\",\n \"intValue\": 12\n },\n {\n \"name\": \"gplus:num_30day_active_members\",\n \"intValue\": 17\n },\n ]\n }\n ]\n}\n```\n\n#### Example JSON response for entities report with warnings\n\nOne or more warnings may be returned in the response if the request cannot be fulfilled. In this example, the report is not available at the time the request is made. \n\n```scdoc\n{\n \"kind\": \"reports#usageReports\",\n \"warnings\": [\n {\n \"code\": \"PARTIAL_DATA_AVAILABLE\"\n \"message\": \"Data for date 2017-12-11 for application gplus is not available right now, please try again after a few hours.\"\n \"data\": [\n {\n \"key\": \"date\"\n \"value\": \"2017-12-11\"\n }\n ]\n }\n ],\n \"usageReports\": [],\n}\n```\nEach entry in the `warnings` array has the following parameters:\n\n- `code`: machine-readable warning code\n- `message`: human-readable warning message\n- `data`: list of key-value pairs which give detailed warning information"]]
