Dasar-Dasar Laporan Tugas

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

Resource Tugas Laporan yang dihasilkan dari permintaan ini dapat digunakan untuk mengakses laporan yang disesuaikan oleh semua pengguna yang memiliki 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 otomatis dihapus.

Membuat Tugas Laporan

Google Analytics Data API v1 menggunakan pendekatan asinkron untuk membuat Tugas Laporan. Pertama, permintaan ke reportTasks.create metode diperlukan untuk membuat Tugas Laporan. Kemudian, metode reportTasks.query digunakan untuk mengambil laporan yang disesuaikan 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 Laporan

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

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 state kolom 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 dikenai biaya.

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 reportTasks.list metode.

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 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"
  }
}