Interfejs Reports API: raport o wykorzystaniu elementów
Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Raport o wykorzystaniu encji zwraca działania usługi Google Workspace związane z encjami
używane przez użytkowników konta. Raporty można dostosowywać i filtrować pod kątem określonego wykorzystania
i informacjami o nich. Dostępne są dane z ostatnich 30 dni.
Raportu o korzystaniu z podmiotów może być wykorzystany tylko do celów zgodnych z prawem
zgodnie z Umową klienta. Raporty te dotyczą również
Google Workspace i Google Workspace for Education.
Pobieranie wszystkich aktywności związanych z wykorzystaniem encji
Obecnie jedynym typem encji obsługiwanym przez ten interfejs API są społeczności Google+. Aby pobrać
wszystkich działań związanych z elementami aplikacji na Twoim koncie, użyj
GET i podaj token autoryzacji opisany w
dokumentację autoryzacji. Dla:
w poniższym przykładzie formatowany jest za pomocą funkcji zwracania wierszy:
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults
Wartość date to data użycia, a sygnatura czasowa znajduje się w
Format ISO 8601, rrrr-mm-dd. Nasze wskazówki
użyj do tego strefy czasowej swojego konta. Więcej informacji o parametrach ciągu zapytania
właściwości odpowiedzi można znaleźć w interfejsie API
Plik referencyjny. Informacje o parametrach raportu na temat wykorzystania encji znajdziesz tutaj:
Parametry wykorzystania encji
odniesienie.
applicationParameters to rozdzielona przecinkami lista parametrów, które chcesz pobrać.
Każdy parametr ma format application:parameter_name, np.
gplus:community_name Dostępne parametry są opisane w
Parametry wykorzystania encji
odniesienie. Jeśli nie podasz żadnych parametrów, zwracane są wszystkie.
parameterFilters to oddzielona przecinkami lista filtrów, które mają zostać zastosowane do wyników. Każdy
filtr jest sformatowany jako
application:parameter_name[relational_operator]parameter_value Na przykład parametr
filtr gplus:num_total_members>100 filtruje wyniki, aby zawierały tylko wyniki
gdzie parametr gplus:num_total_members ma wartość większą niż 100.
maxResults to maksymalna liczba wyników do zwrócenia w ramach jednego pobrania. Jeśli suma
liczba wyników jest większa od tej wartości, odpowiedź zostanie skrócona, a
nextPageToken (zobacz
przykład odpowiedzi JSON poniżej).
Przykłady
Poniższy przykład pokazuje raport zawierający wszystkie parametry
dla wszystkich gplus_communities elementów.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11
Poniższy przykład pokazuje raport zawierający parametr community_name.
dla wszystkich elementów gplus_communities.
GET https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/all
/dates/2017-12-11?parameters=gplus:community_name
Poniższy przykład obejmuje raport community_name i
num_total_members dla każdej jednostki gplus_communities, przefiltrowane według
społeczności liczące ponad 100 członków. Przykładowa odpowiedź interfejsu API znajdziesz w sekcji
Przykład odpowiedzi 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
Pobieranie raportu dotyczącego określonego elementu
Aby pobrać raport dotyczący konkretnego elementu, użyj tego żądania HTTP GET i
umieść token autoryzacji opisany w
dokumentację autoryzacji. Dla:
czytelność w przykładzie poniżej jest sformatowany ze znakami powrotu wierszy.
GET https://admin.googleapis.com/admin/reports/v1/gplus_communities/entityKey/dates/date
?parameters=applicationParameters
&filters=parameterFilters
&maxResults=maxResults
entityKey to identyfikator jednostki specyficzny dla aplikacji, w której
jak żyje dana jednostka. Zapoznaj się z interfejsem API
Link zawiera szczegółowe informacje o tym, jak uzyskać entityKey w przypadku konkretnego podmiotu
które mogą być interesujące. Pozostałe parametry są opisane powyżej w sekcji
Pobieranie wszystkich aktywności związanych z użyciem encji.
Więcej informacji o parametrach ciągu zapytania i właściwościach odpowiedzi znajdziesz w dokumentacji interfejsu API. Informacje na temat
o parametrach raportu wykorzystania jednostek,
Parametry wykorzystania encji
odniesienie.
Przykłady
Poniższy przykład pokazuje raport elementów dla elementu gplus_community z parametrem
entityKey „1234”.
https://admin.googleapis.com/admin/reports/v1/usage/gplus_communities/1234/dates/2017-12-11
Przykładowa odpowiedź JSON z raportem o wykorzystaniu
Pomyślna odpowiedź zwraca kod stanu HTTP 200. Razem z
kod stanu, odpowiedź zwróci raport. Niektóre parametry w odpowiedzi zostały
pominięte ze względu na czytelność.
Przykładowa odpowiedź JSON dotycząca raportu encji
{
"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
},
]
}
]
}
Przykładowa odpowiedź JSON dotycząca raportu dotyczącego encji z ostrzeżeniami
Jeśli nie można zrealizować żądania, w odpowiedzi może wyświetlić się co najmniej 1 ostrzeżenie. W tym
np. w chwili wysyłania żądania raport nie jest dostępny.
{
"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": [],
}
Każdy wpis w tablicy warnings ma te parametry:
code: kod ostrzeżenia zrozumiały dla komputera
message: komunikat ostrzegawczy zrozumiały dla człowieka
data: lista par klucz-wartość, które zawierają szczegółowe ostrzeżenia
O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.
Ostatnia aktualizacja: 2025-08-29 UTC.
[null,null,["Ostatnia aktualizacja: 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"]]
