Overview   Package  Class  Use  Tree  Deprecated  Index 
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    

Package ru.metrika4j

Центральный класс Metrika4j - MetrikaApi.

See:
          Description

Interface Summary
AccountApi API для работы с аккаунтами, представителем которых является текущий пользователь
DelegateApi API для работы с делегатами
FilterApi API для работы с фильтрами.
GoalApi API для работы с целями
GrantApi API для работы с правами доступа
MetrikaApi API Яндекс.Метрики.
OperationApi  
Report Отчёт системы Яндекс.Метрика.
ReportBuilder Построитель отчетов.
ReportItem Одна запись с результатами отчёта.
 

Class Summary
ApiFactory Класс, создающий экземпляр MetrikaApi.
Example Примеры использования Metrika4j
MetrikaDate Представление даты в API Яндекс.Метрики.
 

Enum Summary
ReportBuilder.Group Способ группировки данных по времени в отчёте
ReportBuilder.TableMode Способ представления результатов отчёта
Reports Отчёты, доступные в API Яндекс.Метрики
 

Package ru.metrika4j Description

Центральный класс Metrika4j - MetrikaApi. В нем есть методы для работы с главными сущностями Яндекс.Метрики: счетчиками и отчетами. Работа с дополнительными сущностями (Цели, Фильтры, etc) вынесена в отдельные мини-API, получаемые из главного класса MetrikaApi c помощью методов getXxxApi(), например API целей MetrikaApi.getGoalApi().
Структура методов примерно соответствует структуре REST-вызовов. Один REST-вызов = один метод. Аргументы, передаваемые в REST-вызов, соответствуют аргументам, передаваемым в методы API (кроме API работы с отчетами).
Все сущности (счетчики, цели, фильтры, etc) - POJO объекты, без какой либо бизнес-логики.

Подготовка к использованию Metrika4j

Прежде всего надо получить OAuth токен. В Metrika4j нет функций, связанных c OAuth авторизацией: предполагается, что пользователь самостоятельно получает OAuth токен доступными ему способами, и передаёт в API уже готовый токен. Процедура получения токена описана здесь.
Далее, надо выбрать, с помощью чего обрабатывать JSON. В Metrika4j есть встроенная поддержка Jackson JSON-processor (полноценный маппинг) и библиотеки org.json, как lightweight варианта, удобного для использования под Android (реализовано только чтение счетчиков и работа с отчетами). * Можно подключить любой другой JSON процессор, создав c его помощью имплементации интерфейсов JsonMapper и JsonObject. Готовые имплементации, включенные в Metrika4j - это JacksonMapper и OrgJsonMapper

Начало работы с Metrika4j

Сначала необходимо создать экземпляр MetrikaApi c помощью ApiFactory 
    // Создаем экземпляр API, использующий Jackson JSON-processor и транспорт по умолчанию
    MetrikaApi api = ApiFactory.createMetrikaAPI("05dd3dd84ff948fdae2bc4fb91f13e22", new JacksonMapper());
Если HTTP транспорт по умолчанию (использующий стандартный HttpUrlConnection из JDK) не устраивает, можно создать свой транспорт, имплементировав HttpTransport. Транспорт должен получать OAuth токен при создании и передавать его в каждом запросе к серверам Метрики. 
    // Создаём транспорт, передав в него OAuth токен
    HttpTransport transport = new MyTransport("05dd3dd84ff948fdae2bc4fb91f13e22");

    // Создаем экземпляр API, использующий Jackson JSON-processor и заданный транспорт
    MetrikaApi api = ApiFactory.createMetrikaAPI(transport, new JacksonMapper());
Полученный экземпляр API полностью thread-safe, поэтому на все приложение достаточно только одного экземпляра.

Работа со счетчиками

     // Получаем список счетчиков в текущем аккаунте
     Counter[] myCounters = api.getCounters();
По умолчанию в полученных счетчиках не будет заполнена часть полей (цели, фильтры, зеркала и т.п.). Чтобы заполнить их, надо при чтении счетчиков указать, какая детализация нужна 
     // Получаем счетчики с заполненными целями и фильтрами
     Counter[] myCounters = api.getCounters(CounterDetails.goals, CounterDetails.filters);
     // Получаем счетчики с полной детализацией
     Counter[] detailedCounters = api.getCounters(CounterDetails.values());
При повышении детализации будет увеличиваться время ответа и объем передаваемой информации, поэтому лучше не злоупотреблять высокой детализацией. 
     // Создание счетчика
     Counter newCounter = new Counter();
     newCounter.setSite("mysite.ru");
     newCounter.setName("Мой сайт");
     Counter createdCounter = api.createCounter(newCounter);
     // В createdCounter содержится новый счетчик, загруженный из Метрики, со всем значениями полей, проставленными Метрикой
     System.out.println(createdCounter.getId());
 
     // Удаление счетчика
     api.deleteCounter(createdCounter.id);

Работа с отчетами

Набор доступных отчетов содержится в enum-e Reports. Для построения отчета надо вызвать метод MetrikaApi.makeReportBuilder(Reports, int), который вернет объект ReportBuilder - построитель отчета. В построителе отчета можно задать параметры отчета (временной интервал, сортировку и т.п.). Когда все параметры будут установлены, вызывайте метод ReportBuilder.build(), который отправит запрос на сервер API Метрики и вернет результат. 
    // Создаем построитель отчета "популярное содержимое" для счетчика с id=2138128
    ReportBuilder builder = api.makeReportBuilder(Reports.contentPopular, 2138128);

    // Задаём параметры отчета (отчет за неделю) и строим отчет
    Report report = builder.withDateFrom(MetrikaDate.yesterday()).withDateTo(MetrikaDate.today()).build();
Отчет возвращается в виде объекта Report, представляющего собой таблицу с результатами, плюс некоторая дополнительная информация (итоги, интервал дат, к которым относится отчет и т.п.). Каждая строка таблицы результатов - объект ReportItem, данные из которого можно получить одним из методов getXXX(String fieldName) (аналогично получению значений из JDBC ResultSet). Имена полей и возвращаемые дополнительные данные надо уточнять для каждого отчета в документации на API Яндекс.Метрики 
     // Вытаскиваем результаты из отчета
     ReportItem[] items = report.getData();
     for (ReportItem item : items) {
         System.out.printf("pageViews: %4d, url: %s", item.getInt("page_views"), item.getString("url")).println();
     }
Некоторые отчеты бывают не только табличные, но и древовидные. Для получения древовидного отчета надо задать в ReportBuilder соответствующий режим. 
   // Строим такой же отчет, но древовидный
   report = builder.withTableMode(ReportBuilder.TableMode.tree).build();
   // Отображаем первые два уровня
   items = report.getData();
   for (ReportItem item : items) {
       // Первый уровень
       System.out
               .printf("Level 1, pageViews: %4d, url: %s", item.getInt("page_views"), item.getString("url"))
               .println();
       ReportItem[] children = item.getArray("chld");
       if (children != null) {
           for (ReportItem child : children) {
               // Второй уровень
               System.out
                       .printf("     Level 2, pageviews: %4d, url: %s", child.getInt("page_views"),
                               child.getString("url"))
                       .println();
           }
       }
   }

Обработка ошибок

Все ошибки, возникающие в ходе работы Metrika4j, унаследованы от базового класса Metrika4jException. Ошибки могут возникнуть только в момент обращения к серверам API Метрики. Картина такова:

Thread safety

Все основные классы Metrika4j не содержат состояния (stateless). API Я.Метрики также работает через stateless REST интерфейс. Это означает, что можно делать параллельные запросы из нескольких потоков, используя один экземпляр MetrikaApi Каждый полученный отчет потом должен обрабатываться в рамках одного потока, т.к. thread safety библиотек, выгружающих данные из JSON ответов, не гарантируется.

Overview   Package  Class  Use  Tree  Deprecated  Index 
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    
Copyright © 2011. All Rights Reserved.