Работа с API Sape в PHP для новичков

Мой первый топик на форуме, пинайте нестрого, пожалуйста :) Поиском подобное не нашёл.

Пост предназначен для тех, кто "оптимизатор" на сапе и кому нужно быстро написать обработчик апи на php, с реальными примерами, при этом совершенно не вдаваясь в подробности. Тем, кто хочет покопаться, пост будет удобен как трамплин :)

Итак. Некоторое время назад мне понадобилось анализировать ссылки для своих проектов, купленные на Sape. Так как у Sape есть вполне приличный API (http://www.sape.ru/api_xmlrpc.php?v=extended), решил использовать его, а не парсить страницы. Забегая вперёд, скажу, что для моих целей его хватило полностью.

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

Для того, чтобы работать с API, необходима библиотека, понимающая XML-RPC (по большому счёту, вам ничего и не нужно знать об этой аббревиатуре, так как в итоге вы будете получать при запросе к сапе обычные php-массивы). Я выбрал самую легкую и простую XML-RPC for PHP - http://phpxmlrpc.sourceforge.net/.

Скачиваем архив по ссылке и распаковываем на хостинг.

Затем просто начинаем с помощью библиотеки работать с Sape.

Подключаем библиотеку (всё общение с сапой и результаты будут в уникоде):

include_once($_SERVER["DOCUMENT_ROOT"]."/xmlrpc-2.2.2/lib/xmlrpc.inc");
$GLOBALS['xmlrpc_defencoding'] = "UTF8";
$GLOBALS['xmlrpc_internalencoding'] = "UTF-8";

Создаём объект:

$client = new xmlrpc_client("/api_xmlrpc.php?v=extended", "xmlrpc.sape.ru", 80);

Если хотим видеть, что будет отвечать Сапа в ответ на наши запросы, раскомментируем строку:

//	$client->setdebug(2);

Логинимся в сапу:

$msg = new xmlrpcmsg("sape.login", array(
	new xmlrpcval($login, "string"),
	new xmlrpcval($password, "string"),
	new xmlrpcval(true, "boolean") // шлём в md5
));

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

Я гоняю пароли между моим сервером и сапой только в md5, чего и вам советую. Для этого с помощью простецкого скрипта на php получаем из строки пароля его md5-хеш

<?
echo md5('мой-клёвый-и-секурный-пароль');
?>

и загоняем его в переменную $password.

Есть одна тонкость: иногда сапе плохо и она может не выполнить ваш запрос. Для победы этой проблемы пробуем при ошибочном результате пнуть её три раза (вероятность успеха повышается):

for($i=0;$i<3;$i++)
{
	$resp=$client->send($msg);
	if(!$resp->faultCode())
	{
		$ret = php_xmlrpc_decode($resp->value());
		break;
	}
	sleep(1);
}

Залогинились, едем дальше. Один тонкий момент - нужно при любом запросе к сапе передавать куки, которые были получены при логине. У меня в коде это есть, можно не париться. Но всё-равно, учтите.

Сохраняем куки, полученные от Сапы:

$cookies = $resp->cookies();
$client->setcookie('SAPE', $cookies["SAPE"]["value"], $cookies["SAPE"]["path"], $cookies["SAPE"]["domain"]);

Теперь я расскажу о использовании некоторых функций API Сапы, например получении или удалении списка проектов, ваших урлов в проектах, ссылок для этих урлов.

Получаем все проекты вашего аккаунта:

$msg = new xmlrpcmsg("sape.get_projects", array(new xmlrpcval(false, "boolean")));

for($i=0;$i<3;$i++) // знакомый код, пробуем три раза, если возникают ошибки со стороны сапы
{
	$val=$client->send($msg);
	if(!$val->faultCode())
	{
		$projects = php_xmlrpc_decode($val->value());
		break;
	}
	sleep(1); // не спешим и не ддосим любимую сапу, ждём секунду
}

В массиве $projects будут все ваши проекты. Какие внутри поля - можно посмотреть в документации API Сапы или сделать var_dump($projects);

Как получить список ваших урлов внутри отдельного проекта (в примере - для первого в списке проекта):

$msg = new xmlrpcmsg("sape.get_urls", array(
			new xmlrpcval($projects[1]["id"], "int"),
			new xmlrpcval(false, "boolean")
));
for($i=0;$i<3;$i++)
{
	$val=$client->send($msg);
	if(!$val->faultCode())
	{
		$project_urls = php_xmlrpc_decode($val->value());
		break;
	}
	sleep(1);
}

В $project_urls теперь лежат все урлы для выбранного проекта.

Как теперь получить самое вкусное - ссылки для вашего сайта, которые вы напокупали в Сапе:

$msg = new xmlrpcmsg("sape.get_url_links", array(
		new xmlrpcval($project_urls[1]["id"], "int"), // здесь указан первый урл, вместо единицы вставляйте нужный вам индекс
		new xmlrpcval("", "string"),
		new xmlrpcval("", "string"),
		new xmlrpcval("", "string"),
		new xmlrpcval($page, "int")
	));

for($i=0;$i<3;$i++)
{
	$val=$client->send($msg);
	if(!$val->faultCode())
	{
		$url_links = php_xmlrpc_decode($val->value());
		break;
	}
	sleep(1);
}

В массиве $url_links будут все купленные ссылки для выбранного сайта одного из выбранных проектов.

Отдельного замечания стоит переменная $page - номер страницы результатов из списка ссылок. Можно передавать ноль и на сколько помню, вернется результат со всеми ссылками, но лучше так не делать, а запрашивать небольшими порциями. Так надежнее. В одной странице, если правильно помню, выдаётся 500 результатов.

Как удалить пачку купленных ссылок:

$for_delete = array(1, 2, 3); // вместо 1, 2, 3 вбивайте полученные вами от сапы ID ссылок.
foreach($for_delete as $key => $value)
{
    $deleted_IDs[] = new xmlrpcval($value, 'int');
}
$msg = new xmlrpcmsg("sape.placements_delete", array(new xmlrpcval($deleted_IDs, "array")));

Весь приведённый код - реальный, я только убрал лишнее типа сохранения в базу и поменял имена переменных и пути, надеюсь, нигде не опечатался :)

А как использовать полученные знания - думаю, вы догадаетесь сами.

Если что-то осталось непонятным или неясно, как использовать какую-то функцию или вы заметили ошибки - спрашивайте и комментируйте.

Спасибо за внимание.