Dasar-Dasar Laporan Tugas

Dengan tugas laporan, Anda dapat memulai permintaan asinkron yang berjalan lama untuk membuat laporan yang disesuaikan untuk data peristiwa Google Analytics Anda.

Resource Tugas Laporan yang dihasilkan dari permintaan ini dapat digunakan untuk mengakses laporan yang disesuaikan oleh semua pengguna dengan akses baca ke properti Google Analytics Anda.

Laporan yang disesuaikan akan tersedia selama 72 jam setelah siap. Setelah periode ini, resource tugas laporan yang sesuai dan isinya akan dihapus secara otomatis.

Membuat Tugas Pelaporan

Google Analytics Data API v1 menggunakan pendekatan asinkron untuk membuat Tugas Laporan. Pertama, permintaan ke metode reportTasks.create diperlukan untuk membuat Tugas Laporan. Kemudian, metode reportTasks.query digunakan untuk mengambil laporan kustom yang dibuat.

Selain itu, Anda dapat menggunakan reportTasks.get untuk mengambil metadata konfigurasi tentang Tugas Laporan tertentu dan reportTasks.list untuk mencantumkan semua Tugas Laporan untuk properti.

Pilih entitas pelaporan

Semua metode Data API v1 memerlukan ID properti Google Analytics untuk ditentukan di dalam jalur permintaan URL dalam bentuk properties/GA_PROPERTY_ID, seperti:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

Laporan dibuat berdasarkan data peristiwa Google Analytics yang dikumpulkan di properti Google Analytics yang ditentukan.

Jika menggunakan salah satu library klien Data API, Anda tidak perlu memanipulasi jalur URL permintaan secara manual. Sebagian besar klien API menyediakan parameter property yang mengharapkan string dalam bentuk properties/GA_PROPERTY_ID. Lihat Panduan memulai cepat untuk mengetahui contoh penggunaan library klien.

Pembuatan Tugas Permintaan Laporan

Untuk membuat Tugas Laporan, panggil metode reportTasks.create menggunakan objek ReportTask dalam permintaan. Parameter berikut diperlukan:

Contoh permintaan pembuatan Tugas Laporan:

Permintaan HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
  "reportDefinition": {
    "dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
    "dimensions": [{ "name": "country" }],
    "metrics": [{ "name": "activeUsers" }]
  }
}

Respons metode reportTasks.create berisi nama Tugas Laporan di kolom name (seperti properties/1234567/reportTasks/123), yang dapat digunakan dalam kueri berikutnya untuk mendapatkan status Tugas Laporan dan mengambil laporan yang dihasilkan.

Respons HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
    "name": "properties/1234567/reportTasks/123",
    "reportDefinition": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ],
      "dateRanges": [
        {
          "startDate": "2024-05-01",
          "endDate": "2024-05-15"
        }
      ]
    },
    "reportMetadata": {
      "state": "CREATING",
      "beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
    }
  }
}

Mendapatkan status kesiapan Tugas Pelaporan

Mungkin perlu waktu beberapa menit untuk membuat laporan setelah panggilan reportTasks.create dilakukan. Anda dapat memperoleh status kesiapan untuk Tugas Laporan dengan memanggil metode reportTasks.get.

Gunakan nama Tugas Laporan (seperti properties/1234567/reportTasks/123) yang Anda terima dari respons reportTasks.create untuk menentukan Tugas Laporan.

Contoh:

Permintaan HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

Status kesiapan untuk Tugas Laporan ditampilkan di kolom state respons. Setelah pembuatan laporan selesai, status Tugas Laporan akan berubah dari CREATING menjadi ACTIVE.

Kolom reportMetadata berisi informasi umum tentang laporan yang dihasilkan, seperti jumlah baris dan jumlah token kuota yang ditagih.

Respons HTTP

{
  "reportDefinition": {
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ]
  },
  "reportMetadata": {
    "state": "ACTIVE",
    "beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
    "creationQuotaTokensCharged": 6,
    "taskRowCount": 167,
    "errorMessage": "",
    "totalRowCount": 167
  }
}

Anda dapat memperoleh status semua Tugas Laporan dengan memanggil metode reportTasks.list.

Mengambil laporan yang dibuat

Setelah Tugas Laporan yang dibuat menggunakan metode reportTasks.create dibuat, panggil metode reportTasks.query dan tentukan nama Tugas Laporan (seperti properties/1234567/reportTasks/123).

Permintaan HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

Jika Tugas Pelaporan sudah siap, respons yang berisi laporan yang dibuat akan ditampilkan:

Respons HTTP

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}