Instrukcja obsługi narzędzia API

Transkrypt

1 Instrukcja obsługi narzędzia API 2012

2 1. Podstawowe informacje Aby umożliwić maksymalną integrację systemów i stron partnerów z naszym systemem, stworzyliśmy specjalne API, które umożliwia generowanie aktualnej listy sprzedawanych biletów. Poprawne skonfigurowanie i wdrożenie tego narzędzie wymaga podstawowej wiedzy programistycznej, ale pozwala osiągnąć najlepsze efekty. Naszym partnerom udostępniamy specjalny plik XML ze wszystkimi informacjami o sprzedaży, który można pobrać i przetwarzać na swojej stronie lub serwerze. Jest to doskonałe narzędzie, ponieważ powoduje że spis sprzedawanych aktualnie biletów sam się aktualizuje co pozwala zaoszczędzić sporo czasu i zwiększyć efektywność poprzez dostosowanie wyglądu i sposobu prezentacji danych do swojego serwisu internetowego. Oczywiście jak w pozostałych przypadkach każde przekierowanie za pomocą tego narzędzia jest przez nas system zapisywane i gdy tylko tak przekierowany gość dokona w ciągu 30 dni jakiekolwiek zakupu biletów, zyskami dzielimy się z naszym partnerem. 2. Generowanie pliku XML Aby móc pobrać aktualną listę sprzedaży, z przygotowanymi już informacjami i linkami należy posłużyć się specjalnie przygotowanym linkiem. Dla naszych partneró3. link ten wygląda następująco: PATRNERA] Gdzie w pole [NUMER PARTNERTA] należy wpisać swój numer ID. Przykładowo jeżeli posiadają państwo ID o numerze równym to link powinien wyglądać w ten sposób: Aby sprawdzić czy plik generuje się poprawnie, należy wpisać skopiować link do przeglądarki obsługującej pliki XML (np. Internet Explorer lub FireFox) pamiętając o zmianie numeru ID na swój numer. Po chwili powinien wygenerować się plik XML, który wyglądać będzie, tak jak na obrazku poniżej:

3 Poprawnie wygenerowany plik XML Plik ten zawiera wszystkie najpotrzebniejsze informacje, które można umieścić u siebie na stronie. W pliku tym są też już wygenerowane linki, które identyfikować będą każdą przekierowaną w ten sposób osobę. Poniżej znajduje się opis wszystkich tagów pliku XML: <?xml version="1.0" encoding="utf-8"?> <events> <event event_id="xx"> <event_date> <event_time> <hall_full_name> <geo_lat> <geo_long> <hall_city> <hall_woj> <hall_address> <event_title> <event_text> Tag główny otwierający plik XML z informacją o kodowaniu. Tag główny otwierający spis wszystkich wydarzeń. Tag główny otwierający szczegółowy opis do wydarzenia o ID XX. Tag opisujący datę konkretnego wydarzenia. Tag opisujący godzinę konkretnego wydarzenia. Tag opisujący nazwę obiektu gdzie się odbędzie wydarzenie. Tag opisujący współrzędne geograficzne dla wydarzenia. Tag opisujący współrzędne geograficzne dla wydarzenia. Tag opisujący miasto obiektu gdzie się odbędzie wydarzenie. Tag opisujący województwo obiektu gdzie się odbędzie wydarzenie. Tag opisujący adres obiektu gdzie się odbędzie wydarzenie. Tag opisujący nazwę i tytuł konkretnego wydarzenia. Tag zawierający rozszerzony opis dla konkretnego wydarzenia.

4 <artist_name> <artist_persons> <artist_text> <artist_link> <event_link> <jpg_link> <jpg_min_link> <cena_min> Tag opisujący grupę jaka wystąpi w ramach wydarzenia. Tag opisujący artystów jacy wystąpią w ramach wydarzenia. Tag zawierający szczegółowy opis artysty jaki wystąpi w ramach wydarzenia. Tag z linkiem do działu artysty na KupBilecik.pl. Tag z linkiem do działu sprzedaży biletów na KupBilecik.pl na to wydarzenie. Tag z linkiem do dużego obrazka występującego artysty. Tag z linkiem do miniaturki obrazka występującego artysty. Tag z informacją o cenie najtańszych biletów na dane wydarzenie. Jak widać, wszystkie informacje o pełnej sprzedaży podane są jak na tacy. Jedyne co trzeba zrobić to przetworzyć ten plik tak, by po przetworzeniu informacje z niego zawarte wyświetlały się na wybranej stronie WWW. Poprawne skonfigurowanie i wdrożenie tego narzędzia wymaga podstawowej wiedzy programistycznej języka w jakim strona partnera została stworzona. Dobrze jest to zlecić informatykowi bądź autorowi istniejącej strony. Dla ułatwienia i zademonstrowania jak system działa w praktyce, stworzyliśmy przykładowy skrypt w języku PHP oraz w oparciu o bazę MySQL, który szczegółowo opisany został poniżej. Proszę to traktować TYLKO jako przykład poprawnego przetworzenia danych z pliku XML do bazy danych swojego serwisu. 4. Przykładowy skrypt w języku PHP Na potrzeby zademonstrowania sposobu działania narzędzia, stworzyliśmy skrypt w najpopularniejszym dla stron internetowych języku PHP, który opierając się o bazę równie popularnie stosowaną bazę danych w technologii MySQL, będzie pobierał informacje z wcześniej ściągniętego pliku XML. Podobne skrypty można tworzyć w innych językach programistycznych oraz systemach baz danych. Skrypt na potrzeby własne można pobrać ze strony WWW i dowolnie przetwarzać, link poniżej:

5 I. Przygotowanie bazy danych Pierwszym krokiem będzie stworzenie bazy danych do której będziemy zapisywać dane o imprezach. Oczywiście można ten krok pominąć i za każdym razem generować dane bezpośrednio z pliku XML, lecz będzie to znacznie obciążać serwer obsługujący stronę oraz znacznie ograniczy możliwość zarządzania danymi. Stworzona została zatem baza danych o nazwie spis w której umieszczona została tabela imprezy. Poszczególne komórki nazwaliśmy tak samo jak nazwy tagów w pliku XML... CREATE TABLE `spis`.`imprezy` ( ` event_id` INT NOT NULL, `event_date` DATE NOT NULL, `event_time` TIME NOT NULL, `hall_full_name` VARCHAR( 250 ) NOT NULL, `geo_lat` VARCHAR( 250 ) NOT NULL, `geo_long` VARCHAR( 250 ) NOT NULL, `hall_city` VARCHAR( 250 ) NOT NULL, `hall_woj` VARCHAR( 1 ) NOT NULL, `hall_address` VARCHAR( 250 ) NOT NULL, `event_title` VARCHAR( 250 ) NOT NULL, `event_text` TEXT NOT NULL, `artist_name` VARCHAR( 250 ) NOT NULL, `artist_persons` VARCHAR( 250 ) NOT NULL, `artist_text` TEXT NOT NULL, `artist_link` TEXT NOT NULL, `event_link` TEXT NOT NULL, `jpg_link` TEXT NOT NULL, `jpg_min_link` TEXT NOT NULL, `cena_min` VARCHAR( 10 ) NOT NULL, PRIMARY KEY ( ` event_id` ) ) ENGINE = MYISAM Poprawnie stworzona baza danych (widok z phpmyadmin)

6 II. Pobranie i przetworzenie pliku XML Kolejnym krokiem będzie pobranie pliku XML i przeniesienie jego zawartości do wcześniej utworzonej bazy danych. Stwórzmy zatem plik o nazwie cron.php, który będzie uruchamiany raz dziennie i raz dziennie będzie pobierał aktualną bazę danych imprez z portalu bileterskiego. Dokładny opis poszczególnych linijek kodu, opisany został w komentarzach w załączonym pliku cron.php. Ważne by pamiętać aby na koniec ustawić na swoim serwerze zadanie dla crona np. by codziennie o 1 w nocy opisany w tym rozdziale skrypt się sam automatycznie wykonywał. Więcej zobacz w pliku cron.php III. Wyświetlanie pobranych danych Gdy nowe dane o imprezach w sprzedaży zostaną zapisane do bazy, ostatnim krokiem będzie ich wyświetlenie na stronie WWW. Oczywiście polecamy tutaj dostosować sposób wyświetlania oraz miejsce do istniejącej już strony. Dzięki zawartym w bazie współrzędnym położenia obiektów gdzie odbywać się będą imprezy, można zastosować dodatkowo API Google Maps, które umożliwi wyświetlanie imprez na interaktywnej mapie polski. Dla przykładu stworzyliśmy prosty plik o nazwie index.php który wyświetla wszystkie wydarzenia z bazy. Prosimy traktować go tylko jako przykładową prezentacje danych. Więcej zobacz w pliku index.php