Dasar-Dasar Laporan Tugas

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

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 kontennya akan dihapus secara otomatis.

Membuat Tugas Laporan

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 dihasilkan.

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.

Memilih entitas pelaporan

Semua metode Data API v1 mengharuskan ID properti Google Analytics 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.

Meminta pembuatan Tugas 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. Anda bisa mendapatkan 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 tingkat tinggi 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 bisa mendapatkan status semua Tugas Laporan dengan memanggil metode reportTasks.list.

Mengambil laporan yang dihasilkan

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 Laporan sudah siap, respons yang berisi laporan yang dihasilkan akan ditampilkan:

Respons HTTP

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

...

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