Reports API: Laporan Penggunaan Entitas

Laporan penggunaan entitas menampilkan aktivitas layanan Google Workspace yang terkait dengan entitas yang digunakan oleh pengguna akun Anda. Laporan ini dapat disesuaikan dan difilter untuk informasi penggunaan tertentu. Data tersedia selama 30 hari terakhir.

Laporan penggunaan entitas hanya dapat digunakan untuk tujuan yang sah sesuai dengan Perjanjian Pelanggan Anda. Laporan ini juga berlaku untuk Google Workspace dan Education.

Mengambil semua aktivitas penggunaan entitas

Satu-satunya jenis entitas yang didukung oleh API ini adalah komunitas Google+. Untuk mengambil laporan semua aktivitas yang terkait dengan entitas aplikasi di akun Anda, gunakan permintaan HTTP GET berikut dan sertakan token otorisasi yang dijelaskan dalam dokumentasi otorisasi. Agar mudah dibaca, contoh berikut diformat dengan pemisahan baris:

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

Nilai date adalah tanggal terjadinya penggunaan dan stempel waktu dalam format ISO 8601, yyyy-mm-dd. Sebaiknya Anda menggunakan zona waktu akun Anda untuk hal ini. Untuk mengetahui informasi selengkapnya tentang parameter string kueri dan properti respons, lihat Referensi API. Untuk mengetahui informasi tentang parameter laporan penggunaan entitas, lihat referensi Parameter Penggunaan Entitas.

applicationParameters adalah daftar parameter yang dipisahkan koma yang ingin Anda ambil. Setiap parameter diformat sebagai application:parameter_name, misalnya, gplus:community_name. Parameter yang tersedia didokumentasikan dalam referensi Parameter Penggunaan Entitas. Jika tidak ada parameter yang ditentukan, semua akan ditampilkan.

parameterFilters adalah daftar filter yang dipisahkan koma untuk diterapkan pada hasil. Setiap filter diformat sebagai application:parameter_name[relational_operator]parameter_value. Misalnya, filter gplus:num_total_members>100 memfilter hasil agar hanya berisi hasil dengan parameter gplus:num_total_members yang memiliki nilai lebih besar dari 100.

maxResults adalah jumlah maksimum hasil yang akan ditampilkan dalam satu pengambilan. Jika jumlah total hasil lebih besar dari ini, respons akan dipangkas dan nextPageToken akan disertakan (lihat contoh respons JSON di bawah).

Contoh

Contoh berikut mendapatkan laporan yang berisi semua parameter untuk semua entity gplus_communities.

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

Contoh berikut mendapatkan laporan yang berisi parameter community_name untuk semua entitas gplus_communities.

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

Contoh berikut mendapatkan laporan community_name dan num_total_members untuk setiap entitas gplus_communities, yang difilter menurut komunitas dengan lebih dari 100 anggota. Untuk contoh respons API, lihat Contoh respons 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

Mengambil laporan untuk entitas tertentu

Untuk mengambil laporan untuk entity tertentu, gunakan permintaan HTTP GET berikut dan sertakan token otorisasi yang dijelaskan dalam dokumentasi otorisasi. Agar mudah dibaca, contoh berikut diformat dengan pemisahan baris.

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

entityKey adalah ID entity yang khusus untuk aplikasi tempat entity berada. Lihat Referensi API untuk mengetahui detail tentang cara mendapatkan entityKey untuk entitas tertentu yang Anda minati. Parameter lainnya didokumentasikan sebelumnya di bagian Mengambil semua aktivitas penggunaan entitas.

Untuk mengetahui informasi selengkapnya tentang parameter string kueri dan properti respons, lihat Referensi API. Untuk mengetahui informasi tentang parameter laporan penggunaan entitas, lihat Referensi Parameter Penggunaan Entitas.

Contoh

Contoh berikut mendapatkan laporan entity untuk entity gplus_community dengan entityKey "1234".

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

Contoh respons JSON laporan penggunaan

Respons yang berhasil akan menampilkan kode status HTTP 200. Bersama dengan kode status, respons akan menampilkan laporan. Beberapa parameter dalam respons telah dihilangkan agar mudah dibaca.

Contoh respons JSON untuk laporan entitas

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

Contoh respons JSON untuk laporan entitas dengan peringatan

Satu atau beberapa peringatan dapat ditampilkan dalam respons jika permintaan tidak dapat dipenuhi. Dalam contoh ini, laporan tidak tersedia pada saat permintaan dibuat.

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

Setiap entri dalam array warnings memiliki parameter berikut:

• code: kode peringatan yang dapat dibaca mesin
• message: pesan peringatan yang dapat dibaca manusia
• data: daftar pasangan nilai kunci yang memberikan informasi peringatan mendetail