Недавно Яндекс объявил о запуске свого облачного сервиса под названием Яндекс.Диск. А буквально пару дней назад и Google запустил свой Google Drive. У меня была возможность поработать с обоими этими сервисами и оценить их удобство/полезность для себя. Надо сказать, что при выборе тех или иных онлайн-сервисов я, обычно, выбирал сервисы от Google (Календарь, Почта, соц.сеть и т.д.), но в случае с облачными сервисами я пока больше склоняюсь к использованию сервиса от Яндекс. По большей части такой выбор был сделан на основе изучения двух документов: API Яндекс.Диска и SDK Google Drive. Google в очередной раз "порадовал" ограничениями на использование API и набором методов API - есть методы добавления, редактирования и получения данных по файлам, но почему-то отсутствуют методы для удаления...странно как-то. Можно было бы привести ещё несколько причин моего выбора, но к статье эти причины не имеют никакого отношения. Яндекс в плане API оказался более дружелюбным к разработчикам - никаких ограничений, доступ к методам через Basic- или OAuth-аутентификацию (по выбору) и никаких "наворотов" в API - только методы и возможности WebDAV. Надеюсь, что Яндекс после окончания бетта-тестов Диска не переделает API и то, что будет рассказано и показано ниже будет работать ещё долго. Итак, сегодня продолжим речь о замечательной библиотеке Synapse и посмотрим как можно работать с протоколом WebDAV на примере API Яндекс.Диска.
Что представляет из себя протокол WebDAV? Вот небольшая выдержка из Вики:
WebDAV (Web-based Distributed Authoring and Versioning) - защищённый сетевой протокол высокого уровня, работающий поверх HTTP для доступа к объектам и коллекциям.
WebDAV расширяет HTTP следующими командами:
- PROPFIND - Получение свойств объекта на сервере в формате XML. Так же можно получать структуру репозитория (дерево каталогов).
- PROPPATCH - Изменение свойств за одну транзакцию.
- MKCOL - Создать коллекцию объектов (каталог в случае доступа к файлам)
- COPY - Копирование из одного URI в другой
- MOVE - То же что и предыдущий, только перемещение
- LOCK - Поставить блокировку на объекте. WebDAV поддерживает эксклюзивные и общие (shared) блокировки
- UNLOCK - Снять блокировку с ресурса
А раз WebDAV - это надстройка над HTTP(S), то нам никто не мешает использовать для этого давно уже нам известный класс THTTPSend. Все, что от нас требуется при подготовке к работе - это немного вспомнить про работу с https в Synapse, ну и, если необходимо, освежить в памяти работу с GZip. Так как WebDAV передает всю мета-информацию по документам в виде XML, то дополнительно нам может потребоваться какая-нибудь библиотека для работы с XML - обычный MSXML, NativeXML и т.д.
Примечание: если ищите быстрый парсер XML - почитайте эту статью в блоге Teran'а - там есть хорошая табличка сравнения скорости работы различных XML-парсеров
Теперь приступим к работе. Создадим в Delphi проект VCL Application, подключим в uses модули Synapse:
- httpsend,
- synacode,
- ssl_openssl
И на главной форме разместим следующие компоненты (см. рисунок):
Для доступа к методам API будем использовать простую Basic-аутентификацию. Так как в каждый запрос мы должны будем вставлять заголовок аутентификации, то напишем свой небольшой класс для работы с API. В принципе, можно было бы обойтись пока и без класса, но лишним, думаю, он не будет. Итак, заготовка класса для работы с WebDAV через THTTPSend будет такой:
type
TWebDAVSend = class
private
FHTTP : THTTPSend;
FToken: AnsiString;
FPassword: string;
FLogin: string;
procedure SetLogin(const Value: string);
procedure SetPassword(const Value: string);
procedure SetToken;
public
constructor Create;
destructor Destroy; override;
property Login: string read FLogin write SetLogin;
property Password: string read FPassword write SetPassword;
end;
{ TWebDAVSend }
constructor TWebDAVSend.Create;
begin
inherited;
FHTTP:=THTTPSend.Create;
end;
destructor TWebDAVSend.Destroy;
begin
FHTTP.Free;
inherited;
end;
procedure TWebDAVSend.SetToken;
begin
FToken:=EncodeBase64(FLogin+':'+FPassword);
end;
procedure TWebDAVSend.SetLogin(const Value: string);
begin
FLogin := Value;
SetToken;
end;
procedure TWebDAVSend.SetPassword(const Value: string);
begin
FPassword := Value;
SetToken;
end;Теперь попробуем реализовать несколько методов WebDAV. Первое, что нам необходимо - это определить какие каталоги имеются в Яндекс.Диске. Для этого нам надо реализовать в классе метод API PROPFIND. Согласно документации API, набор файлов и каталогов, свойства которых должны содержаться в ответе, определяется заголовком Depth со следующими поддерживаемыми значениями:
- 0 - запрашиваются свойства файла или каталога, непосредственно указанного в запросе.
- 1 - запрашиваются свойства каталога, а также всех элементов, находящихся на первом уровне каталога.
В результате запроса сервер ответит нам XML-документом, содержащим необходимые нам свойства. Реализация PROPFIND в нашем классе будет такой:
function TWebDAVSend.PROPFIND(Depth: integer; const Element: String): string;
begin
with FHTTP do
begin
Headers.Clear;
Document.Clear;
Headers.Add('Authorization: Basic ' + FToken);
Headers.Add('Depth: ' + IntToStr(Depth));
Headers.Add('Accept: */*');
if HTTPMethod('PROPFIND', GetRequestURL(Element)) then
result := ReadStrFromStream(Document, Document.Size)
else
raise Exception.Create(rsPropfindError+' '+ResultString);
end;
end;Рассмотрим работы этой функции. Вначале мы очищаем заголовки и тело от данных, полученных в предыдущем запросе, если таковой был. После этого вставляем заголовок аутентификации, указываем "глубину просмотра" в заголовке Depth. Затем, выполняем запрос PROPFIND на сервер и здесь вам встречается неизвестная функция GetRequestURL.
Функция GetRequestURL получает корректный URL. В качестве параметра задается любой действительный путь в дереве каталогов и файлов. К примеру, в параметре функции я могу задать такую строку:
Documents/Мои статьи/Delphi/Работа с API Яндекс.Диска.doc
И функция вернет мне URL, который гарантированно примет сервер. GetRequestURL выглядит следующим образом:
const
cWebDAVServer = 'https://webdav.yandex.ru/';
function TWebDAVSend.GetRequestURL(const Element: string): string;
var URI: string;
begin
URI:=Element;
if URI[1]='/' then
Delete(URI,1,1);
Result:=cWebDAVServer+EncodeUTF8URI(URI);
end;Здесь, опять же, встречается ещё одна непонятная функция - EncodeUTF8URI. Эта функция проводит кодирование URI, который может содержать символы в кодировке UTF-8. Выглядит функция так:
function TWebDAVSend.EncodeUTF8URI(const URI: string): string;
var
i: integer;
Char: AnsiChar;
begin
result := '';
for i := 1 to length(URI) do
begin
if not(URI[i] in URLFullSpecialChar) then
begin
for Char in UTF8String(URI[i]) do
Result:=Result+'%'+IntToHex(Ord(Char), 2)
end
else
Result:=Result+URI[i];
end;
end;URLFullSpecialChar - это множество, которое описано в модуле synacode.pas Synapse:
URLFullSpecialChar: TSpecials = [';', '/', '?', ':', '@', '=', '&', '#', '+'];
Вполне возможно, что можно было бы как-нибудь обойтись методами Synapse типа EncodeURLElement, но для строки "Библиотека" эта функция выдавала такую строку:%C1%E8%E1%EB%E8%EE%F2%E5%EA%E0
вместо такой:%D0%91%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA%D0%B0
поэтому я, долго не заморачиваясь, написал свою маленькую функцию кодирования. Она может и не идеальна, но сервер Яндекс.Диска отвечал правильно. Так...с чего мы начали? Ах да - с TWebDAVSend.PROPFIND. Так вот, если запрос проходит успешно, то дальше мы просто считываем строку из тела запроса (Document), а если была какая-либо ошибка - показываем её пользователю.
В результате выполнения TWebDAVSend.PROPFIND сервер может ответить следующим образом:
- Если запрос обработан успешно - возвращается XML-документ, содержащий свойства элемента(-ов)
- Если был задан не верный элемент, то вернется строка, содержащая описание ошибки.
Пример успешно выполненного запроса PROPFIND показан на рисунке ниже:
Пример с неправильно заданным элементом (сервер возвращает код 200 и описание ошибки):
Про метод PROPFIND стоит также добавить, что имя каталога на сервере может не совпадать с представлением этого каталога в URL. Например, каталог "Музыка" в URL представляется как "Music". Чтобы понять как должен выглядеть URL для получения свойств какого-либо каталога необходимо смотреть на свойство 'href' в XML-документе. Список всех свойств, поддерживаемых в рамках протокола WebDAV приведен в разделе описания протокола DAV Properties.
Аналогично методу PROPFIND можно реализовать и другие методы для работы с WebDAV в Synapse. Все методы рассматривать, думаю, смысла нет - алгоритм работы практически неизменный: вставили заголовки аутентификации, собрали URL, отправили запрос, обработали ответ. Но, для полноты картины, рассмотрим ещё один метод WebDAV - MKCOL. В отличие от предыдущего, этот метод не возвращает ничего в теле ответа, а об успешности выполнения запроса можно судить по ResulCode. Итак, чтобы создать на сервере новую коллекцию, мы будем использовать в нашем классе такую функцию:
function TWebDAVSend.MKCOL(const ElementPath: string): boolean;
begin
Result:=False;
with FHTTP do
begin
Headers.Clear;
Document.Clear;
Headers.Add('Authorization: Basic ' + FToken);
Headers.Add('Accept: */*');
if HTTPMethod('MKCOL', GetRequestURL(ElementPath)) then
begin
Result:=ResultCode=201;
if not Result then
raise Exception.Create(IntToStr(ResultCode)+' '+ResultString);
end
else
raise Exception.Create(rsPropfindError+' '+ResultString);
end;
end;Пример использования MKCOL:
MKCOL('Documents/Новая папка с документами');В результате в каталоге Documents будет создан новый с названием "Новая папка с документами". Следует отметить, что согласно протоколу WebDAV, в результате одного запроса может быть создан только один каталог. Если приложение отправляет запрос о создании каталога a/b/c/, а в каталоге a/ нет каталога b/, то сервис не создает каталог b/, а отвечает c кодом 409 Conflict.
Вот, пожалуй, кратко о том как можно реализовать работу с WebDAV в Synapse и использовать API Яндекс.Диска в своих Delphi-приложениях. Исходник проекта, рассмотренного в статье Вы всегда сможете скачать со страницы с исходниками (раздел по Delphi XE2) и, при необходимости, дописать реализацию других методов API.