Allegro WebAPI

Interfejs programistyczny platformy Allegro

doGetSiteJournal

Ostatnia zmiana: ---
Dostępność:
Metoda pozwala na pobranie informacji z dziennika zdarzeń na temat zdarzeń (rozpoczęcie, zakończenie, złożenie oferty kupna w licytacji, zakup przez Kup Teraz!, zmiana w ofercie, odwołanie oferty kupna w licytacji) w ofertach zalogowanego użytkownika (dane zwracane są tylko dla ofert użytkownika utworzonych przez niego w kraju do którego jest on zalogowany w momencie wywoływania metody) lub we wszystkich ofertach w serwisie. Zwracanych jest zawsze 100 najnowszych zdarzeń (zaczynając od punktu podanego w parametrze starting-point), posortowanych rosnąco po czasie ich wystąpienia. W przypadku przekazania w parametrze starting-point wartości 0, zwróconych zostanie 100 chronologicznie najwcześniejszych zdarzeń, do których dostęp ma jeszcze dziennik zdarzeń (zazwyczaj są to dane z ostatnich 8-9 dni). Aby sterować pobieraniem kolejnych porcji danych (tak aby dotrzeć do danych najświeższych), należy w parametrze starting-point przekazywać wartość row-id ostatniego (setnego) elementu, zwracanego w ramach danego wywołania i robić to sukcesywnie, dopóki w wyniku wywołania nie otrzyma się porcji danych mniejszej niż 100 elementów (co będzie świadczyło, że otrzymane dane są danymi najświeższymi).

  1. session-handle | string | wymagany
    Identyfikator sesji użytkownika, uzyskany za pomocą metody doLogin(Enc).
  2. starting-point | long | niewymagany
    Punkt startu, pozwalający na sterowanie pobieraniem kolejnych porcji danych dot. informacji o zdarzeniach związanych z ofertami (jego wartość zwracana jest w polu row-id struktury site-journal-array).
  3. info-type | int | niewymagany
    Zakres zwracanych informacji (0 - zwracane są tylko dane dot. zdarzeń w ofertach zalogowanego użytkownika, 1 - zwracane są dane dot. zdarzeń we wszystkich ofertach w serwisie; domyślnie ustawiana jest wartość 0).



Orientacyjna struktura wywołania metody

$dogetsitejournal_request = array(
   'session-handle' => '22eb99326c6be29aa16d07d622bcfbcbee94ad54846f2f4e03_1',
   'starting-point' => 2865837087,
   'info-type' => 0
);

  1. site-journal-array | SiteJournal[]
    Tablica struktur zawierających informacje o zdarzeniach związanych z ofertami.
    1. row-id | long
      Identyfikator rekordu zawierającego informację o zdarzeniu.
    2. item-id | long
      Identyfikator oferty.
    3. change-type | string
      Typ zdarzenia (start - rozpoczęcie oferty; end - zakończenie oferty; bid - złożenie oferty kupna w licytacji; now - zakup przez Kup Teraz!; change - zmiana w ofercie; cancel_bid - odwołanie oferty kupna w licytacji przez sprzedającego lub administratora).
    4. change-date | long
      Data zapisania zdarzenia w dzienniku (w formacie Unix time).
    5. current-price | float
      Aktualna cena przedmiotu w licytacji (lub 0 jeżeli oferta jest typu Kup Teraz!).
    6. item-seller-id | long
      Identyfikator sprzedającego.



Orientacyjna struktura odpowiedzi serwera

$dogetsitejournal_response = array(
   'site-journal-array' => array(
      array(
         'row-id' => 2869399784,
         'item-id' => 975967833,
         'change-type' => 'start',
         'change-date' => 1269603383,
         'current-price' => 0,
         'item-seller-id' => 4109848),
      array(
         'row-id' => 2869434550,
         'item-id' => 975967833,
         'change-type' => 'change',
         'change-date' => 1269603891,
         'current-price' => 0,
         'item-seller-id' => 4109848),
      array(
         'row-id' => 2869460429,
         'item-id' => 975967833,
         'change-type' => 'end',
         'change-date' => 1269604287,
         'current-price' => 0,
         'item-seller-id' => 4109848))
);


  • ERR_INVALID_INFO_TYPE
    Niepoprawna wartość dla zakresu zwracanych informacji.
  • ERR_NO_SESSION / ERR_SESSION_EXPIRED
    Niepoprawny identyfikator sesji lub sesja wygasła.
  • ERR_WEBAPI_KEY_INACTIVE
    Klucz WebAPI na którym została wygenerowana sesja został zdezaktywowany (jego właściciel nie zaakceptował warunków Regulaminu WebAPI).
  • ERR_WEBAPI_NOT_AVAIL
    Problemy z usługą Allegro WebAPI.

Allegro nie bierze odpowiedzialności za skutki wykorzystania zamieszczonych przykładów kodu, nie daje także gwarancji ich poprawnego działania. Widoczny kod ma charakter wyłącznie poglądowy i może zawierać błędy.

#1 (24.04.2010 r.) / php (Autor: danielnowacki)
  1. /**
  2. * Definicja metod klienta do komunikacji z usługami WebAPI
  3. *
  4. * @package Allegro/Client
  5. * @author Daniel Nowacki
  6. * @version 1.0
  7. */
  8. abstract class Allegro_Client_Abstract extends SoapClient
  9. {
  10. const JOURNAL_INFO_TYPE_USER = 0
  11. const JOURNAL_INFO_TYPE_SERVICE = 1
  12. ...
  13.  
  14. /**
  15. * Pobiera dziennik zdarzeń
  16. *
  17. * Uwaga, metoda zwraca $maxLimit rekordów z dziennika zdarzeń. Jako, że
  18. * WebAPI pozwala pobrać maksymalnie 100 ostatnich zdarzeń, to aby osiągnąć
  19. * wartość $maxLimit, Allegro może być odpytane kilka razy.
  20. *
  21. * @see http://www.allegro.pl/webapi/documentation.php/show/id,65
  22. *
  23. * @param float $startingPoint punkt startu, od którego będize pobierane $limit wpisów
  24. * @param int $maxLimit wartość 0 oznacza bez limitu, wpp. ogranicza liczbę wyników do wartości
  25. * @param int $infoType 0 - tylko zalogowanego, 1 - całego serwisu
  26. * @return array dziennik zdarzeń
  27. */
  28. public function &getSiteJournal($startingPoint = null, $maxLimit = 0, $infoType = Allegro_Client_Abstract::JOURNAL_INFO_TYPE_USER )
  29. {
  30. $handle = $this->getSessionHandle()->getIdentifier();
  31.  
  32. $stopCondition = false;
  33. $journal = array();
  34. $currentLimit = 0;
  35. while(!$stopCondition)
  36. {
  37. // metoda doGetSiteJournal zwraca maksymalnie po 100 zdarzeń
  38. $journalPortion = $this->doGetSiteJournal($handle, $startingPoint, $infoType);
  39.  
  40. $journal = array_merge($journal, $journalPortion);
  41.  
  42. $packageSize = count($journalPortion);
  43. $currentLimit+= $packageSize;
  44.  
  45. // paczka mniejsza niż 100, lub przekroczony maksymalny limit
  46. if ($packageSize < 100 || (($currentLimit >= $maxLimit) && $maxLimit > 0) )
  47. {
  48. $stopCondition = true;
  49. }
  50. else
  51. {
  52. $startingPoint = $journalPortion[99]->{'row-id'};
  53. }
  54. }
  55.  
  56. if ($maxLimit > 0) return array_slice($journal, 0, $maxLimit);
  57.  
  58. return $journal;
  59. }
  60.  
  61. /**
  62. * Pobiera informacje na temat ostatniej zmiany w dzienniku zdarzeń
  63. *
  64. * Dziennik zdarzeń pozwala na wykrycie zdarzeń w aukcjach, bez
  65. * zbytniego obciążania WebAPI Allegro. Parametr $startingPoint warto
  66. * związać z obiektem utrwalającym w pewnym kontekście (np loginem sesji).
  67. * Kolejne wywołania metody powinny być z wywoływane z ostatnio pobranym
  68. * punktem startowym (stąd konieczność utrwalania punktu startu)
  69. *
  70. * @see http://www.allegro.pl/webapi/documentation.php/show/id,66
  71. *
  72. * @param float $startingPoint punkt startu
  73. * @param int $infoType 0 - tylko zalogowanego użytkownika, 1 - całego serwisu
  74. * @return array informacje z dziennika zdarzeń
  75. */
  76. public function getSiteJournalInfo($startingPoint = null, $infoType = Allegro_Client_Abstract::JOURNAL_INFO_TYPE_USER )
  77. {
  78. // metoda sessionHandle zwraca instancję obiektu implementującego interfejs Allegro_Session_Interface
  79. $handle = $this->getSessionHandle()->getIdentifier();
  80.  
  81. return get_object_vars($this->doGetSiteJournalInfo($handle, $startingPoint, $infoType));
  82. }
  83. }
  84.  
  85. interface Allegro_Session_Interface
  86. {
  87. /**
  88. * Pobiera dane o sesji (uzyskane przy logowaniu) jakie zwróciło WebAPI
  89. *
  90. * @return array
  91. */
  92. public function getAllegroFormatSessionInfo();
  93.  
  94. /**
  95. * Pobiera pozostały czas do wygaśnięcia sesji
  96. *
  97. * @return int sekundy do wygaśnięcia sesji
  98. */
  99. public function getExpireTime();
  100.  
  101. /**
  102. * Aktywność sesji
  103. *
  104. * @return boolean ważność sesji
  105. */
  106. public function isActive();
  107.  
  108. /**
  109. * Metody SOAP Allegro, używają najczęściej identyfikatora sesji
  110. *
  111. * @throws Allegro_Exception gdy sesja nie jest aktywna
  112. * @return string identyfikator sesji
  113. */
  114. public function getIdentifier();
  115.  
  116. /**
  117. * Ustawia informacje na temat zalogowanego użytkowania. Ze względu na
  118. * bezpieczeństwo warto metodę zaimplementować tak, aby nie pozwoliła
  119. * na nadpisanie tożsamości.
  120. *
  121. * @param array identity tożsamość zalogowanego użytkownika
  122. */
  123. public function setIdentity(array $identity);
  124.  
  125. /**
  126. * Pobiera tożsamość ustawioną przy logowaniu
  127. *
  128. * @return array identity
  129. */
  130. public function getIdentity();
  131.  
  132.  
  133. /**
  134. * Zniszczenie sesji logowania.
  135. *
  136. * Nie znalazłem, w dokumentacji żadnej metody w Allegro WebAPI, aby
  137. * zniszczyć zakończyć sesję logowania. Jednak zostawiam ją w
  138. * interfejsie, przyda się chociażby do zniszczenia lokalnej sesji
  139. *
  140. * @throws Allegro_Exception gdy brak sesji
  141. * @return true przy powodzeniu
  142. */
  143. public function destroy();
  144.  
  145. }