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

Bu belgede, Çok Kanallı Dönüşüm Hunileri 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'sı, Çok Kanallı Dönüşüm Hunileri standart ve özel raporlardaki tablo verilerine erişim sağlar. Verilere erişmek için görünümü (profil), başlangıç ve bitiş tarihlerini, tablodaki sütun başlıklarını oluşturan boyut ve metrikleri belirten bir sorgu oluşturursunuz. 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 bir 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 temel bilgiler için Çok Kanallı Dönüşüm Hunileri Raporlama API'sine Genel Bakış'ı okuyun.

Not: Çok Kanallı Dönüşüm Hunileri Raporlama API'sı, düzenlenemeyen 30 günlük bir yeniden inceleme aralığı kullanır.

Başlamadan Önce

Bu kılavuzda, Çok Kanallı Dönüşüm Hunileri Raporlama API'sine erişmek için Java istemci kitaplığı kullanılı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 bir 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 kodu yazın.

Bu adımları tamamlamadıysanız bir Google Analytics API uygulaması oluşturmanın ilk adımlarında size yol gösterecek olan Hello Analytics API Eğiticisini durdurup 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'sine çağrıda bulunmak için analytics adlı Analytics hizmet nesnesini kullanın.

Genel bakış

Verileri almak üzere Çok Kanallı Dönüşüm Hunileri Raporlama API'sini kullanmak için şunları yazın:

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

Çok Kanallı Dönüşüm Hunileri Raporlama API'sını 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 Hunileri sunucularından veri istemek için sorgu nesnesini kullanın.

Çok Kanallı Dönüşüm Hunileri Raporlama API'si 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 (profilinin) kimliğidir. Sorgu parametrelerini belirtmek için sorgu nesnesini kullanın (yani 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'ne bakın. Metrikler ve boyutlar 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'si veri isteğinde bulunma

Sorgu nesnesini oluşturduktan sonra, Çok Kanallı Dönüşüm Hunileri 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, hatanın 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 Raporlama API'si sorgusu başarılı olursa raporlama verilerini ve verilerle ilgili bilgileri döndürür.

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

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

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

Sütun başlığı verileri

Sorgu yanıtı, tablo başlığı bilgilerini içeren bir sütun başlığı alanı içerir. Alan, her biri sütun adı, sütun türü ve sütun veri türünü içeren ColumnHeaders nesnenin listesi (veya dizisi). Sütun sırası, boyut sütunlarının ardından orijinal sorguda belirtilen sırayla 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 tutarındaki 2 boyutlu List şeklinde döndürülür. Her McfData.Rows, tek bir hücreyi temsil eder: String türünden oluşan temel değer veya McfData.Rows.ConversionPathValue türündeki dönüşüm yolu değeridir. 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 bir dize veya Çok Kanallı Dönüşüm Hunileri dizi türü olarak döndürüldüğünden, her sütun başlığı nesnesindeki DataType alanı özellikle değerleri uygun türlere ayrıştırmak için yararlıdır. Olası tüm 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 dizi türü nesnesinin nasıl ayrıştırılacağı ve bir 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 verilerle ilgili bilgileri de (örneğin, rapor kimliği) döndürür. Örneğin, aşağıdaki yöntemde rapor bilgileri yazdırılı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 örneklenmiş olup olmadığını gösterir. Örnekleme, sorgu sonuçlarını etkileyebileceğinden, 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üleme

Sorgu yanıtı, web mülkü kimliğini, görünümü (profil) adını, 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 (String) döndürür.

Sayfalara ayırma bilgileri

Çok Kanallı Dönüşüm Hunileri Raporlama API'si istekleri, yüz binlerce satırlık Çok Kanallı Dönüşüm Hunileri verileriyle eşleşebilir. Çok Kanallı Dönüşüm Hunileri Raporlama API'si, belirli bir zamanda, verilerin tek bir sayfası olarak adlandırılan yalnızca bir alt küme 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, sorgu tarafından döndürülen toplam satır sayısından daha büyük olabilir. mcfData.getItemsPerPage() yöntemi ç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ı, mcfData.getNextLink() ise bağlantıyı sonraki sayfaya döndürür.

Tüm sonuçların toplamları

İstenen metriklerin toplam değerlerini, yalnızca sorgu yanıtında döndürülen sonuçlarla değil, tüm sonuçlarla ilgili olarak almak için sorgu yanıtında getTotalsForAllResults() yöntemini, yani 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'si Örneği