Reports API: Nutzungsbericht zu Entitäten

Der Bericht zur Entitätsnutzung enthält Google Workspace-Dienstaktivitäten im Zusammenhang mit Entitäten, die von den Nutzern Ihres Kontos verwendet werden. Diese Berichte können angepasst und nach bestimmten Nutzungsinformationen gefiltert werden. Es stehen die Daten der letzten 30 Tage zur Verfügung.

Der Bericht zur Entitätsnutzung darf nur für rechtmäßige Zwecke gemäß Ihrer Kundenvereinbarung verwendet werden. Diese Berichte gelten auch für Google Workspace und Education.

Alle Aktivitäten zur Entitätsnutzung abrufen

Der einzige Entitätstyp, der von dieser API unterstützt wird, sind Google+‑Communities. Wenn Sie einen Bericht mit allen Aktivitäten im Zusammenhang mit App-Entitäten in Ihrem Konto abrufen möchten, verwenden Sie die folgende GET HTTP-Anfrage und fügen Sie das Autorisierungstoken ein, das in der Autorisierungsdokumentation beschrieben ist. Zur besseren Lesbarkeit ist das folgende Beispiel mit Zeilenumbrüchen formatiert:

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

Der date Wert ist das Datum, an dem die Nutzung stattgefunden hat. Der Zeitstempel ist im ISO 8601-Format, also JJJJ-MM-TT. Wir empfehlen, die Zeitzone Ihres Kontos zu verwenden. Weitere Informationen zu den Abfragestringparametern und Antwort-Properties finden Sie in der API Referenz. Informationen zu den Parametern des Berichts zur Entitätsnutzung finden Sie in der Referenz zu den Parametern zur Entitätsnutzung .

applicationParameters ist eine durch Kommas getrennte Liste der Parameter, die Sie abrufen möchten. Jeder Parameter ist als application:parameter_name formatiert, z. B. gplus:community_name. Die verfügbaren Parameter sind in der Referenz zu den Parametern zur Entitätsnutzung dokumentiert. Wenn keine Parameter angegeben sind, werden alle zurückgegeben.

parameterFilters ist eine durch Kommas getrennte Liste von Filtern, die auf die Ergebnisse angewendet werden sollen. Jeder Filter ist als application:parameter_name[relational_operator]parameter_value formatiert. Mit dem Filter gplus:num_total_members>100 werden die Ergebnisse beispielsweise so gefiltert, dass nur Ergebnisse enthalten sind, bei denen der gplus:num_total_members Parameter einen Wert über 100 hat.

`maxResults` ist die maximale Anzahl der Ergebnisse, die in einem einzelnen Abruf zurückgegeben werden sollen. Wenn die Gesamtzahl der Ergebnisse höher ist, wird die Antwort abgeschnitten und ein nextPageToken eingefügt (siehe das Beispiel für eine JSON-Antwort unten).

Beispiele

Im folgenden Beispiel wird ein Bericht mit allen Parametern für alle gplus_communities Entitäten abgerufen.

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

Im folgenden Beispiel wird ein Bericht mit dem community_name Parameter für alle gplus_communities Entitäten abgerufen.

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

Im folgenden Beispiel wird ein Bericht mit community_name und num_total_members für jede gplus_communities-Entität abgerufen, gefiltert nach Communities mit mehr als 100 Mitgliedern. Ein Beispiel für eine API-Antwort finden Sie im Beispiel für eine JSON-Antwort.

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

Bericht für eine bestimmte Entität abrufen

Wenn Sie einen Bericht für eine bestimmte Entität abrufen möchten, verwenden Sie die folgende GET HTTP-Anfrage und fügen Sie das Autorisierungstoken ein, das in der Autorisierungsdokumentation beschrieben ist. Zur besseren Lesbarkeit ist das folgende Beispiel mit Zeilenumbrüchen formatiert.

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

Das entityKey ist eine Entitäts-ID, die spezifisch für die Anwendung ist, in der sich die Entität befindet. In der API Referenz finden Sie Details dazu, wie Sie den entityKey für die gewünschte Entität abrufen. Die anderen Parameter werden weiter oben im Abschnitt Alle Aktivitäten zur Entitätsnutzung abrufen dokumentiert.

Weitere Informationen zu den Abfragestringparametern und Antwort-Properties finden Sie in der API-Referenz. Informationen zu den Parametern des Berichts zur Entitätsnutzung finden Sie in der Referenz zu den Parametern zur Entitätsnutzung.

Beispiele

Im folgenden Beispiel wird der Entitätsbericht für eine gplus_community Entität mit dem entityKey „1234“ abgerufen.

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

Beispiel für eine JSON-Antwort für einen Nutzungsbericht

Bei einer erfolgreichen Antwort wird der Statuscode „HTTP 200“ zurückgegeben. Zusammen mit dem Statuscode wird in der Antwort ein Bericht zurückgegeben. Einige der Parameter in der Antwort wurden zur besseren Lesbarkeit weggelassen.

Beispiel für eine JSON-Antwort für einen Entitätsbericht

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

Beispiel für eine JSON-Antwort für einen Entitätsbericht mit Warnungen

Wenn die Anfrage nicht erfüllt werden kann, werden in der Antwort möglicherweise eine oder mehrere Warnungen zurückgegeben. In diesem Beispiel ist der Bericht zum Zeitpunkt der Anfrage nicht verfügbar. 
{
 "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": [],
}
 Jeder Eintrag im Array warnings hat die folgenden Parameter:
  • code: maschinenlesbarer Warnungscode
  • message: für Menschen lesbare Warnungsmeldung
  • data: Liste von Schlüssel/Wert-Paaren mit detaillierten Warnungsinformationen