Модуль FeedBurner API для Delphi 2010.

Хотите создать без проблем свою собственную программу по анализу фидов Google FeedBurner? Нет ничего проще. Сегодня я хочу представить Вам небольшую разработку — модуль, реализующий в полной мере API FeedBurner.

При разработке FeedAPI я постарался, на сколько это возможно, сделать работу с модулем простой и понятной. Для того, чтобы было понятно, что может Вам дать этот модуль, рассмотрим вкратце API FeedBurner и посмотрим как реализованы, предоставляемые функции в модуле FeedAPI.

FeedBurner API. Зачем и для чего он?

Вот цитата из Лаборатории Google о том, что такое FeedBurner API:

FeedBurner предлагает разработчикам крупную (и развивающуюся!) библиотеку веб-служб для управления каналами данных создания автоматических уведомлений. Используя функции этой библиотеки, любой обладатель аккаунта Google с включенной службой FeedBurner может выполнить некоторые из обычных действий, программно доступных в нашей службе.

Например, в одном из постов я рассматривал вопрос о том, как получить количество подписчиков в FeedBurner. Казалось бы мелочь, однако подобная возможность в Вашей программе может повысить её (программы) привлекательность, особенно, если приложение рассчитано на работу с блогами.

Или, допустим, Вам необходимо получить информацию по какому либо элементу вашего фида (посту): количество кликов и откуда эти клики были произведены. Для этого Вы должны:

1. Зайти в свой аккаунт FeedBurner
2. Выбрать свой фид в списке
3. Перейти на страницу Analyze —> ItemUse
4. Найти необходимый элемент в списке и кликнуть по нему

В итоге, Вы должны попасть на страницу с примерно таким содержанием:

Абсолютно ту же самую информацию с помощью API FeedBurner Вы можете получить в виде XML выполнив простой запрос вида:

GET feedburner.google.com/api/awareness/1.0/GetResyndicationData?uri=&itemurl=&dates=,

Результатом выполнения запроса будет XML-документ со следующим содержанием:

И Вам остается только разобрать этот документ и вывести результат пользователю.
Более того, используя API Вы можете легко на одном графике получать данные по нескольким элементам фида или сравнивать несколько фидов, что достаточно проблематично сделать стандартными средствами FeedBurner’a.
Таким образом FeedBurner API дает в наше распоряжение достаточно мощный инструмент для анализа своих и, что немаловажно, чужих фидов. Для чего проводить подобный анализ — решать только Вам. Можно, например, определять какие из тем пользуются наибольшей популярностью у пользователей — по кликам. Или найти наиболее активного реферрера.

2. Как использовать FeedBurner API

Для того, чтобы использовать FeedBurner API вы должны настроить свой фид. Первое, что следует сделать — это определить, какие данные должны быть доступны для просмотра в статистике. Для этого следует выбрать в аккаунте FeedBurner свой фид, перейти на страницу «Analyze — Configure Stats» и выбрать необходимые элементы статистики. Это могут быть:
Item views — просмотры элементов фида
Item link clicks — клики по элементам фида с переходом на Ваш блог
Item enclosure downloads — количество загрузок для подкастов
Затем Вы должны включить сервис Awareness API, который и дает возможность использовать API для фида. Сервис подключается на страницу Publicize.
После этих действий можно приступать к полноценному использованию API.
Сразу следует отметить, что в API предусмотрена определенная форма использования дат и интервалов времени.
Любая дата в запросе должна быть составлена в следующем формате: YYYY-MM-DD.
При этом, если необходимо получить информацию по фиду за интервал времени, например с 01.11.2009 по 09.11.2009, то в запросе этот интервал следует записывать так:

2009-11-01,2009-11-09

В случае, если необходима информация за несколько дней дискретно, например на 01.11.2009, 05.11.2009 и 07.11.2009 (три дня), то в запросе следует записать такой параметр:

2009-11-01/2009-11-05/2009-11-07

В модуле FeedAPI за преобразование дат отвечают три функции.
Функция SetAPIDate переводит дату из TDate в формат, необходимый для запроса API и выглядит следующим образом:

function SetAPIDate(const cDate: TDate): string; 
var
  Day, Month, Year: word;
begin
  DecodeDate(cDate, Year, Month, Day);
  Result := IntToStr(Year) + '-';
  if Month < 10 then
    Result := Result + '0' + IntToStr(Month) + '-'
  else
    Result := Result + IntToStr(Month) + '-';
  if Day < 10 then
    Result := Result + '0' + IntToStr(Day)
  else
    Result := Result + IntToStr(Day);
end;

Для обратного преобразования используется функция GetAPIDate:

function GetAPIDate(cDate: string): TDate;
var
  Day, Month, Year: integer;
begin
  Year := StrToInt(copy(cDate, 1, 4));
  Delete(cDate, 1, 5);
  Month := StrToInt(copy(cDate, 1, 2));
  Delete(cDate, 1, 3);
  Day := StrToInt(copy(cDate, 1, 2));
  Result := EncodeDate(Year, Month, Day);
end;

Для составления запроса с несколькими датами (дискретно расположенными) используется функция SetAPIDiscreteDate:

function SetAPIDiscreteDate(Dates: TDiscreteDates): string;
var
  i: integer;
begin
  Result := '';
  for i := 0 to length(Dates) - 1 do
    Result := Result + SetAPIDate(Dates[i]) + '/';
  Delete(Result, length(Result), 1);
end;

2.1. Виды запросов к FeedBurner API

Всего Awareness API в настоящее время поддерживает три вида запросов:
1. GetFeedData — получение основной информации по фиду: количество подписчиков, количество переходов на страницы блога из фида, охват и количество загрузок.
2. GetItemData — получение данных по элементам фида. Для каждого элемента в данном случае Вы можете получить следующую информацию: заголовок, оригинальный URL, количесво просмотров элемента и количество переходов пользователей и ботов на страницы блога (количество кликов)
3. GetResyndicationData — получение информации по фиду и его элементам включая данные по реферрерам.
При этом, используя каждый вид запроса, Вы можете дополнительно включать в запрос параметр, содержащий интервал времени, за который необходимо получить данные, а для GetItemData и GetResyndicationData определить конкретный элемент фида по которому необходимо получить информацию.
Теперь рассмотрим реализацию FeedBurner API в Delphi.

3. Модуль FeedAPI для работы с FeedBurnerAPI.

Чтобы максимально упростить использование модуля, при его разработке я использовал следующий подход к составлению функций:
1. Для каждого вида запроса определена своя функция для разбора XML-документа (всего три функции). В качестве агрументов функций выступает уже готовый URL запроса.
2. В каждого вида запроса определен свой формат предоставления данный (запись record).
3. Для получения информации с помощью API каждый вид запроса содержит набор функций с названиями следующего формата:
GetCur***(FeedURI: string; cDate: TDate) — получение текущей информации по конкретному виду запроса, либо данные за один определенный день.
Get***Between(const FeedURI: string; StartDate, EndDate: TDate) — получение информации по определенному виду запроса за непрерывный интервал времени, который определен через начальную (StartDate) и конечную (EndDate) даты.
Get***Discrete(const FeedURI: string; Dates: TDiscreteDates) — получение информации по запросу за дискретный интервал времени, который задается в виде массива дат в параметре Dates
Дополнительно для запросов GetItemData и GetResyndicationData определены функции вида
Get***Single***(***), которые используются для получения информации по отдельно взятым элементам фида.

3.1. Работа с запросами GetFeedData

Для того, чтобы получить информацию по фиду, в самом простом случае, необходимо выполнить запрос вида:

GET feedburner.google.com/api/awareness/1.0/GetItemData?uri=

где URI — это идентификатор вашего фида, который задается Вами на этапе регистрации RSS-потока. Получить URI можно, например из счётчика FeedBurner:

Результатом выполнения запроса будет XML-документ, содержащий текущую информацию по фиду:

Или, в случае ошибочного запроса:

Как видно из рисунков, корневой элемент всегда rsp. В зависимости от того успешный или нет был запрос у корневого элемента изменяется атрибут stat. Соответственно, для того, чтобы написать простенький парсер такого документа, можно использовать такой алгоритм:
1. Отправляем запрос и получаем XML-документ
2. Определяем значение атрибута stat у корневого элемента
3. В зависимости от значения stat читаем либо данные о фиде, либо информацию об ошибке: код и текстовое описание.
Для реализации этого алгоритма в модуле определены следующие типы данных:

type //информация об ошибке
  TRSPError = record 
    code: integer; //код
    msg: string;    //текстовое описание
  end;

для хранения информации из элемента entry определена запись:

type
  TRSPBasicEntry = record
    date: TDate; //дата за которую получена информация
    circulation: integer; //количество подписчиков
    hits: integer;   //количество переходов
    reach: integer; //охват
    downloads: integer;//количество загрузок
  end;

И, наконец, запись содержащая всю информацию по запросу:

type
  TBasicResponce = record
    rsp_stat: string;
    error: TRSPError;
    entry: array of TRSPBasicEntry;
  end;

Для разбора XML-документа, полученного в результате запроса, используется функция:

function ParseFeedData(URL: string): TBasicResponce; 
var
  i: integer;
  Doc: IXMLDocument;
  ItemNodes: IDOMNodeList;
  ChildNode: IDOMNodeEx;
begin
  Doc := NewXMLDocument(); // создаем пустой документ
  { загружаем XML-документ API }
  Doc.LoadFromFile(URL);
  if Doc.IsEmptyDoc then
  begin
    ShowMessage('Пустой документ');
    Exit
  end;
  ItemNodes := Doc.DOMDocument.getElementsByTagName('rsp');
  ChildNode := ItemNodes.item[0] as IDOMNodeEx; // элемент rsp
  Result.rsp_stat := ChildNode.attributes.getNamedItem('stat').nodeValue;
  if Result.rsp_stat = 'ok' then // получен ответ с результатами
  begin
    ItemNodes := Doc.DOMDocument.getElementsByTagName('entry');
    SetLength(Result.entry, ItemNodes.length);
    // читаем данные о фиде
    for i := 0 to ItemNodes.length - 1 do
    begin
      ChildNode := ItemNodes.item[i] as IDOMNodeEx;
      with Result.entry[i] do
      begin
        date := GetAPIDate(ChildNode.attributes.getNamedItem('date').nodeValue);
        circulation := StrToInt(ChildNode.attributes.getNamedItem('circulation')
            .nodeValue);
        hits := StrToInt(ChildNode.attributes.getNamedItem('hits').nodeValue);
        downloads := StrToInt(ChildNode.attributes.getNamedItem('downloads')
            .nodeValue);
        reach := StrToInt(ChildNode.attributes.getNamedItem('reach').nodeValue);
      end;
    end;
  end
  else // получен ответ об ошибке
  begin
    ItemNodes := Doc.DOMDocument.getElementsByTagName('err');
    ChildNode := ItemNodes.item[0] as IDOMNodeEx;
    Result.error.code := StrToInt(ChildNode.attributes.getNamedItem('code')
        .nodeValue);
    Result.error.msg := ChildNode.attributes.getNamedItem('msg').nodeValue;
  end;
end;

Как видите, для работы с модулем нет необходимости использовать компонент XMLDocument — вся работа ведется напрямую через интерфейсы из модуля xmldom.
Для того, чтобы получить информацию по запросу Вы можете использовать следующие функции:

function GetCurFeedData(const FeedURI: string; cDate: TDate):TBasicResponce;
function GetFeedDataBetween(const FeedURI: string; StartDate, EndDate: TDate): TBasicResponce;
function GetFeedDataDiscrete(const FeedURI: string; Dates: DiscreteDates):TBasicResponce;

(Назначение каждой из функций см. выше :) )

3.2. Работа с запросами GetItemData

Вид простого запроса:

GET feedburner.google.com/api/awareness/1.0/GetItemData?uri=

Результатом запроса будет XML-документ:

Либо документ содержащий код и описание ошибки. Как видно, этот документ содержит туже информацию, что и в случае запроса GetFeedData и дополнительно информацию по элементам фида. Соответственно запись для хранения информации запроса будет выглядеть следующим образом:

type
  TItemResponce = record
    rsp_stat: string; //состояние запроса
    error: TRSPError;//сообщение об ошибке
    entry: array of TRSPItemEntry; //элементы запроса
  end;

каждый элемент поля entry определен как:

type
  TRSPItemEntry = record
    Basic: TRSPBasicEntry; //информация из элемента entry
    Items: array of TRSPItem;//информация из элементов item
  end;

тип TRSPItem описан как запись вида:

type
  TRSPItem = record
    Title: string; //заголовок элемента
    URL: string; //оригинальный URL на запись
    itemviews: integer; //количество просмотров элемента
    clickthroughs: integer; //количество переходов (кликов)
  end;

Для получения информации по запросу можно использовать следующие функции:

function ParseItemData(URL: string):TItemResponce;
function GetCurItemData(FeedURI: string; cDate: TDate):TItemResponce;
function GetItemDataBetween(FeedURI: string; StartDate, EndDate: TDate):TItemResponce;
function GetItemDataDiscrete(FeedURI: string; Dates: TDiscreteDates) :TItemResponce;
{информация по отдельным элементам}
function GetCurSingleItemData(FeedURI, ElementURL: string; cDate:TDate):TItemResponce;
function GetSingleItemDataBetween(FeedURI, ElementURL: string; StartDate, EndDate: TDate):TItemResponce;
function GetSingleItemDataDiscrete(FeedURI, ElementURL: string;  Dates: TDiscreteDates):TItemResponce;

3.2. Работа с запросами GetResyndicationData

По своей форме данный вид запроса отличается от предыдущего тем, что содержит детальную информацию по реферрерам для каждого элемента фида.
Вид запроса:

GET feedburner.google.com/api/awareness/1.0/GetResyndicationData?uri=

XML-документ, содержащий ответ в случае успешного запроса:

Соответственно, запись, содержащая информацию по запросу будет выглядеть следующим образом:

type
  TResyncItemResponce = record
    rsp_stat: string;
    error: TRSPError;
    entry: array of TRSPResyncItemEntry;
  end;

Элемент записи entry в данном случае имеет более сложную форму:

type
  TRSPResyncItemEntry = record
    Basic: TRSPBasicEntry;
    Items: array of TRSPResyncItem;
  end;
 
type
  TRSPResyncItem = record
    Basic: TRSPItem;
    Referrer: array of TReferrer;//реферреры для элемента
  end;

А запись реферрера выглядит как:

type
  TReferrer = record
    URL: string;
    itemviews: integer;
    clickthroughs: integer;
  end;

Для получения информации по запросу используются следующие функции:

function ParseResyncData(URL: string):TResyncItemResponce;
function GetCurResyncData(FeedURI: string; cDate: TDate): TResyncItemResponce;
function GetResyncDataBetween(FeedURI: string; StartDate, EndDate: TDate):TResyncItemResponce;
function GetResyncDataDiscrete(FeedURI: string; Dates:TDiscreteDates):TResyncItemResponce;
function GetResyncSingleData(FeedURI, ElementURL: string; cDate: TDate):TResyncItemResponce;
function GetResyncSingleDataBetween(FeedURI, ElementURL: string;  StartDate, EndDate: TDate):TResyncItemResponce;
function GetResyncSingleDataDiscrete(FeedURI, ElementURL: string;  Dates: TDiscreteDates):TResyncItemResponce;

4. Резюмируем

Таким образом, с помощью представленного модуля Вы можете получить всю информацию, которую предоставляет в распоряжение разработчиков Awareness API. При этом, в зависимости от целей, которые Вы преследуете, Вы можете использовать различные виды запросов. Так, для получения динамики роста/падения количества подписчиков, наиболее целесообразно использование запросов вида GetFeedData — самой простой формы запроса к API.
С другой стороны, если вам необходимо определить пути поступления трафика на ваш блог/сайт, а также определить какие записи пользуются наибольшим спросом у пользователей, то здесь Вам понадобится использование самого сложного запроса вида GetResyndicationData.
Использование модуля не подразумевает наличия у Вас каких либо знаний по работе с XML — вся информация по запросам предоставляется в форме записей (record) Delphi.
Модуль не использует в своей работе каких либо компонентов — для его использования достаточно прописать имя модуля в uses.