Wrzasq.pl

Allegro WebAPI tutorial vol. 1

Monday, 21 July 2008, 06:17

Co to WebAPI i z czym to się je?

WebAPI to usługa sieciowa udostępniona przez Allegro umożliwiająca wykonywanie operacji na swoim koncie przez protokół SOAP. SOAP jest bardzo wygodnym sposobem zdalnego wykonywania operacji - umożliwia on mapowanie wywołań interfejsu programistycznego po stronie klienta (naszej) na wywołania po stronie serwera. W praktyce wygląda to tak, jakbyśmy mieli zasoby allegro na naszej maszynie i bezpośrednio na nich pracowali (w rzeczywistości wszystkie wywołania są przesyłane w postaci zwykłych pakietów - SOAP oparty jest na XMLu, po czym wykonywanie po stronie serwera - w tym wypadku Allegro, a następnie rezultaty tych operacji są z powrotem przesyłane sieciowo i zwracane jako wyniki naszych wywołań).

Na wstępie ostudzę nieco zapędy - WebAPI niestety nie oferuje zbyt wiele ciekawych funkcji. W praktyce dostajemy jedynie formularze ze stron Allegro w wersji bardziej przystępnej dla programisty, a szkoda, bo tego typu rozwiązania dają możliwość jakiejś większej interakcji między skryptami. No ale rozwiązanie to jest mimo wszystko niezwykle przydatne, na przykład do automatycznego eksportu produktów z naszego sklepu na Allegro.

Jednak WebAPI ma jedną wielką wadę - dokumentację, a konkretniej jej niemal całkowity brak. Całość ogranicza się jedynie do jałowego spisu wywołań, oraz typów danych generowanego zapewne automatycznie. Nie ma żadnego tutoriala, a sam opis funkcji i wszelkich wartości (typu stałe) ogranicza się zazwyczaj do jednego zdania, z którego na dodatek trzeba się domyślać "co autor miał na myśli". Ja z WebAPI styczność miałem jedynie przy okazji współpracy z 4DeeJays group, ale i tak musiałem sobie poradzić z masą niedogodności i pułapek, dlatego postanowiłem co nieco napisać, żeby ułatwić życie innym (nie znalazłem do tej pory w Internecie żadnego artykułu na temat Allegro WebAPI, który by jakoś pomagał programistom w tworzeniu aplikacji). Podstawowe dwa miejsca, w których można znaleźć przynajmniej cząstkowe informacje to już wspomniana dokumentacja: http://webapi.allegro.pl/uploader.php, oraz forum: http://allegro.pl/phorum/list.php?f=327.

Warsztat pracy

Zanim zacznę pisać jak korzystać z WebAPI w naszym kodzie, ważną rzeczą jest zrobienie sobie konta w serwisie testowym: testwebapi.pl. Jest to strona na której jest uruchomiona kopia Allegro wraz z usługą WebAPI i na której można bez konsekwencji testować kod, przez co możemy sprawdzić go w warunkach zbliżonych do tych z prawdziwego serwisu, zanim narazimy się na konsekwencje finansowe na prawdziwych aukcjach. Niestety tutaj już pierwsza uwaga - są to warunki jedynie zbliżone i często będzie trzeba uważać na różnice, chociażby w kategoriach, czy polach formularzy. Niemniej jest to na pewno dobra rzecz pozwalająca znaleźć przynajmniej ogólne błędy w naszej aplikacji. Poza kontem do testowania niezbędny będzie nam też klucz do WebAPI - klucz jest darmowy, zostaje nam przydzielony na rok po wypełnieniu zgłoszenia pod adresem: http://allegro.pl/contact/contact.php?topic=288. Po roku oczywiście możemy uzyskać następny klucz. Więcej informacji znajdziesz na stronach Allegro.

Jeśli chodzi o platformę do pracy, to będę opisywał pracę w PHP5, ale należy pamiętać, że SOAP to po prostu protokół internetowy, więc można z niego korzystać w dowolnym niemal środowisku od C po Pythona, Jave i tym podobne. Oczywiście również w starszej wersji - PHP4, można wykorzystywać SOAP, ale w końcu nie będziemy "rzeźbić w gównie" ;).

Do obsługi samego protokołu SOAP w PHP5 twórcy WebAPI polecają biblioteke NuSOAP, a podobnych bibliotek jest jeszcze sporo, jednak w PHP5 mamy przecież dostępną i bardzo wygodną obsługę SOAP i to właśnie na niej opieram swoje pracę, oraz ten tutorial. Biblioteka NuSOAP może się wam jednak przydać w momencie, gdy nie macie zainstalowanego rozszerzenia SOAP, ani możliwości jego aktywacji (na przykład zewnętrzny hosting). Sama logika kodu pozostaje jednak niezmienna niezależnie od zastosowanego rozwiązania, więc nie powinno być wiele problemów z ewentualną przesiadką.

Praca z samym SOAPem z wykorzystaniem PHP nie jest trudna. Dzięki wsparciu dla WSDL i udostępnieniu opisu Allegro WebAPI w tymże formacie cały proces obsługi protokołu jest zupełnie zautomatyzowany. Nam pozostaje jedynie wykorzystywać wywołania. Na początek przyda się stowrzyć obiekt klienta, na którym będziemy wykonywać operacje:

/**
 * @see http://www.php.net/manual/en/book.soap.php
 * @author Wrzasq <wrzasq@gmail.com>
 * @copyright 2008 (C) by Wrzasq
 */
class WebAPISoapClient extends SoapClient
{
/**
 * Kraj - Polska.
 */
    const COUNTRY_PL = 1;
/**
 * Logowanie do serwisu testwebapi.pl.
 */
    const COUNTRY_TESTWEBAPI = 228;

/**
 * Zapytanie o wersję Allegro WebAPI.
 */
    const QUERY_ALLEGROWEBAPI = 1;

/**
 * Automatycznie tworzy klienta dla interfejsu Allegro WebAPI.
 */
    public function __construct()
    {
        parent::__construct('http://webapi.allegro.pl/uploader.php?wsdl');
    }
}

Główny z użytek tej klasy będzie polegał właśnie na grupowaniu stałych, których w WebAPI niemal na pewno będziemy wykorzystywać całe mnóstwo.

Jak czytać dokumentację

Od tej pory na instancji klasy SoapClient (lub naszej pochodnej WebAPISoapClient) możemy wykonywać operacje SOAP. Czytając dokumentacje należy po prostu sprawdzać nazwę wywołania, oraz listę argumentów. Samo odwołanie się w naszym przypadku wygląda tak, jakbyśmy wykorzystywali interfejs napisany w PHP (dzięki przeciążonym metodą klasy SoapClient), a więc jako nie trudno zauważyć w porównaniu do komentarzy użytkowników z dokumentacji nasz kod będzie bardziej czytelny i elegancki. Dodatkowo należy zwrócić uwagę na rodzaj zmiennych. O ile typy tablicowe nie będą problemem, o tyle ciekawie jest z typami obiektowymi, ponieważ nazwy pola zostały dość niefortunnie nazwane z wykorzystaniem myślników, a więc odwoływać się do pól obiektów będzie trzeba (na przykład) w taki sposób:

$pole = $obiekt->{'nazwa-pola'};

Na dodatek w rodzajach pól/argumentów jest pewna pułapka w postaci typu base64. Dane przesyłane jako wartość takiego parametru są zakodowane z użyciem base64, ale tutaj trzeba być ostrożnym. W zależności o tego jakiej biblioteki używamy takie kodowanie będzie wykonywane automatycznie, lub nie. Ponieważ informacja o takim typie jest przekazywana w WSDLu biblioteka ma możliwość jego rozpoznania i wiele z nich to czyni. Ponieważ robi tak również biblioteka SOAP z PHP (a także NuSOAP o ile mi wiadomo), to dane typu base64 będą dla nas zwykłym stringiem, ponieważ ich kodowaniem/rozkodowaniem zajmie się biblioteka kliencka.

Oprócz tego warto zwrócić uwage, że każde wywołanie może zwracać kod błędu. Jeśli zdecydujecie sie na proponowane przeze mnie rozwiązanie z wbudowaną obsługą SOAP błędy wywołań będą skutkować pojawieniem się wyjątków, więc warto się zaznajomić z obsługą wyjątków w PHP.

Pierwsze kroki - logowanie

Ponieważ trochę mi się wstęp przedłużył to nie będę rozpisywał się dalej, niż na razie tylko do logowania. Może potem znajdę czas na opisanie procesu dodawania produktów. Do logowania się potrzebujemy loginu, hasła, klucza WebAPI, oraz klucza wersji. Pierwsze trzy wartości są oczywiste, ale czym jest ta ostatnia? Otóż za każdym razem, gdy w interfejsie WebAPI jest wprowadzana jakaś zmiana, zmienia się też numer wersji. Dotyczy to praktycznie każdej nawet najmniejszej zmiany. Wersję API będzie trzeba podawać niemal przy każdym wywołaniu, a ma to zapewne na celu upewnienie się, że oprogramowanie klienckie jest kompatybilne z daną wersją Allegro WebAPI. Jednak problem w tym, że tak jak juz wspomniałem wersja zmienia się przy każdym updacie i nawet jeśli zmieniono tylko sposób zwracania informacji o niesprzedanych przedmiotach w sklepach, to nam uniemożliwi to nawet zalogowanie. Istnieje jednak możliwość pobrania aktualnego numeru, więc jeśli nasz skrypt nie będzie wykorzystywał WebAPI w dużym stopniu, a jedynie ograniczy się do pewnych podstawowych czynności, to możemy sobie pozwolić na automatyzację tego procesu. Oprócz tego przy logowaniu określamy serwis do którego chcemy się zalogować (Allegro WebAPI jest dostępne również w zagranicznych serwisach Aukro i TeszVesz, także wspomnianym już serwisie testowym). Po zalogowaniu, jak nie trudno się domyślić zostanie nam zwrucony identyfikator sesji, który z kolei dalej będziemy wykorzystywali w naszych operacjach. Niestety tutaj kolejne moim zdaniem niedociągnięcie WebAPI - mimo iż podajemy dane przy logowaniu, za każdym następnym razem musimy dalej podawać swój klucz WebAPI (to jeszcze mogę zrozumieć), oraz klucz wersji (to już jest dla mnie niezrozumiałe - przecież można go przypisać do otwartej sesji po stronie serwera), no ale cóż poradzić… Do zalogowania się służy wywołanie doLogin(), natomiast numer wersji pobieramy wykorzystując doQuerySysStatus(), które służy również do pobierania innych informacji. Jeśli dbamy o bezpieczeństwo, możemy zamiast dandardowego logowania wykorzystać doLoginEnc() gdzie hasło zamiast w surowej postaci, jest przesyłane jako skrót SHA-256, jednak w samym PHP nie ma funkcji generującej taki hash, a nie każdy ma rozszerzenie Mhash. Skoro już teorię mamy za sobą, to oto jak to wygląda w praktyce:

// nasze dane
$config = array(
    'login' => 'twój login',
    'password' => 'twoje hasło',
    'apiKey' => 'twój klucz Allegro WebAPI'
);

// dla serwisu testowego wybierz WebAPISoapClient::COUNTRY_TESTWEBAPI
$country = WebAPISoapClient::COUNTRY_PL;

try
{
    $client = new WebAPISoapClient();
    // pobieranie wersji WebAPI
    $version = $client->doQuerySysStatus(WebAPISoapClient::QUERY_ALLEGROWEBAPI, $country, $config['apiKey']);
    // właściwe logowanie do serwisu
    $session = $client->doLogin($config['login'], $config['password'], $country, $config['apiKey'], $version['ver-key']);
}
catch(SoapFault $soapFault)
{
    /* obsługa wyjątku */
}
Część III
Część IV
Część V
Część VI

Tags: Code, Tutorial, Allegro, WebAPI, PHP, SOAP