Pamiętaj, wkrótce wyłączymy WebAPI!

Podstawowym i rozwijanym API Allegro jest REST API. Skorzystaj z niego, jeśli tworzysz nową aplikację lub myślisz o rozwoju obecnej. WebAPI to stare rozwiązanie, które utrzymujemy głównie z uwagi na kompatybilność wsteczną z istniejącymi aplikacjami. Nie rozwijamy go już i planujemy jego wyłączenie. Wszelkie nowe funkcjonalności wdrażamy tylko na REST API.

Harmonogram wygaszania poszczególnych metod WebAPI znajdziesz tutaj.

Allegro WebAPI

Interfejs programistyczny platformy Allegro

Tutoriale

< < Powrót do listy tutoriali

Wprowadzenie do Allegro WebAPI

Wykorzystane technologie: PHP
Data dodania: 31 marca 2010
Ostatnia aktualizacja: 5 marca 2020

Podstawowym i rozwijanym API Allegro jest REST API. Skorzystaj z niego, jeśli tworzysz nową aplikację lub myślisz o rozwoju obecnej. Wszelkie nowe funkcjonalności wdrażamy tylko na REST API, i tylko w nim udostępniamy wszelkie nowe funkcjonalności.


Wstęp do wstępu


Allegro WebAPI - co to właściwie jest? Jest to usługa oferowana przez Allegro umożliwiająca korzystanie z mechanizmów portalu aukcyjnego z poziomu kodu programu komputerowego. Zakładam, że jeśli ktoś się bierze za korzystanie z usług sieciowych, czy ogólnie za tworzenie rozwiązań dotyczących sprzedaży, obracania pieniędzmi, to z samym programowaniem styczność już miał. Jednak usługi sieciowe same w sobie są dość specyficznym tematem, dlatego zanim przejdę do sedna sprawy, trochę teorii. Dla programisty korzystanie z bibliotek takich, jak Allegro WebAPI wygląda niemalże identycznie jak z normalnych bibliotek, które znajdują się w systemach operacyjnych, ale istnieje dość zasadnicza różnica w tym, jak funkcjonują one wewnętrznie.


Co programista widzi w kodzie

Rysunek 1: Co programista widzi w kodzie

 

Kluczową kwestią jest to, że wszelkie operacje związane z logiką działania danej usługi są wykonywane na zdalnym serwerze, w naszym przypadku jest to serwer Allegro. W samym pisaniu kodu nie robi to różnicy, ale przy projektowaniu aplikacji nie można o tym zapomnieć - oznacza to, że nie mamy wpływu na samą bibliotekę. Trzeba też pamiętać, że pod każdym wywołaniem metody WebAPI w rzeczywistości kryje się cały proces komunikacji klient-serwer, musimy zatem uwzględnić czas potrzebny na przesłanie danych (co nierzadko, szczególnie przy dużych porcjach, stanowi czas o wiele większy, niż same operacje na tych danych).


Co się w rzeczywistości dzieje

Rysunek 2: Co się w rzeczywistości dzieje




Podstawowe informacje


RPC - Remote Procedure Call, ang. zdalne wywołanie procedury; mechanizm pozwalający na wywołanie procedur udostępnionych przez serwer.
SOAP - protokół typu RDP oparty na XML-u. To jego wykorzystujemy łącząc się z Allegro WebAPI.
WSDL - Web Services Desription Language, ang. język opisu usług sieciowych. To język umożliwiający poinformowanie kodu klienckiego o tym, jakie procedury udostępnia serwer usługi. Allegro WebAPI posiada definicję zapisaną w tym formacie.

Ramka 1: Ważniejsze definicje

Usługa jest realizowana przy pomocy protokołu SOAP, który można łatwo wykorzystywać w wielu najpopularniejszych środowiskach i który posiada szerokie wsparcie w postaci dostępnych wielu dodatkowych bibliotek i programów. Oprócz tego dostępna jest też definicja usługi w formacie WSDL, dzięki czemu proces korzystania z usługi w kodzie programu jest jeszcze bardziej automatyczny i mniej problematyczny. Dokument WSDL dla Allegro WebAPI znajduje się pod adresem https://webapi.allegro.pl/service.php?wsdl. Najczęściej wystarczy ten adres przekazać odpowiedniemu programowi lub zainicjować nim bibliotekę w kodzie – w zależności od języka proces inicjalizacji będzie przebiegać w różnej formie. W przypadku języków kompilowanych najczęściej mamy do dyspozycji narzędzie, które na podstawie specyfikacji w formacie WSDL wygeneruje pliki źródłowe, a w przypadku języków interpretowanych, jak na przykład PHP, wszystko będzie się działo "w locie".


Metodyka

Fakt, że usługi sieciowe są udostępniane przez zdalne serwery, które samodzielnie wykonują zadane operacje daje im wielką zaletę - przenośność. De facto usługa tego typu (jak właśnie Allegro WebAPI) jest zupełnie niezależna od tego w jaki sposób i gdzie programista z niej korzysta. Można jej używać w dowolnym języku programowania, na dowolnej platformie sprzętowej i systemowej. Równie dobrze można tworzyć oprogramowanie biurkowe z wykorzystaniem platformy .NET, jak i serwerowe aplikacje w postaci sklepów internetowych w technologii PHP. Na dodatek w większości środowisk mamy wspomniane gotowe biblioteki do obsługi protokołu SOAP. W poradnikach będę prezentował przykłady użycia Allegro WebAPI w PHP5, ale (pomijając składnię i ewentualne zarządzanie pamięcią) sposób użycia jest dokładnie taki sam w każdym innym języku. PHP5 posiada standardowe rozszerzenie do obsługi SOAP, które jest bardzo wygodne i to z niego będę korzystał. Jeśli ktoś korzysta ze starszych wersji PHP niż wersja 5, bądź jego instalacja nie posiada tego rozszerzenia i nie ma możliwości jego doinstalowania zawsze może skorzystać z biblioteki NuSOAP. Tak, czy inaczej samo korzystanie z SOAP w większości przypadków nie jest problemem.


Dokumentacja

Allegro WebAPI posiada dokumentację techniczną, która znajduje się pod adresem http://www.allegro.pl/webapi/documentation.php. Zawiera ona listę wszystkich metod, listy ich parametrów, zwracanych wartości jak i typów danych używanych do tego celu. W tym miejscu wypada, abym napomknął o pewnej niedogodności - otóż w przypadku złożonych pól, tworzących obiekty (w większości przypadków będziemy mieli do czynienia z językami zorientowanymi obiektowo, albo przynajmniej obsługującymi tego typu programowanie, ale nawet, jeśli piszemy w C, to przez obiekt chcę wyrazić ogólny ustrukturyzowany zbiór elementów, a nie koniecznie pojęcie z zakresu programowania obiektowego) ich nazwy zazwyczaj składają się z więcej niż jednego wyrazu. W takim wypadku pola te posiadają w nazwie myślniki/minusy, co jest znacznym utrudnieniem w przypadku języków programowania (bierze się to z tego, że SOAP jest oparty na XML-u). Dlatego musimy się upewnić, jak w naszym środowisku tego typu nazwy będą funkcjonować, a możliwości jest kilka: w przypadku języków kompilowanych najczęściej będzie to oznaczało zmianę nazw na odpowiednią konwencję nazewnictwa jak camelCase (łączenie poszczególnych wyrazów i pisanie kolejnych z wielkich liter - na przykład fvalue-int zostanie zamienione na fvalueInt), albo zamianę myślników na inny separator (najczęściej znaku podkreślenia). Jednak niektóre języki, jak właśnie PHP posiada konstrukcję składniową pozwalającą na wykorzystanie takich pól bez żadnych zmian:

  1. $value = $field->{'fvalue-int'};


Jeszcze inaczej będzie to miało miejsce w przypadku standardowej obsługi usług sieciowych w środowisku Visual C# 2008 – tam znaki myślnika zostaną po prostu pominięte.


 
camelCase

Separator podkreślenia
(gSOAP)
Dostęp do zmiennej
(PHP5)
Usunięcie znaku
(Visual C# 2008)
fvalue-int fvalueInt fvalue_int {'fvalue-int'} fvalueint

Tabela 1: Różne konwencje nazewnictwa


Klucz WebAPI

Ostatnią rzeczą, o którą musimy się zatroszczyć przed rozpoczęciem pracy z Allegro WebAPI jest nasz klucz WebAPI. Będzie on nam potrzebny praktycznie w każdej linijce kodu, w której kierujemy jakieś zapytanie do serwera Allegro – to nasz klucz do całej usługi. Klucz jest przypisany do naszego konta i jest niezmienny (posiada czas ważności, ale nie ulega zmianie po przedłużeniu). Aby otrzymać nasz klucz należy skorzystać z formularza na stronie Allegro pod adresem http://www.allegro.pl/contact/contact.php?topic=288 i czekać na maila zwrotnego od obsługi serwisu. Nie powinno to trwać zbyt długo, zazwyczaj kilkanaście minut, jednak należy mieć na uwadze godziny pracy i dni wolne: jeśli zgłosimy się po klucz w piątek wieczorem, to klucz dostaniemy w poniedziałek późnym rankiem.




Dobre nawyki


Organizacja kodu

Nie chcę nikomu narzucać stylu programowania, ani tym bardziej samego kodu, ale myślę, że pewne rzeczy, nawet jeśli nie będą koniecznie w takim kształcie wykorzystane, mogą się okazać pomocne. Pierwszy aspekt, o który warto zadbać od razu to dostosowanie kodu do naszych potrzeb. Pamiętajmy, że dostępne biblioteki do obsługi SOAP nie dostosowują się do żadnej konkretnej usługi, jedynie umożliwiają korzystanie z niej. Dlatego warto samemu stworzyć chociaż najbardziej podstawowe udogodnienia. WebAPI w bardzo wielu miejscach wymaga użycia stałych wartości, więc dobrze jest mieć je posegregowane i ponazywane odpowiednio. Jako iż przykłady kodu będą prezentowane z użyciem PHP5, proponuję stworzyć sobie prostą (na razie) klasę dziedziczącą po SoapClient (o kwestiach związanych z konkretnymi elementami kod później), która zautomatyzuje wykonywanie niektórych czynności. Do klasy tej z czasem pewnie zaczniemy dodawać kolejne funkcjonalne elementy, jednak na początek ograniczę się tylko do prostej konstrukcji:

  1. class AllegroWebAPISoapClient extends SoapClient
  2. {
  3. // jedynka to kod kraju dla Polski, o tym dalej
  4. const COUNTRY_PL = 1;
  5.  
  6. const QUERY_ALLEGROWEBAPI = 1;
  7.  
  8. public function __construct()
  9. {
  10. parent::__construct('http://webapi.allegro.pl/uploader.php?wsdl');
  11. }
  12. }


Podobnie pracować możemy w przypadku języków kompilowanych - na przykład po wygenerowaniu kodu wyjściowego przez program gSOAP możemy dodać definicje stałych do jego plików nagłówkowych.

Druga sprawa to organizacja naszych danych dostępowych. Najwygodniej jest je trzymać w osobnym pliku konfiguracyjnym, albo nagłówkowym, bądź też na początku pliku z kodem wykonawczym. Najlepiej, aby były to stałe lub jeśli mamy zamiar wczytywać dane w czasie pracy programu - zmienne pogrupowane na przykład w formie tablicy asocjacyjnej. Przyjmijmy, że w dalszej części poradnika będziemy korzystać z następującego nazewnictwa:

  1. define('ALLEGRO_LOGIN', 'login');
  2. define('ALLEGRO_PASSWORD', 'hasło');
  3. define('ALLEGRO_KEY', 'klucz WebAPI');
  4. define('ALLEGRO_COUNTRY', AllegroWebAPISoapClient::COUNTRY_PL);



Obsługa błędów

Zanim przejdziemy do kolejnych etapów, ostatnim elementem dotyczącym podstaw komunikacji z samym WebAPI, a także sposobem tworzenia dobrego kodu jest obsługa błędów. Usługa Allegro wykorzystuje do tego SOAP w zakresie wyjątków. Dobrze jest zawczasu zaopatrzyć nasz kod w obsługę wyjątków, gdyż są one tutaj wyrzucane przy najmniejszych problemach/potknięciach (co jest zrozumiałe, gdyż taka, a nie inna filozofia działania usług sieciowych uniemożliwia nam ingerencje w przebieg procesu po stronie serwera, a więc o najmniejszych nieprawidłowościach chcemy być informowani - naprawdę chcemy). Błędy zwracane za pośrednictwem SOAP będą w przypadku wielu środowisk propagowane od najniższej warstwy obsługi tego protokołu bez żadnego obsłużenia aż do naszego kodu, tak więc jeśli nie będziemy pilnować obsługi wyjątków, nasza aplikacja będzie się "wykrzaczać" przy każdym potknięciu niezależnie, czy to naszym, czy po stronie Allegro, czy też "natury rzeczy martwych". O samą obsługę błędów będziemy się martwić w konkretnych przypadkach, a filozofia obsługi wyjątków to temat rozległy na kilka ładnych tomów projektowania oprogramowania, więc tutaj go wykładać nie będę. Przestawię za to podstawową składnie, która będzie potrzebna do obsługi nieprzewidzianych sytuacji (na razie pomińmy istotę samych metod WebAPI):

  1. try
  2. {
  3. $client = new SoapClient('http://webapi.allegro.pl/uploader.php?wsdl');
  4. $version = $client->doQuerySysStatus(1, 1, 'klucz WebAPI');
  5. $session = $client->doLoginEnc('login', base64_encode( hash('sha256', 'hasło', true) ), 1, 'klucz WebAPI', $version['ver-key']);
  6. }
  7. catch(SoapFault $error)
  8. {
  9. echo 'Błąd ', $error->faultcode, ': ', $error->faultstring, "n";
  10. }


Jak widać błędy wyrzucane są jako obiekty klasy SoapFault. Konkretne kody błędów, czyli wartości pola $error->faultcode widoczne są w dokumentacji przy każdej metodzie WebAPI. Pole to zawiera łańcuch znaków, a więc nie należy szukać wartości liczbowych odpowiednich kodów – jeżeli na przykład podamy błędny klucz dostępu do WebAPI otrzymamy dokładnie ERR_WEBAPI_KEY.




Pierwsze kroki


Połączenie

No dobra, czas na pierwsze kroki – patrzcie uważnie i powtarzajcie za mną. Ten krok może się różnić najbardziej w przypadku różnych środowisk ze względu właśnie na to, że mają one różnie zrealizowaną obsługę SOAP i WSDL. Na przykład w C++ możemy wygenerować sobie gotową bibliotekę za pomocą oprogramowania gSOAP:

wsdl2h -o allegro.h http://webapi.allegro.pl/uploader.php?wsdl
soap2cpp allegro.h


Tutaj mała uwaga dotycząca powyższego polecenia – aby wykonać je w dokładnie takiej postaci jak powyżej, musimy skopiować do swojego katalogu plik stlvector.h, który jest dostarczany razem z oprogramowanie gSOAP.

A jak to będzie wyglądać w naszym przykładowym PHP? Tutaj wszystko dzieje się w czasie wykonywania (runtime), jako że PHP jest językiem bardzo dynamicznym. Do obsługi Allegro WebAPI posługiwać się będziemy klasą SoapClient, która posiada również obsługę WSDL, a w użyciu jest bardzo prosta – sprowadza się to do jednej linijki kodu:

  1. $client = new SoapClient('http://webapi.allegro.pl/uploader.php?wsdl');


Jeśli dobrze popatrzymy, to zauważymy, że dokładnie taki kod jest w konstruktorze naszej klasy AllegroWebAPISoapClient. Dlatego aby uczynić nasz kod bardziej czytelnym przyjmijmy, że używamy wszędzie już naszych własnych narzędzi:

  1. $client = new AllegroWebAPISoapClient();



Klucz wersji

Skoro tak już nam dobrze idzie to od razu przejdziemy do wywoływania metod Allegro WebAPI. Szczególnie takiej jednej, co to ją często wywoływać będziemy. Chodzi o metodę doQuerySysStatus i jej "hurtowy" odpowiednik doQueryAllSysStatus - służą one do pobierania informacji o aktualnych wersjach komponentów Allegro WebAPI. Aby pobrać aktualny numer wersji za pomocą pierwszej z nich musimy określić, o jaki serwis nam chodzi i podać pole, o które pytamy:

  1. $version = $client->doQuerySysStatus(AllegroWebAPISoapClient::QUERY_ALLEGROWEBAPI, ALLEGRO_COUNTRY, ALLEGRO_KEY);


Pierwszy parametr to element, o który pytamy:
  1. wersja samego WebAPI,
  2. wersja WSDL,
  3. wersja spisu kategorii,
  4. wersja formularza sprzedaży i jego pól,
  5. informacje o stronie.

Drugi parametr to numer serwisu (kraju) – spis wszystkich dostępny jest w dokumentacji, a my będziemy korzystać raczej tylko z wartości, która oznacza Polskę (Allegro.pl). Ostatnim parametrem jest nasz klucz WebAPI.

Zwrócone zostają dwie wartości – wersja zadanego elementu, oraz klucz wersji, który będzie potrzebny do dalszych operacji. Dane te przechowywane są w zmiennej $version jako pola tablicy asocjacyjnej - $version['info'] to wersja danego elementu w formacie X.Y.Z natomiast potrzebny nam klucz wersji to $version['ver-key'] (ma on postać liczbową).

W przypadku zapytania drugą metodą otrzymujemy wersje wszystkich komponentów ze wszystkich serwisów (jednak nadal musimy podawać swój identyfikator kraju):

  1. $versions = $client->doQueryAllSysStatus(ALLEGRO_COUNTRY, ALLEGRO_KEY);


Zapytanie to zwraca tablicę obiektów, z których każdy zawiera identyfikator kraju, poszczególne wersje, oraz klucz wersji. Nie będę tutaj opisywał wszystkich pól, gdyż nie jest to  aż tak istotne, jednak możemy zobaczyć, w jaki sposób dostać się do pól składowych obiektów. Oto jak wypisać klucze wersji wszystkich dostępnych serwisów:

  1. foreach($versions as $version)
  2. {
  3. echo $version->{'country-id'}, ': ', $version->{'ver-key'}, "n";
  4. }


Po co nam w ogóle klucz wersji? Jego wartość zmienia się za każdym razem, kiedy zmienia się wersja któregokolwiek z elementów wymienionych przedtem (w praktyce zmieniają się wersje jedynie drzewa kategorii i pól formularza sprzedaży). Ponieważ klucz ten jest potrzebny do niemal każdej operacji przez WebAPI, jeśli nie będziemy znali jego aktualnej wartości, nie zrobimy praktycznie nic. W momencie przydzielania nam klucza WebAPI otrzymujemy również klucze wersji wszystkich serwisów. Gdy wartość klucza serwisu, w którym się poruszamy ulegnie zmianie nie będziemy mogli korzystać z WebAPI do czasu, aż go nie uaktualnimy. Błąd klucza zostanie nam zgłoszony w kodzie jako wyjątek, a o tym w jaki sposób sobie z nimi radzić napiszę w dalszej części.


Logowanie

Czas przejść do konkretnych działań – logowanie się do systemu jest chyba dość konkretne na początek. Do tego służy metoda doLogin, która jest dość prosta w użyciu:

  1. $session = $client->doLogin(ALLEGRO_LOGIN, ALLEGRO_PASSWORD, ALLEGRO_COUNTRY, ALLEGRO_KEY, $version['ver-key']);

Kolejne parametry są raczej jasne, więc tłumaczyć nie będę. Ostatni parametr to opisywany powyżej klucz wersji. Zwrócone zostają nam dwie dane - $session['session-handle-part'] to klucz sesji (kolejna ważna zmienna, wszystkie operacje wymagające logowania będziemy potwierdzać właśnie kluczem sesji), $session['server-time'] - aktualny czas z punktu widzenia serwera Allegro (w razie potrzeby możemy zawsze pobrać aktualny czas również wywołaniem doGetSystemTime). Jest jeszcze trzecie pole, ale nie jest one wykorzystywane na obecną chwilę.

Funkcja skrótu - algorytm generujący krótki ciąg znaków, w dużym stopniu jednoznaczny (trudno o wygenerowanie takiego samego skrótu dla różnych danych), a odczytanie informacji ze skrótu jest niemożliwe.
SHA256 - 256-bitowa funkcja skrótu. Na chwilę obecną nie znaleziono dla niej kolizji, a jej długość powoduje, że nawet metody brute-force takie jak tęczowe tablice są praktycznie nieskuteczne.
Base64 - mechanizm kodowania danych w taki sposób, aby były one zapisane wyłącznie znakami alfanumerycznymi oraz +, - i =. Jest to szczególnie przydatne w przypadku transmisji binarnych danych, które zawierają wiele niedozwolonych dla danego protokołu symboli.

Ramka 3: Kodowanie i szyfry
Jak jednak widać na pierwszy rzut oka taki kod rodzi pewien niepokój u każdego, kto chociaż raz stracił hasło do jakiejkolwiek usługi w Internecie. Przesyłanie hasła w formie jawnej nie jest nigdy dobrym rozwiązaniem. Można temu zaradzić korzystając z metody doLoginEnc - jest ona taka sama, jak jej odpowiednik z akapitu powyżej, ale hasło jest tutaj przesyłane jako skrót SHA256. Jest to bardzo skuteczne zabezpieczenie, które uniemożliwia odczytanie przesyłanego hasła. Jest to skrót z rodziny SHA2, dlatego w wielu środowiskach może on być niedostępny. Na przykład w PHP można z niego korzystać jako domyślnie dostępnego dopiero od wersji 5.1.2 (wcześniej potrzebne było dodatkowe rozszerzenie o nazwie hash). Ale jeśli tylko mamy taką możliwość, powinniśmy to robić, gdyż jest to rozwiązanie o wiele bezpieczniejsze. W użyciu metoda bezpiecznego logowania wygląda identycznie, tyle, że skrót hasła musi zostać wysłany w formie binarnej zakodowanej w base64:

  1. $session = $client->doLoginEnc(ALLEGRO_LOGIN, base64_encode( hash('sha256', ALLEGRO_PASSWORD, true) ), ALLEGRO_COUNTRY, ALLEGRO_KEY, $version['ver-key']);





Zbierając wszystko w całość


Spróbujmy zatem wykorzystać zdobytą wiedzę do stworzenia czegoś konkretnego. Napiszmy program, który będzie się logował na nasze konto, a przy tym automatycznie uaktualniał się w przypadku modyfikacji w serwisie. Przyjmijmy, że klucz wersji trzymamy w pliku .verkey i nie znajduje się w nim nic ponadto:

  1. /* tutaj definicje naszych stałych i klasy */
  2.  
  3. // pobieramy nasz klucz wersji
  4. $allegroVerKey = file_get_contents('.verkey');
  5.  
  6. // łączymy się z Allegro WebAPI
  7. $client = new AllegroWebAPISoapClient();
  8.  
  9. // w ten sposób zadbamy, aby ewentualny błąd nie narobił szkód
  10. try
  11. {
  12. try
  13. {
  14. // próba logowania
  15. $session = $client->doLoginEnc(ALLEGRO_LOGIN, base64_encode( hash('sha256', ALLEGRO_PASSWORD, true) ), ALLEGRO_COUNTRY, ALLEGRO_KEY, $allegroVerKey);
  16. }
  17. catch(SoapFault $error)
  18. {
  19. // błąd niepoprawnego klucza wersji pozwala nam zauważyć fakt iż coś w serwisie się zmieniło
  20. if($error->faultcode == 'ERR_INVALID_VERSION_CAT_SELL_FIELDS')
  21. {
  22. // pobieramy aktualny klucz wersji
  23. $version = $client->doQuerySysStatus(AllegroWebAPISoapClient::QUERY_ALLEGROWEBAPI, ALLEGRO_COUNTRY, ALLEGRO_KEY);
  24. $allegroVerKey = $version['ver-key'];
  25.  
  26. /* tutaj wykonujemy swoje operacje uaktualniające */
  27.  
  28. // zapisujemy klucz wersji do pliku
  29. file_put_contents('.verkey', $allegroVerKey);
  30.  
  31. // ponowna próba logowania, już z nowym kluczem
  32. $session = $client->doLoginEnc(ALLEGRO_LOGIN, base64_encode( hash('sha256', ALLEGRO_PASSWORD, true) ), ALLEGRO_COUNTRY, ALLEGRO_KEY, $allegroVerKey);
  33. }
  34. // każdy inny błąd to już poważny problem
  35. else
  36. {
  37. throw $error;
  38. }
  39. }
  40.  
  41. // udało nam się zalogować
  42. echo 'Logowanie poprawne. Uzyskany klucz sesji to: ', $session['session-handle-part'];
  43. }
  44. catch(SoapFault $error)
  45. {
  46. echo 'Błąd ', $error->faultcode, ': ', $error->faultstring, "n";
  47. }





Klucze


Ucz się, ucz, bo nauka to potęgi klucz. A jak będziesz miał dużo kluczy do zostaniesz woźnym. Jako iż dziś dużo się nauczyliśmy i zdobyliśmy dużo kluczy, to trzeba sobie sporządzić jakiś przybornik woźnego-programisty. Więc jeśli podczas czytania zaczęły Ci się mylić pojęcia, to na koniec powtarzam, jakie klucze są potrzebne i skąd je brać:

  • Klucz Allegro WebAPI - to nasz klucz dostępowy. Jest on przypisywany do naszego konta. Otrzymujemy go od Allegro. Potrzebny jest niemalże do każdej operacji w obrębie usługi. Klucz ten jest niezmienny - raz przyznany pozostaje zawsze taki sam (po przedłużeniu ważności również nie zmienia się).
  • Klucz wersji - to klucz aktualnej wersji systemu. Zmienia się za każdą zmianą w WebAPI. Klucz ten dostajemy w momencie zgłoszenia do usługi WebAPI wraz z naszym kluczem dostępu, a klucz aktualnie obowiązujący możemy pobrać zapytaniem doQuery(All)SysStatus. Wymagany jest do wszystkich operacji dotyczących konkretnego serwisu. Ulega on zmianie w momencie wprowadzania zmian w usłudze, w szczególności zmian w liście kategorii i liście pól formularza.
  • Klucz sesji - to klucz identyfikujący naszą sesję logowania. Dostajemy go po wywołaniu metody doLogin(Enc). Jest wymagany do wszystkich operacji dotyczących konta. Jest to klucz krótko trwały (czas trwania sesji wynosi 6 godzin) i generowany jest każdorazowo podczas logowania.



Podsumowanie


Czego się nauczyliśmy? Przede wszystkim tego czym jest Allegro WebAPI i jak z niego korzystać w naszym programie. Nauczyliśmy się też podstawowych wywołań, które pozwolą nam w pełni wykorzystać potencjał WebAPI w przyszłości.



Opracował:
Rafał Wrzeszcz z Chillout Development