Çok Kanallı Dönüşüm Hunileri Raporlama API'sı - Geliştirici Kılavuzu

Bu belgede, Çok Kanallı Dönüşüm Hunisi Verilerine erişmek için Çok Kanallı Dönüşüm Hunileri Raporlama API'sinin nasıl kullanılacağı açıklanmaktadır.

Giriş

Çok Kanallı Dönüşüm Hunileri Raporlama API'si, Çok Kanallı Dönüşüm Hunileri standart ve özel raporlarındaki tablo verilerine erişim sağlar. Verilere erişmek için şunları belirten bir sorgu oluşturursunuz: görünüm (profil), başlangıç ve bitiş tarihleri, tablodaki sütun başlıklarını oluşturan boyutlar ve metrikler. Bu sorgu, Çok Kanallı Dönüşüm Hunileri Raporlama API'sine gönderilir ve Çok Kanallı Dönüşüm Hunileri Raporlama API'si, tüm verileri tablo biçiminde döndürür.

API'yi kullanmaya yeni başladıysanız Çok Kanallı Dönüşüm Hunileri Raporlama API'sinin amacı ve sağladığı veriler hakkında bilgi edinmek için Çok Kanallı Dönüşüm Hunileri Raporlama API'sine Genel Bakış'ı okuyun.

Başlamadan Önce

Bu kılavuzda, Çok Kanallı Dönüşüm Hunileri Raporlama API'sine erişmek için Java istemci kitaplığı kullanılmaktadır. Her istemci kitaplığı, verileri almak için Çok Kanallı Dönüşüm Hunileri Raporlama API'sini çağıracak tek bir Analytics hizmet nesnesi sağlar. API'ye erişmek için istemci kitaplığı kullanmıyorsanız Çok Kanallı Dönüşüm Hunileri Raporlama API'si - Referans Kılavuzu'nu okuyun.

Analytics hizmet nesnesini oluşturmak için:

  1. Uygulamanızı Google API Konsolu'na kaydedin.
  2. Google Analytics verilerine erişim yetkisi verin.
  3. Analytics hizmet nesnesini oluşturmak için kod yazın.

Bu adımları tamamlamadıysanız durup bir Google Analytics API uygulaması oluşturmanın ilk adımlarında size yol gösterecek Merhaba Analytics API Eğiticisi'ni okuyun. Eğitimi tamamladıktan sonra aşağıdaki kılavuzu okumaya devam edin.

Örneğin, aşağıdaki kod yetkili bir Analytics hizmet nesnesi oluşturur:

Java

Analytics analytics = initializeAnalytics();

Çok Kanallı Dönüşüm Hunileri Raporlama API'sini çağırmak için analytics Analytics hizmet nesnesini kullanın.

Genel bakış

Veri almak amacıyla Çok Kanallı Dönüşüm Hunileri Raporlama API'sını kullanmak için bir uygulama yazın:

  1. Çok Kanallı Dönüşüm Hunileri Raporlama API'sini sorgulama.
  2. API'nin döndürdüğü sonuçlarla çalışın.

Çok Kanallı Dönüşüm Hunileri Raporlama API'sini sorgulama

Çok Kanallı Dönüşüm Hunileri Raporlama API'sinden veri istemek için:

  1. Çok Kanallı Dönüşüm Hunileri Raporlama API'si sorgu nesnesi oluşturun.
  2. Çok Kanallı Dönüşüm Hunisi sunucularından veri istemek için sorgu nesnesini kullanın.

Çok Kanallı Dönüşüm Hunileri Raporlama API'sı sorgusu oluşturma

Çok Kanallı Dönüşüm Hunileri Raporlama API'si sorgu nesnesi oluşturmak için şu yöntemi çağırın:

analytics.data.mcf.get()    // analytics is the Analytics service object

Yönteme sağlanan ilk parametre, ga:XXXX biçiminde benzersiz bir tablo kimliğidir. Burada XXXX, istenen verileri içeren bir Analytics görünümünün (profilin) kimliğidir. Sorgu parametrelerini belirtmek için sorgu nesnesini kullanın (ör. setDimensions). Örneğin:

Java

Get apiQuery = analytics.data().mcf()
    .get(tableId,
        "2012-01-01",              // Start date
        "2012-03-31",              // End date
        "mcf:totalConversions")    // Metrics
    .setDimensions("mcf:sourcePath")
    .setSort("-mcf:totalConversions")
    .setMaxResults(25);

Tüm sorgu parametrelerinin listesi için Sorgu Parametreleri Özeti bölümüne bakın. Metrik ve boyut parametreleri, Çok Kanallı Dönüşüm Hunileri'nden hangi verilerin alınacağını belirtmenize olanak tanır. Tüm boyutların ve metriklerin listesi için Boyutlar ve Metrikler Referansı'na bakın.

Çok Kanallı Dönüşüm Hunileri Raporlama API'sı veri isteğinde bulunma

Sorgu nesnesini oluşturduktan sonra, Çok Kanallı Dönüşüm Hunisi sunucularından veri istemek için nesnede execute yöntemini çağırın. Örneğin:

Java

try {
  apiQuery.execute();
  // Success. Do something cool!

} catch (GoogleJsonResponseException e) {
  // Catch API specific errors.
  handleApiError(e);

} catch (IOException e) {
  // Catch general parsing network errors.
  e.printStackTrace();
}

Bunun yerine ham API yanıtına erişmeyi tercih ederseniz sorgu nesnesinde executeUnparsed() yöntemini çağırın:

HttpResponse response = apiQuery.executeUnparsed();

Sorgu başarılı olursa istenen verileri döndürür. Bir hata oluşursa execute yöntemi, hataya ilişkin durum kodunu ve hatanın açıklamasını içeren bir istisna oluşturur. Uygulama, istisnayı yakalayıp işlemelidir.

API Sonuçlarıyla Çalışma

Çok Kanallı Dönüşüm Hunileri Reporting API sorgusu başarılı olursa raporlama verilerini ve verilerle ilgili bilgileri döndürür.

Çok Kanallı Dönüşüm Hunisi raporlama verileri

Sorgu, aşağıdaki tablo halindeki raporlama verilerini döndürür:

  • Sütun başlığı verileri
  • Satır verileri

Sütun başlığı verileri

Sorgu yanıtında, tablo başlığı bilgilerini içeren bir sütun başlığı alanı bulunur. Alan, ColumnHeaders nesnelerinden oluşan bir listedir (veya dizidir). Bu nesnelerin her biri sütun adı, sütun türü ve sütun veri türünü içerir. Sütun sıralaması, orijinal sorguda belirtilen sırayla boyut sütunları ve ardından metrik sütunlarıdır. Örneğin, aşağıdaki yöntem sütun başlıklarını yazdırır:

Java

private static void printColumnHeaders(McfData mcfData) {
  System.out.println("Column Headers:");

  for (ColumnHeaders header : mcfData.getColumnHeaders()) {
    System.out.println("Column Name: " + header.getName());
    System.out.println("Column Type: " + header.getColumnType());
    System.out.println("Column Data Type: " + header.getDataType());
  }
}

Satır verileri

API'den döndürülen ana veriler, McfData.Rows değerine ait 2 boyutlu List olarak döndürülür. Her McfData.Rows, String türünde temel değer veya McfData.Rows.ConversionPathValue türünde dönüşüm yolu değeri olan tek bir hücreyi temsil eder. Bir satırdaki hücrelerin sırası, yukarıda açıklanan sütun başlığı nesnesindeki alanlarla aynıdır.

Her bir hücredeki veriler dize veya Çok Kanallı Dönüşüm Hunileri sıra türü olarak döndürüldüğünden, her bir sütun başlığı nesnesindeki DataType alanı, değerleri uygun türlerde ayrıştırmak için özellikle yararlıdır. Tüm olası veri türleri için referans kılavuzuna bakın.

Örneğin, aşağıdaki yöntem tablo başlıklarını ve satırları yazdırır:

Java

private static void printDataTable(McfData mcfData) {
  System.out.println("Data Table:");
  if (mcfData.getTotalResults() > 0) {
    // Print the column names.
    List<ColumnHeaders> headers = mcfData.getColumnHeaders();
    for (ColumnHeaders header : headers) {
      System.out.print(header.getName());
    }
    System.out.println();

    // Print the rows of data.
    for (List<McfData.Rows> row : mcfData.getRows()) {
      for (int columnIndex = 0; columnIndex < row.size(); ++columnIndex) {
        ColumnHeaders header = headers.get(columnIndex);
        McfData.Rows cell = row.get(columnIndex);
        if (header.getDataType().equals("MCF_SEQUENCE")) {
          System.out.print(getStringFromMcfSequence(cell.getConversionPathValue()));
        } else {
          System.out.print(cell.getPrimitiveValue());
        }
      }
      System.out.println();
    }
  } else {
    System.out.println("No rows found");
  }
}

Aşağıdaki örnekte, Çok Kanallı Dönüşüm Hunileri adım sırası türü nesnesinin nasıl ayrıştırılacağı ve dizeye nasıl dönüştürüleceği gösterilmektedir:

Java

private static String getStringFromMcfSequence(List<McfData.Rows.ConversionPathValue> path) {
  StringBuilder stringBuilder = new StringBuilder();
  for (McfData.Rows.ConversionPathValue pathElement : path) {
    if (stringBuilder.length() > 0)
      stringBuilder.append(" > ");
    stringBuilder.append(pathElement.getNodeValue());
  }
  return stringBuilder.toString();
}

Rapor bilgileri

Sorgu, raporlama verilerine ek olarak bu verilerle ilgili bilgileri (ör. rapor kimliği) döndürür. Örneğin, aşağıdaki yöntem rapor bilgilerini yazdırır:

Java

private static void printReportInfo(McfData mcfData) {
  System.out.println("Report Info:");
  System.out.println("ID:" + mcfData.getId());
  System.out.println("Self link: " + mcfData.getSelfLink());
  System.out.println("Kind: " + mcfData.getKind());
  System.out.println("Contains Sampled Data: " + mcfData.getContainsSampledData());
}

containsSampledData alanı, sorgu yanıtının örneklenip örneklenmediğini belirtir. Örnekleme, sorgu sonuçlarını etkileyebileceği için sorgudan (API) döndürülen örneklenmiş değerler web arayüzünde gösterilenlerle eşleşmez. Daha fazla bilgi için Örnekleme bölümüne bakın.

(Profil) bilgilerini görüntüleyin

Sorgu yanıtı; web mülkü kimliğini, görünüm (profil) adını ve kimliğini ve görünümü (profili) içeren Analytics hesabının kimliğini içerir. Örneğin, aşağıdaki yöntem bunları terminale yazdırır (standart çıkış):

Java

private static void printProfileInfo(McfData mcfData) {
  ProfileInfo profileInfo = mcfData.getProfileInfo();

  System.out.println("View (Profile) Info:");
  System.out.println("Account ID: " + profileInfo.getAccountId());
  System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
  System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
  System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
  System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
  System.out.println("Table ID: " + profileInfo.getTableId());
}

Sorgu bilgileri

Sorgu yanıtı, tüm veri isteği sorgu parametrelerinin değerlerini içeren bir Query nesnesi içerir. Örneğin, aşağıdaki yöntem bu tür parametrelerin değerlerini yazdırır:

Java

private static void printQueryInfo(McfData mcfData) {
  Query query = mcfData.getQuery();

  System.out.println("Query Info:");
  System.out.println("Ids: " + query.getIds());
  System.out.println("Start Date: " + query.getStartDate());
  System.out.println("End Date: " + query.getEndDate());
  System.out.println("Metrics: " + query.getMetrics());       // List of Analytics metrics
  System.out.println("Dimensions: " + query.getDimensions()); // List of Analytics dimensions
  System.out.println("Sort: " + query.getSort());             // List of sorte metrics or dimensions
  System.out.println("Segment: " + query.getSegment());
  System.out.println("Filters: " + query.getFilters());
  System.out.println("Start Index: " + query.getStartIndex());
  System.out.println("Max Results: " + query.getMaxResults());
}

query.getMetrics(), query.getDimensions() ve query.getSort() dışındaki yöntemler String döndürür. Örneğin, query.getStartDate(), raporun başlangıç tarihini (bir String) döndürür.

Sayfalara ayırma bilgileri

Herhangi bir Çok Kanallı Dönüşüm Hunisi Reporting API isteği, yüz binlerce Çok Kanallı Dönüşüm Hunisi veri satırıyla eşleşebilir. Çok Kanallı Dönüşüm Hunileri Raporlama API'si, belirli bir zamanda yalnızca verilerin tek bir sayfası olarak adlandırılan bir alt kümeyi döndürür. Tüm veri sayfalarını almak için sayfalara ayırma alanını kullanın. Aşağıdaki yöntem, sayfalara ayırma bilgilerini yazdırır:

Java

private static void printPaginationInfo(McfData mcfData) {
  System.out.println("Pagination Info:");
  System.out.println("Previous Link: " + mcfData.getPreviousLink());
  System.out.println("Next Link: " + mcfData.getNextLink());
  System.out.println("Items Per Page: " + mcfData.getItemsPerPage());
  System.out.println("Total Results: " + mcfData.getTotalResults());
}

mcfData.getTotalResults() yöntem çağrısı, sorgu için toplam satır sayısını döndürür. Bu sayı, sorgunun döndürdüğü toplam satır sayısından daha büyük olabilir. mcfData.getItemsPerPage() yöntem çağrısı, sorgu yanıtının içerebileceği maksimum satır sayısını döndürür.

mcfData.getPreviousLink() yöntem çağrısı, önceki sayfanın bağlantısını ve mcfData.getNextLink(), sonraki sayfanın bağlantısını döndürür.

Tüm sonuçlar için toplamlar

Yalnızca sorgu yanıtında döndürülen sonuçları değil, tüm sonuçlar genelinde istenen metriklerin toplam değerlerini almak için sorgu yanıtında getTotalsForAllResults() yöntemini, bir McfData nesnesini çağırın. Ortalamaları hesaplamak için toplam değerleri kullanın.

Java

private static void printTotalsForAllResults(McfData mcfData) {
  System.out.println("Metric totals over all results:");
  Map<String, String> totalsMap = mcfData.getTotalsForAllResults();
  for (Map.Entry<String, String> entry : totalsMap.entrySet()) {
    System.out.println(entry.getKey() + " : " + entry.getValue());
  }
}

Çalışma Örneği

Java

Google API Java istemci kitaplığı Çok Kanallı Dönüşüm Hunileri Raporlama API'sı Örneği