Le rapport sur l'utilisation des entités renvoie les activités de service Google Workspace liées aux entités utilisées par les utilisateurs de votre compte. Vous pouvez personnaliser ces rapports et les filtrer selon des informations d'utilisation spécifiques. 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
Actuellement, le seul type d'entité compatible avec 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 les autorisations. Pour des raisons 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 et à l'horodatage au format ISO 8601 (aaaa-mm-jj). Nous vous recommandons d'utiliser le fuseau horaire de votre compte pour cela. 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 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 que vous souhaitez 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 les résultats sont renvoyés.
parameterFilters est une liste de filtres à appliquer aux résultats, séparés par une virgule. Chaque filtre est au format application:parameter_name[relational_operator]parameter_value. Par exemple, le filtre gplus:num_total_members>100 filtre les résultats pour ne contenir que les résultats dont 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 le nombre total de résultats est supérieur à cette limite, la réponse est tronquée et un élément nextPageToken est inclus (voir l'exemple de réponse JSON ci-dessous).
Exemples
L'exemple suivant permet d'obtenir un rapport contenant tous les paramètres de 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 permet d'obtenir 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 génère un rapport sur community_name et num_total_members pour chaque entité gplus_communities, filtrée pour n'afficher que les communautés de 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 les autorisations. Pour des raisons 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é. Consultez la documentation de référence de l'API pour savoir comment obtenir la valeur entityKey pour l'entité particulière qui vous intéresse. Les autres paramètres sont présentés ci-dessus dans la section Récupérer toutes les activités d'utilisation des entités.
Pour plus d'informations 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 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 permet d'obtenir le rapport d'entité pour une entité gplus_community avec l'élément entityKey "1234".
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
Exemple de réponse JSON de rapport sur l'utilisation
Les appels réussis renvoient un code d'état HTTP 200. Avec le 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 le 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 le rapport sur les entités avec des avertissements
Un ou plusieurs avertissements peuvent s'afficher dans la réponse si la requête ne peut pas être traitée. 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 un ordinateurmessage: message d'avertissement lisible par l'humaindata: liste des paires clé-valeur qui fournissent des informations d'avertissement détaillées