REST Client Library: использование API ВКонтакте #3

Продолжаем разбираться с API ВКонтакте. За время, прошедшее с последней публикации на эту тему, пообщался с несколькими людьми по поводу работы как API Vk в общем, так и использования REST Client Library в Delphi  в частности. Простенькие вопросы типа проблем с кодировками текста в сообщениях решились на форуме или в комментариях к статьям. Один вопрос остался на данный момент открытым и именно его сегодня и рассмотрим, а именно: как скачать музыку ВКонтакте? В принципе, вопрос достаточно актуальный, одновременно, интересный. Для порядка рассмотрим весь процесс работы с аудио-записями в ВК, начиная с получения списка альбомов пользователя до загрузки и проигрывания отдельных композиций. Итак, вооружаемся Delphi XE5/XE7 c REST Client Library, документацией к API и начинаем работу.

Так как это уже третья статья на тему использования API ВКонтакте, то здесь я не буду рассказывать про то, как авторизовать пользователя VK, а просто дам ссылку на статью где про это рассказывается — вот она. Отмечу только, что

Для разнообразия, сегодня в работе я буду использовать VCL. Итак, авторизация в ВК прошла успешно, у вас в руках токен доступа к данным пользователя с правом доступа к аудиозаписям. Что дальше? Дальше открываем список методов API и смотрим на методы в разделе «Аудиозаписи». В этом разделе находятся методы, которые и пригодятся нам для того, чтобы скачать музыку из ВКонтакте.

Получение списка альбомов пользователя

Для начала научимся читать список альбомов, которые пользователь создал у себя в аккаунте. Для этого мы должны использовать метод audio.getAlbums, который имеет следующие параметры:

• owner_id (целое число) — идентификатор пользователя или сообщества, у которого необходимо получить список альбомов с аудио. По умолчанию будет равен идентификатору текущего пользователя.
• offset (целое положительное число) — смещение, необходимое для выборки определенного подмножества альбомов.
• count (целое положительное число) — количество альбомов, которое необходимо вернуть. По умолчанию — 50, максимально — 100.

В результате запроса сервер вернет нам массив элементов, каждый из которых будет представлять из себя один альбом пользователя. Сам объект альбома содержит всего три параметра:

• id — идентификатор альбома;
• owner_id — идентификатор владельца альбома;
• title — название альбома.

Теперь посмотрим как запросить список альбомов пользователя в Delphi. У меня в приложении компоненты REST Client Library вынесены в отдельный TDataModule:

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

const
  API_VERSION = '5.25';
 
function TAPI.Album_Get(AOwnerID: cardinal): TJSONObject;
begin
  Result:=nil;
  VKRequest.Resource:='audio.getAlbums';
  VKRequest.Method:=TRESTRequestMethod.rmGET;
  VKRequest.Params.Clear;
  with VKRequest.Params.AddItem do
    begin
      name:='v';
      Value:=API_VERSION;
      Options:=[poDoNotEncode];
    end;
  with VKRequest.Params.AddItem do
    begin
      name:='count';
      Value:='100';
      Options:=[poDoNotEncode];
    end;
  VKRequest.Execute;
 
  if VKRequest.Response.StatusCode=200 then
    Result:=VKResponse.JSONValue as TJSONObject
  else
    raise Exception.Create(VKResponse.ErrorMessage);
end;

Этот метод написан в качестве примера и не учитывает то, что пользователи бывают всякие, а именно то, что у пользователя может быть и 1 и 10 и 200 альбомов. Максимум, что я получу из аккаунта — это 100 альбомов. Теперь надо разобрать полученный ответ. Смотрим, что нам вернет сервер:

С использованием нынешних возможностей Delphi разобрать такой JSON-объект — дело пяти минут. Пусть у нас в программе каждый альбом храниться в отдельном объекте, имеющем следующее описание:

TVKAlbum = class
  private
    FID: cardinal;
    FOwnerID: cardinal;
    FTitle: string;
  public
    constructor Create(AJSONObject: TJSONObject);
    destructor Destroy;override;
    procedure Parse(AJSONObject: TJSONObject);
    property ID: cardinal read FID;
    property OwnerID: cardinal read FOwnerID;
    property Title: string read FTitle;
  end;

В метод Parse будет передаваться JSON-объект с описанием альбома, а сам метод будет выглядеть следующим образом:

procedure TVKAlbum.Parse(AJSONObject: TJSONObject);
const
  cPairs: array [0..2]of string = ('id','owner_id','title');
var Enums: TJSONPairEnumerator;
begin
  if not Assigned(AJSONObject) then Exit;
  Enums:=AJSONObject.GetEnumerator;
  try
    while Enums.MoveNext do
      begin
        case StrIndex(Enums.Current.JsonString.Value,cPairs) of
          0:Fid:=TJSONNumber(Enums.Current.JsonValue).AsInt64;//'id'
          1:FOwnerId:=TJSONNumber(Enums.Current.JsonValue).AsInt64;//'owner_id'
          2:FTitle:=Enums.Current.JsonValue.Value;//'title'
        end;
      end;
  finally
    Enums.Free;
  end;
end;

То есть здесь я вначале получаю перечислитель всех пар в JSON-объекте (Enums: TJSONPairEnumerator), а затем прохожу по каждой паре, определяю её индекс в массиве cPairs и, в зависимости от полученного значения заполняю уже поля Delphi-объекта.

Почему так «сложно»? В принципе, т.к. мы знаем перечень пар, которые содержит JSON-объект альбома, мы могли бы обойтись и без перечислителя, выполняя что-то типа:

FId:=AJSONObject.Get('id').Value;

И этот код прекрасно бы работал в текущей версии API. Но, имея некоторый опыт работы с различными API онлайн-сервисов, в последнее время я использую перечислители полей и константы-массивы по той простой причине, что в любой момент и название пар в JSON-объекта и их количество может измениться, причем значительно (достаточно посмотреть на перечень изменений в API Vk). В итоге, если API меняется и, например, пара идентификатора альбома станет называться album_id , то на строке:

FId:=AJSONObject.Get('id').Value;

мы получим законный AV, избежать который мы можем, используя конструкции if…then, каждый раз проверяя есть ли пара в объекте или нет. Если пар в JSON много, то мы просто устанем при каждом серьезном изменении API читать нагромождения if’ов, а потом добавлять ещё и новые. А код функции выше изменяется просто — добавляем новый элемент массива, дописываем нужные значения в case..of и все работает как надо.

Итак, как разбирать JSON-объект альбома разобрались. Для тех, кто теряется в JSON поясню картинкой. Сейчас мы научились читать  вот эту часть ответа сервера:

Добраться до массива «items», до массива items в JSON можно, например, так:

var JArray: TJSONArray;
    JValue: TJSONValue;
    I: Integer;
    A: TVKAlbum;
begin
  if not Assigned(AJSON) then Exit;
  JValue:=AJSON.GetValue('response');//в этой строке вы можете получить ошибку, т.к. метод GetValue появился в Delphi XE6
  if not Assigned(JValue) then Exit; //получили ответ?
  JArray:=(JValue as TJSONObject).Values['items'] as TJSONArray;//нашли массив
  {проходим по каждому элементы и создаем объекта альбомов}
  for I := 0 to JArray.Count-1 do
    begin
      A:=TVKAlbum.Create(TJSONObject(JArray.Items[i]));
      {заносим объект в список, массив и т.д.} 
    end;
end;

Получив список альбомов мы сможем в своей программе мы можем запрашивать аудиозаписи из конкретного альбома. Посмотрим как получаются аудиозаписи из ВК.

Получение списка аудиозаписей пользователя

Для получения списка аудиозаписей пользователя мы должны использовать метод audio.get. Этот метод имеет следующие параметры:

• owner_id (целое число) — идентификатор владельца аудиозаписей (пользователь или сообщество)
• album_id (целое число) — идентификатор альбома с аудиозаписями
• audio_ids (список положительных чисел, разделенных запятыми) — идентификаторы аудиозаписей, информацию о которых необходимо вернуть
• need_user (1 или 0) — 1 — возвращать информацию о пользователях, загрузивших аудиозапись
• offset (положительное число) — смещение, необходимое для выборки определенного количества аудиозаписей. По умолчанию — 0.
• count (положительное число)- количество аудиозаписей, информацию о которых необходимо вернуть. Максимальное значение — 6000.

Здесь сразу стоит прояснить некоторые моменты по работе метода, чтобы в будущем не получить «сюрприз».

Во-первых,  ни один из параметров метода не является обязательным. Если отправить на сервер запрос без параметров, то сервер попытается вернуть вам весь список аудиозаписей текущего пользователя, начиная с самой первой записи.

Во-вторых, метод имеет ограничение — 6000 записей максимум. Это значит, что как бы вы не старались и что бы не предпринимали, сервер может вам вернуть только список из первых 6000 записей. Если вы захотите получить 6001-й элемент списка и установите такие параметры запроса:

• count=1
• offset = 6000

то сервер вам вернет пустой массив. Вот такое неприятное для нас ограничение. Но с этим ничего не поделаешь. Теперь как реализовать работу с аудиозаписями пользователя ВК в Delphi. Получение списка аудиозаписей ничем принципиально не отличается от получения альбомов, т.е. метод фактически 1 в 1  повторяет Album_Get (конечно же для примера — в реальном приложении такого жесткого копипаста лучше избегать):

function TAPI.Audio_Get(AOwnerID: cardinal): TJSONObject;
begin
  Result:=nil;
  VKRequest.Resource:='audio.get';
  VKRequest.Method:=TRESTRequestMethod.rmPOST;
  VKRequest.Params.Clear;
  with VKRequest.Params.AddItem do
    begin
      name:='v';
      Value:=API_VERSION;
      Options:=[poDoNotEncode];
    end;
  with VKRequest.Params.AddItem do
    begin
      name:='owner_id';
      Value:=AOwnerID.ToString;
      Options:=[poDoNotEncode];
    end;
  VKRequest.Execute;
  if VKRequest.Response.StatusCode=200 then
    Result:=VKResponse.JSONValue as TJSONObject;
end;

Возвращаемый сервером JSON-объект выглядит точно так же как и предыдущий, т.е. содержит пары «response», «items» и т.д., но только в массиве уже содержатся JSON-объекты аудиозаписей. Выглядит ответ сервера вот так:

Каждый JSON-объект аудиозаписи содержит следующие пары:

• id — идентификатор аудиозаписи
• owner_id — идентификатор владельца аудиозаписи
• artist — исполнитель
• title — название композиции
• duration — длительность аудиозаписи в секундах
• url — ссылка на mp3
• lyrics_id — идентификатор текста аудиозаписи
• album_id — идентификатор альбома, в котором находится аудиозапись (если присвоен)
• genre_id — идентификатор жанра из списка аудио жанров.

Как видите, в этом объекте есть всё, что нам необходимо — прямая ссылка на mp3-файл, название, исполнитель и т.д. Объект в Delphi можно определить такой:

type
  TVKAudio = class
  private
    Fid: cardinal;
    FOwnerId: cardinal;
    FArtist: string;
    FTitle: string;
    FDuration: cardinal;
    FUrl: string;
    FLyricsId: cardinal;
    FAlbumId: cardinal;
    FGenreId: word;
  public
    constructor Create(AJSONObject: TJSONObject);
    destructor Destroy;override;
    procedure Parse(AJSONObject: TJSONObject);
    property id: cardinal read FId;
    property OwnerId: cardinal read FOwnerId;
    property Artist: string read FArtist;
    property Title: string read FTitle;
    property Duration: cardinal read FDuration;
    property Url: string read FURL;
    property LyricsId: cardinal read FLyricsId;
    property AlbumId: cardinal read FAlbumId;
    property GenreId: word read FGenreId;
end;

Соответственно, метод Parse может быть таким:

procedure TVKAudio.Parse(AJSONObject: TJSONObject);
const
  cPairs: array [0..8]of string = ('id','owner_id','artist','title','duration','url','lyrics_id','album_id','genre_id');
var Enums: TJSONPairEnumerator;
begin
  if not Assigned(AJSONObject) then Exit;
  Enums:=AJSONObject.GetEnumerator;
  try
    while Enums.MoveNext do
      begin
        case StrIndex(Enums.Current.JsonString.Value,cPairs) of
          0:Fid:=TJSONNumber(Enums.Current.JsonValue).AsInt64;//'id'
          1:FOwnerId:=TJSONNumber(Enums.Current.JsonValue).AsInt64;//'owner_id'
          2:FArtist:=Enums.Current.JsonValue.Value;//'artist'
          3:FTitle:=Enums.Current.JsonValue.Value;//'title'
          4:FDuration:=TJSONNumber(Enums.Current.JsonValue).AsInt;//'duration'
          5:FUrl:=Enums.Current.JsonValue.Value;//'url'
          6:FLyricsId:=TJSONNumber(Enums.Current.JsonValue).AsInt;//'lyrics_id'
          7:FAlbumId:=TJSONNumber(Enums.Current.JsonValue).AsInt;//'album_id'
          8:FGenreId:=TJSONNumber(Enums.Current.JsonValue).AsInt;//'genre_id'
        end;
      end;
  finally
    Enums.Free;
  end;
end;

Опять же как хранить список объектов аудиозаписей — личное дело каждого, а мы двигаемся далее.

Как скачать музыку ВКонтакте?

Думаю, что после того как мы получили список всех аудиозаписей пользователя и разобрали его по отдельным элементам вопроса о том как скачать песню из ВК возникнуть не должно. Есть прямая ссылка на mp3, есть Delphi. В Delphi есть Indy с компонентом idHTTP — берем компонент, выполняем метод GET на URL mp3-файла в ВК и сохраняем ответ в файл с расширением .mp3. Всё. Более мне добавить тут нечего.

Как слушать музыку из ВКонтакте в своей программе?

А вот этот вопрос уже по-интереснее. Можно, конечно, сохранять сначала музыку из VK на диск, а потом открывать в проигрывателе, но это не наш метод — лучше играть сразу с сервера. Как можно реализовать потоковое воспроизведение аудио в Delphi?

Хорошую наводку на решение дал автор блога devdelphi.ru — использовать библиотеку BASS. По ссылке находится небольшая статья на тему реализации интернет-радио с использованием bass.dll. Здесь я не буду копипастить код с другого блога, просто скажу, что точно таким же способом, как рассказано в статье, можно реализовать и проигрывание музыки из ВКонтакте. Лучше приведу полезные ссылки, которые могут вам пригодиться:

1. Официальный сайт библиотеки BASS. Здесь вы найдете как саму bass.dll, так и готовые модули Delphi для работы с библиотекой
2. BASS Simple. Сайт для тех кому BASS «из коробки» покажется сложным. Здесь автор разрабатывал свои собственные классы для удобной работы с bass.dll. Довольно интересные решения для работы с bass.dll

Заключение

Сегодня мы научились получать список аудиозаписей пользователя ВКонтакте и рассмотрели вопросы, касающиеся скачивания музыки из ВК и её потокового воспроизведения в Delphi. У API есть ограничение по количеству запрашиваемых записей, но с этим пока ничего не поделаешь. Теперь можете начинать свои «качалки» музычки из ВКонтактика.

Будут вопросы — пишите. Постараюсь ответить.