Rapor görevleriyle ilgili temel bilgiler

Rapor görevlerini kullanarak Google Analytics etkinlik verilerinizin özelleştirilmiş bir raporunu oluşturmak için uzun süreli bir asenkron istek başlatabilirsiniz.

Bu istekten oluşturulan rapor görevi kaynağı, Google Analytics mülkünüze okuma erişimi olan tüm kullanıcılar tarafından özel raporlara erişmek için kullanılabilir.

Özel rapor, hazır olduktan sonra 72 saat boyunca kullanılabilir. Bu sürenin ardından, ilgili rapor görevi kaynağı ve içeriği otomatik olarak silinir.

Rapor görevi oluşturma

Google Analytics Data API v1, rapor görevleri oluşturmak için eşzamansız bir yaklaşım kullanır. Öncelikle bir rapor görevi oluşturmak için reportTasks.create yöntemine istek gönderilmesi gerekir. Ardından, oluşturulan özelleştirilmiş raporu almak için reportTasks.query yöntemi kullanılır.

Ayrıca, belirli bir rapor göreviyle ilgili yapılandırma meta verilerini almak için reportTasks.get, bir mülkün tüm rapor görevlerini listelemek için ise reportTasks.list yöntemini kullanabilirsiniz.

Raporlama tüzel kişisi seçin

Data API v1'in tüm yöntemleri, Google Analytics mülk tanımlayıcısının URL istek yolunda properties/GA_PROPERTY_ID biçiminde belirtilmesini gerektirir. Örneğin:

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

Rapor, belirtilen Google Analytics mülkünde toplanan Google Analytics etkinlik verilerine göre oluşturulur.

Data API istemci kitaplıklarından birini kullanıyorsanız istek URL'si yolunu manuel olarak değiştirmeniz gerekmez. Çoğu API istemcisi, properties/GA_PROPERTY_ID biçiminde bir dize bekleyen bir property parametresi sağlar. İstemci kitaplıklarının kullanımına dair örnekler için Hızlı başlangıç kılavuzu'na bakın.

Rapor görevi oluşturma isteğinde bulunma

Rapor görevi oluşturmak için bir istekte ReportTask nesnesini kullanarak reportTasks.create yöntemini çağırın. Aşağıdaki parametreler zorunludur:

Örnek rapor görevi oluşturma isteği:

HTTP İsteği

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

reportTasks.create yönteminin yanıtı, name alanında rapor görevi adını (ör. properties/1234567/reportTasks/123) içerir. Bu ad, sonraki sorgularda rapor görevinin durumunu öğrenmek ve sonuç raporunu almak için kullanılabilir.

HTTP Yanıtı

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

Rapor görevinin hazırlık durumunu alma

reportTasks.create çağrısından sonra raporun oluşturulması birkaç dakika sürebilir. reportTasks.get yöntemini çağırarak bir rapor görevinin hazırlık durumunu öğrenebilirsiniz.

Rapor görevini belirtmek için reportTasks.create yanıtından aldığınız rapor görevi adını (ör. properties/1234567/reportTasks/123) kullanın.

Örnek:

HTTP İsteği

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

Rapor görevinin hazırlık durumu, yanıtın state alanında döndürülür. Rapor oluşturma işlemi tamamlandığında rapor görevinin durumu CREATING iken ACTIVE olarak değişir.

reportMetadata alanı, oluşturulan raporla ilgili üst düzey bilgiler (ör. satır sayısı ve ücretlendirilen kota jetonlarının miktarı) içerir.

HTTP Yanıtı

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

reportTasks.list yöntemini çağırarak tüm rapor görevlerinin durumunu öğrenebilirsiniz.

Oluşturulan raporu alma

reportTasks.create yöntemi kullanılarak oluşturulan rapor görevi oluşturulduğunda reportTasks.query yöntemini çağırın ve rapor görevinin adını (ör. properties/1234567/reportTasks/123) belirtin.

HTTP İsteği

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

Rapor görevi hazırsa oluşturulan raporu içeren bir yanıt döndürülür:

HTTP Yanıtı

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

...

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

Sonraki adımlar