Rheinwerk Computing < openbook > Rheinwerk Computing - Professionelle Bücher. Auch für Einsteiger.
Professionelle Bücher. Auch für Einsteiger.

Inhaltsverzeichnis
Geleitwort
Vorwort
1 PEAR – Einführung
2 Authentication
3 Caching
4 Date and Time
5 File Formats
6 HTTP
7 Internationalization
8 Mail
9 Networking
10 PHP
11 Text
12 Web Services
13 Benchmarking
14 Configuration
15 Database
16 File System
17 HTML
18 Images
19 Logging
20 Math
21 Numbers
22 Tools and Utilities
23 XML
24 Selbst Pakete erstellen
25 PECL
Index
Ihre Meinung?

Spacer
 <<   zurück
PHP PEAR von Carsten Möhrke
Anwendung und Entwicklung – Erweiterungen für PHP schreiben
Buch: PHP PEAR

PHP PEAR
798 S., 39,90 Euro
Rheinwerk Computing
ISBN 3-89842-580-0
gp 12 Web Services
  gp 12.1 Services_Google
  gp 12.2 Services_Amazon
  gp 12.3 Services_Weather
    gp 12.3.1 weather.com
    gp 12.3.2 Globalweather
  gp 12.4 Services_Ebay


Rheinwerk Computing

12.4 Services_Ebay  toptop


Besprochene Version: 0.11.0 Lizenz: PHP-Lizenz 2.02
Klassendatei(en): Services/Ebay.php

Seit geraumer Zeit stellt die Internet-Auktionsplattform eBay auch eine Schnittstelle zur Verfügung. Über diese API können Sie auf einen Großteil der Dienste von eBay zugreifen. Allerdings benötigen Sie auch hier Kennungen, um sich gegenüber dem Server zu authentifizieren. Diese erhalten Sie dann, wenn Sie Mitglied im eBay-Entwicklerprogramm werden. Die Registration können Sie unter der URL http://developer.ebay.com/DevProgram/membership/ join.asp vornehmen. Dazu benötigen Sie allerdings einen normalen eBay-Account, den Sie sich vorher beschaffen sollten, falls Sie noch keinen haben.

Das Paket ist recht umfangreich, so dass ich nicht alle Funktionalitäten erläutern kann. Da das Paket aber sehr gut strukturiert ist, sollte es Ihnen kein Problem bereiten, sich die Funktionen, die hier nicht besprochen werden, anzueignen. In der API-Dokumentation finden Sie bei jedem API-Aufruf einen Link zur eBay-Dokumentation. Dort wird umfangreich erläutert, was der API-Aufruf leistet. Des Weiteren finden Sie im Tar-Archiv bzw. unterhalb Ihres PEAR-Verzeichnisses im Ordner doc/Services_Ebay/examples eine große Anzahl von Beispielen.

Sobald Sie sich registriert haben, erhalten Sie eine E-Mail, in der Ihnen ein Bestätigungscode mitgeteilt wird. Loggen Sie sich unter der angegebenen URL bei eBay ein, und geben Sie in das vorgesehene Feld den Code ein. Auf Basis Ihrer Daten werden dann drei Kennungen generiert, die Sie auf der nachfolgenden Seite finden.

Hierbei handelt es sich um die DevID, die AppID und die CertID. All diese Codes sind beim Aufbau einer Verbindung an eBay zu übermitteln.

Die eBay-Entwicklerseiten bieten darüber hinaus sehr umfangreiche und hilfreiche Informationen. Auf PEAR::Services_Ebay wird hier allerdings (noch) nicht eingegangen.

Des Weiteren sollten Sie sich für die Entwicklung zwei zusätzliche Accounts (einen zum Anbieten von Artikeln und einen zum Bieten auf einen Artikel) unter der URL http://sandbox.ebay.com bzw. http://sandbox.ebay.de beschaffen. Die com-Variante repräsentiert den amerikanischen Dienst, wohingegen die de-Variante weitgehend dem deutschen eBay-Dienst entspricht. Wie Sie feststellen werden, ist der deutsche Server noch nicht komplett fertig, so dass ich in den Beispielen öfter auf den amerikanischen Server zurückgreife.

Bei diesen »Sandkästen« handelt es sich um »Spiel-Versionen« von eBay. Hier können Sie Ihre Applikationen testen, ohne Gefahr zu laufen, dass Sie etwas kaufen, was Sie gar nicht haben wollen. Eine Sandbox bietet grundsätzlich dieselben Funktionalitäten wie der echte eBay-Service. Bitte unterschätzen Sie diesen Faktor nicht. Wenn Sie hier auf Help klicken, erhalten Sie auch nur Hilfe zu dem »echten Ebay«, aber keine Hilfe, die Ihnen als Entwickler etwas bringt. Des Weiteren werden Sie feststellen, dass die Sandbox-Server nicht ganz so schnell sind und zeitweise technische Probleme haben.

Um auf dem amerikanischen Server einen neuen Account anzulegen, benötigen Sie eine gültige Adresse mit gültiger Telefonnummer in den USA. Da ich, wie Sie wahrscheinlich auch, leider keine Adresse in den USA habe, nutze ich Adressen, die ich aus http://www.yellowpages.com oder http://www.any who.com übernehme. Ich möchte Sie natürlich nicht dazu verleiten, fremde Adressen zu nutzen, aber ich bin mir nicht sicher, ob der Aufwand, eine Wohnung in den USA anzumieten, nicht zu groß wäre. Nach meinem jetzigen Kenntnisstand wird die dort angegebene Adresse allerdings nicht genutzt, so dass die Nutzung kein Problem darstellen sollte. [Die Empfehlung, auf diesem Weg eine Adresse zu finden, stammt vom PEAR-Entwickler-Team, zu dem auch Adam Trachtenberg, der »Technical Evangelist« von eBay, gehört. ]

Einen neuen Account auf sandbox.ebay.de zu beantragen ist unproblematisch, da die Daten nicht auf Validität geprüft werden.

Die erstellten Accounts können allerdings noch nicht genutzt werden. Normalerweise müssten Sie noch eine Kreditkartennummer eingeben, um sie produktiv nutzen zu können. In diesem Fall hat eBay allerdings eine API-Funktion vorgesehen, um die Accounts »scharf« schalten zu können, die später erläutert wird.

Möchten Sie eine Verbindung zu eBay aufbauen, müssen Sie zunächst eine neue Session instanziieren. Aus dieser heraus werden dann die einzelnen Aufrufe getätigt. Diese Session benötigt die drei Tokens, die Sie von eBay erhalten haben. Des Weiteren benötigen Sie noch ein »Authentication Token«. Hiermit wird der Account eines Users bei eBay identifiziert. Hierfür gibt es zwei Gründe. Zum einen ist der Entwickler, der durch die drei anderen Tokens schon identifiziert würde, wahrscheinlich nicht derjenige, unter dessen Account auf eBay zugegriffen werden soll. Zum anderen wäre ein User-Account natürlich auch durch Benutzernamen und Passwort zu identifizieren. Das hätte aber den Nachteil, dass das Passwort im Klartext in der Applikation abgelegt würde und der Programmierer es eventuell ausspähen könnte.

Um dieser Problematik zu entgehen, kann ein User mithilfe des Authentication Tokens identifiziert werden. Ein solches Token können Sie vom Single-User-Tool unter der URL http://developer.ebay.com/tokentool/ generieren lassen. Sie werden feststellen, dass es hier zwei Arten von Tokens gibt: eine Version für die Sandbox und eine für den Produktivserver. Sie sollten hier zum Testen erstmal nur eine Sandbox-Version generieren lassen. Da diese nicht kompatibel zum Produktivserver ist, können Sie somit auch sicher sein, nicht aus Versehen einen Artikel zu ersteigern.

Es ist sinnvoll, diese Daten in eine externe Datei auszulagern, die dann jederzeit inkludiert werden kann. Für die folgenden Beispiele sieht die Datei, die unter dem Namen auth.inc.php abgelegt wird, wie folgt aus:

<?php 
   $devId = 'R6413VUINKIF13374ZBWDB7LHO56EH4'; 
   $appId = 'SAMHMY3WG8WCF3N2BSB958SDG67VX'; 
   $certId = 'Z3BDB3WB4OTT9$28J13D834-U3DQR3l1'; 
   $token = 'AgAAAA**AQAAAA**aAAAAA**cB … 9hAZ' 
?>

In $token ist das Authentication Token abgelegt, das ich hier deutlich gekürzt habe. Nutzen Sie eine Include-Datei wie diese, so beachten Sie bitte, dass in den Strings durchaus ein Dollarzeichen enthalten sein kann. Daher sollten Sie einfache und keine doppelten Anführungszeichen nutzen.

Bevor ich zu der Nutzung des Paketes komme, noch der Hinweis, dass Services_Ebay in PHP 5 erstellt wurde. Somit können Sie das Paket nicht unter PHP 4 nutzen, und die Fehler werden auf Basis von Exceptions behandelt.

Um API-Aufrufe an eBay zu senden, müssen Sie zuerst eine neue Session mit der statischen Methode getSession() generieren. Sie bekommt die Developer-ID, die Application-ID und die Certificate-ID übergeben. Sind alle Werte korrekt, gibt die Methode ein Services_Ebay_Session-Objekt zurück. Diesem Objekt muss dann das Token übergeben werden, das den Benutzer identifiziert. Dies geschieht mit der Methode setSession(), die das Authentication-Token als Parameter übergeben bekommt.

Die so initialisierte Session wird an den Konstruktor der Klasse Services_Ebay übergeben, die Ihnen ein Objekt zurückgibt, mit dem Sie dann die einzelnen API-Aufrufe tätigen können.

Der erste API-Aufruf, den Sie ausführen sollten, ist ValidateTestUserRegistration(). Hiermit schalten Sie den Account, den Sie in der Sandbox eingerichtet haben und der durch das Token identifiziert wird, frei, so dass Sie darüber auch »verkaufen« können. [Bitte versuchen Sie nicht, den Account durch die Eingabe einer Kreditkartennummer als »Seller Account« freizuschalten. Es wird nicht funktionieren. ]

require_once('Services/Ebay.php'); 
require_once('auth.inc.php'); 
 
try 
{ 
   // Neue Session ableiten 
   $session = Services_Ebay::getSession($devId, 
                                            $appId,$certId); 
   // Authentication-Token setzen 
   $session->setToken($token); 
 
   // Services_Ebay-Objekt ableiten 
   $ebay = new Services_Ebay($session); 
 
   // User freischalten 
   $ebay->ValidateTestUserRegistration(); 
} 
catch (Exception $error) 
{ 
   die ("Fehler: ".$error->getMessage()); 
}

Listing 12.7 Freischalten eines Accounts mit der API

Nachdem der Account freigeschaltet ist, können Sie über die API Artikel einstellen oder darauf bieten.

Die Nutzung der API-Aufrufe in diesem Bereich läuft meist sehr ähnlich ab. Für jeden API-Aufruf existiert eine Klasse, deren Name mit Services_Ebay_Call eingeleitet wird. Üblicherweise besteht die Klasse nur aus der Methode call(), die den eigentlichen Aufruf ausführt.

Da die API-Aufrufe nicht immer ausreichend dokumentiert sind, kann es hilfreich sein, die Methode describeCall() aufzurufen. Diese ist für alle Klassen definiert, die einen API-Aufruf ausführen, und gibt eine kurze Beschreibung der Klasse und der enthaltenen Methoden aus.

Diese Klassen werden teilweise implizit genutzt. So wird im obigen Beispiel die Methode ValidateTestUserRegistration() aufgerufen. Bei genauer Betrachtung wird hierzu im Hintergrund die Klasse Services_Ebay_Call_ValidateTestUserRegistration genutzt, mit der Sie als Programmierer aber nicht direkt konfrontiert werden.

Des Weiteren ist eine recht stattliche Anzahl von Klassen definiert. Diese dienen entweder dazu, Objekte zu definieren, die ein API-Aufruf zurückgibt, oder daraus abgeleitete Objekte werden genutzt, um damit einen API-Aufruf zu initiieren. Die Namen dieser Klassen beginnen jeweils mit Services_Ebay_Model.

Objekte dieser Klassen werden häufig nicht direkt instanziiert, sondern mithilfe der Methode loadModel() abgeleitet. Diese bekommt den Namen des Objekts übergeben, das Sie benötigen. In einem ersten Beispiel möchte ich Ihnen zeigen, wie Sie ein Objekt zum Verkauf anbieten. Um ein Angebot mithilfe des AddItem-Aufrufs an eBay zu übermitteln, benötigen Sie ein Services_Ebay_Model_Item-Objekt. Die Methode loadModel() bekommt den String 'Item' übergeben, bindet die entsprechende Klassendatei ein und leitet das Objekt ab. Diesem Item-Objekt werden die Werte übergeben, die wichtig sind, um das Objekt bei eBay listen zu können. Wenn das erfolgt ist, können Sie es mit dem API-Aufruf AddItem an eBay übergeben.

Nun stellt sich die interessante Frage, wie der Verkaufsgegenstand beschrieben wird. Dies geschieht über Werte, die Sie in Form von Eigenschaften im Objekt ablegen. Die Eigenschaften, die Sie dazu nutzen können, sind in der Dokumentation des Paketes nicht beschrieben. Hierzu müssen Sie in der Entwickler-Dokumentation bei eBay nachlesen. Dort finden Sie bei der Beschreibung des API-Aufrufs AddItem einen Link zur Standard Argument Table. Hierbei handelt es sich um eine umfangreiche Tabelle, von der Sie einen Ausschnitt in Abbildung 12.6 sehen.

Die Werte, die Sie in der Spalte Argument finden, können Sie direkt als Namen für eine Eigenschaft übernehmen. Daneben finden Sie den unterstützten Datentyp sowie die Information, ob das Argument erforderlich ist. In der letzten Spalte sind dann die Erläuterungen zu finden.

Das erste Argument, RequestToken, können Sie getrost ignorieren, da das Token durch die Methode setToken() übergeben wird.

Abbildung 12.6 Standard Argument Table zu AddItem

In Listing 12.8 finden Sie ein Beispiel dafür, wie Sie einen Artikel hinzufügen.

require_once ('Services/Ebay.php'); 
require_once('auth.inc.php'); 
 
try 
{ 
   $session = Services_Ebay::getSession($devId, 
                                      $appId, $certId); 
   $session->setToken($token); 
   $ebay = new Services_Ebay($session); 
 
   // Neues Item-Objekt 
   $item = Services_Ebay::loadModel('Item'); 
 
   // Session fuer API-Aufruf uebergeben 
   $item->setSession($session); 
 
   // Kategorie-Nummer 
   $item->Category = 14909; 
 
   // Titel der Auktion 
   $item->Title = 'Neues G4 Powerbook, 1,5 GHz, 512 MB '; 
 
   // Ueberschrift soll in der Liste fett erscheinen 
   $item->BoldTitle=true; 
 
   // Beschreibung des Artikels 
   $item->Description = ' 
          Sie k&ouml;nnen hier ein <b>NAGELNEUES</b> G4 Powerbook 
          ersteigern<br><ul><li>1,5GHz</li><li>512 MB RAM </li> 
          <li>Combo-Drive</li></ul><p>Nach neuem EU-Recht 
          handelt es sich um einen <u>Privatverkauf</u> 
          ohne Anspruch auf Garantie oder 
          Gew&auml;hrleistung</p>'; 
 
   //Artikelstandort 
   $item->Location = 'Bielefeld'; 
   // Land, in dem sich der Artikel befindet 
   $item->Country = 'DE'; 
 
   // Art der Auktion (optional) 
   $item->Type = 1; 
   // Startgebot 
   $item->MinimumBid = 1; 
   // Sofort-Kaufen-Preis 
   $item->BuyItNowPrice = 2000; 
   // Waehrung, in der das Angebot laeuft (1 = USD) 
   $item->Currency = 1; 
 
   // Zahlungsmoeglichkeiten 
   // Zahlung bei Abholung 
   $item->CashOnPickupAccepted = true; 
   // Zahlung per Ueberweisung + 
   $item->MoneyXferAcceptedinCheckout = true; 
   // Zahlung per Visa-/Master-Karte 
   $item->VisaMaster = 1; 
 
   // Versandbedingungen 
   // Versandkosten wurden spezifiziert 
   $item->CheckoutDetailsSpecified = true; 
   // Versandkosten sind immer gleich 
   $item->ShippingType = 1; 
   // Laender, in die versandt wird 
   $item->SetShipToLocations(array('US', 'DE', 'GB')); 
   // Kosten fuer den Versand 
   $item->addShippingServiceOption( 
         1, //Versandart (Standard Flat Rate Shipping Service) 
         1, // Prioritaet 
         30.10, // Versandkosten 
         0.0, // Versandkosten fuer weitere Artikel 
         array('US','DE','GB') //Preise gelten fuer diese Laender 
        ); 
 
   $result = $ebay->AddItem($item); 
 
   echo "Der Artikel wurde als Nummer $item->Id bei eBay 
         eingeliefert und l&auml;uft bis: $item->EndTime"; 
} 
catch (Exception $err) 
{ 
   die ("Fehler: ".$err->getMessage()); 
}

Listing 12.8 Einliefern eines Artikels über die API

Bei eBay erscheint die Auktion wie in Abbildung 12.7 dargestellt. Zwar sind nicht alle Eigenschaften zu sehen, die hier festgelegt wurden, aber es reicht, um einen Eindruck zu bekommen.

Das Unschöne an dieser Vorgehensweise ist zum einen, dass die Anzahl der Eigenschaften, die belegt werden müssen oder belegt werden können, sehr groß ist. Das andere Problem ist, dass die zulässigen Werte leider nicht immer selbsterklärend sind. Die zulässigen Werte können Sie der eBay-Dokumentation entnehmen, wobei ich einige gleich noch erläutern werde. Erschwert wird die Nutzung noch dadurch, dass nicht alle Werte für alle Landesplattformen von eBay zulässig sind.

Abbildung 12.7 Auktion bei eBay

Wo Sie die möglichen Eigenschaften für ein Item finden, wissen Sie ja schon. Allerdings stellt sich noch die Frage, welche Werte für die Eigenschaft zulässig sind. Für einige, wichtige Eigenschaften möchte ich Ihnen zeigen, wie und wo Sie die Werte finden.

Eins vorweg: eBay betreibt eine recht große Anzahl von Plattformen in unterschiedlichen Ländern. Die Funktionalitäten, die auf den einzelnen Plattformen vorhanden sind, unterscheiden sich dabei. Daher werden Sie in der eBay-Dokumentation oft den Hinweis finden, dass bestimmte Argumente oder Werte für Argumente nur für bestimmte Site-IDs zulässig sind. Jedes der regionalen Auktionshäuser wird also durch eine eigene ID identifiziert. Die aktuellen Site-IDs finden Sie in Tabelle 12.5.

[eBay gibt für www.ebay.com.hk Englisch an, momentan läuft der Dienst allerdings auf Chinesisch.
Tabelle 12.5 Site-IDs von eBay
Site-ID Land Abkürzung Sprache
0 Vereinigte Staaten us Englisch
2 Kanada ca Englisch
3 Großbritannien uk Englisch
15 Australien au Englisch
16 Österreich at Deutsch
23 Belgien (Französisch) befr Französisch
71 Frankreich fr Französisch
77 Deutschland de Deutsch
100 eBay Motors   Englisch
101 Italien it Italienisch
123 Belgien (Holländisch) benl Holländisch
146 Niederlande nl Holländisch
186 Spanien es Spanisch
193 Schweiz ch Deutsch
196 Taiwan tw Chinesisch
201 Hongkong hk Englisch8
207 Malaysia my Englisch
211 Philippinen ph Englisch
216 Singapur sg Chinesisch

]

Die lokalen Server werden typischerweise über diese IDs referenziert. Die Landesabkürzung wird eher selten genutzt. Bitte beachten Sie, dass die Landesabkürzungen hier nichts mit Ländern zu tun haben, die Sie für den Versand oder Ähnliches benötigen. Welche Möglichkeiten auf welchem Server zur Verfügung stehen, können Sie in den International Matrixes nachlesen, die Sie in Anhang N der API-Dokumentation finden.

In Listing 12.8 ist die Nummer der Kategorie der erste Wert, den ich zuweise. In diesem Fall handelt es sich um die Kategorie für Apple-Notebooks. Möchten Sie die Nummer einer einzelnen Kategorie in Erfahrung bringen, würde ich Ihnen empfehlen, in der fraglichen eBay-Landes-Domain den Server listings aufzurufen, also z. B. http://listings.ebay.de oder http://listings.ebay.com. Hier finden Sie eine Übersicht, in der Sie sich alle Kategorien anzeigen lassen können. Unterhalb der Zeile mit den Optionslisten finden Sie einen Radio-Button, der Ihnen die Möglichkeit gibt, die Kategorienummern einzublenden. Um eine Übersicht über alle Kategorien zu erhalten, bietet sich der API-Aufruf getCategories an. Dazu später mehr.

Mit den Eigenschaften Title und Description wird die Überschrift bzw. die Beschreibung des Artikels übergeben. Bei der Beschreibung können Sie alle Funktionalitäten nutzen, die die normale eBay-Plattform auch bietet. Es ist also kein Problem, HTML, CSS oder Ähnliches zu nutzen.

Um in der Listen-Ansicht eine fette Darstellung des Titels zu gewährleisten, habe ich der Eigenschaft BoldTitle den Wert true zugewiesen. Bitte beachten Sie, dass diese und auch einige andere Optionen kostenpflichtig sind. Die Preise entnehmen Sie bitte der Preisliste, die für das jeweilige Land gültig ist.

Die Eigenschaften Location und Country enthalten die Information, wo sich der Artikel befindet. In Location können Sie einen freien Text übergeben, und Country muss einem Land entsprechen. Die Abkürzungen, die zum Festlegen des Landes genutzt werden, entsprechen weitgehend den ISO-Codes, aber leider nicht ganz. Die eBay-Codes finden Sie im Anhang L der API-Dokumentation. [APO = Army Post Office; FPO = Fleet Post Office ]

Die Eigenschaft Type wird mit dem Code belegt, der definiert, um welche Art von Auktion es sich handelt.


Tabelle 12.6 Auktionsformate bei eBay
Auktionstyp Beschreibung
1 Chinesische Auktion, die »normale« eBay-Auktion. Kann zusammen mit dem Sofort-Kaufen genutzt werden.
2 Holländische Auktion, in diesem Fall können mehrere identische Artikel eingestellt werden. Kann nur von geprüften Mitgliedern oder ab 30 positiven Bewertungen genutzt werden.
6 Auktion im »Ad Format« (Nur für Immobilien auf ebay.com)
7 Artikel für einen eBay-Shop
9 Artikel, der nur zum Sofortkauf angeboten wird

Hierbei handelt es sich um ein optionales Argument. Geben Sie den Auktionstyp nicht an, wird automatisch Typ 1 genutzt.

Die Eigenschaften MinimumBid und BuyItNowPrice dienen zur Preisdefinition. Die erste enthält den Startpreis und die zweite den Preis für einen Sofort-Kauf, wobei diese Angabe natürlich optional ist.

Zusätzlich kann auf einigen eBay-Plattformen noch die Eigenschaft ReservePrice genutzt werden. Diese enthält einen Mindestpreis, der erreicht werden muss, bevor der Verkäufer verkauft.

Die Eigenschaft currency übernimmt die Währung, in der der Artikel versteigert wird. Normalerweise ist diese Angabe nicht unbedingt notwendig, da immer die Landeswährung der Plattform übernommen wird. Mit der Konstante 1 werden US-Dollar bezeichnet. Welche Währungen noch zur Verfügung stehen, können Sie der Currency Table der API-Dokumentation entnehmen.

Die Angabe der akzeptierten Zahlungsmöglichkeiten ist ein wenig umständlich, wie ich finde. Für jede Zahlungsmethode, die eine Site kennt, ist eine Eigenschaft definiert. Zur Angabe der Zahlungsmethoden, die für dieses Produkt akzeptiert werden, müssen Sie die jeweilige Eigenschaft mit true bzw. 1 belegen, was äquivalent ist.

Welche Zahlungsmethoden von welcher Plattform unterstützt werden, können Sie wiederum den International Matrixes aus Anhang N entnehmen. Die Zahlungsmethoden CashOnPickupAccepted (Barzahlung bei Abholung) und MoneyXferAcceptedinCheckout (Überweisung +) werden nicht vom amerikanischen eBay und somit auch nicht von der amerikanischen Sandbox unterstützt. In der deutschen Sandbox sollten sie allerdings problemlos nutzbar sein.

Haben Sie Versandart oder -kosten definiert, so müssen Sie der Eigenschaft CheckoutDetailsSpecified den Wert true übergeben.

Mit ShippingType wird festgelegt, wie sich die Versandkosten berechnen. Der Typ 1 besagt, dass die Versandkosten immer gleich sind. Beim Typ 2 können diese dynamisch berechnet werden. Weitere Informationen dazu erhalten Sie unter dem Stichwort Shipping beim Unterpunkt Managing Item Shipping Costs in der API-Dokumentation.

Eine der wenigen Methoden, die hier genutzt werden, ist SetShipToLocations(), der ein Array mit Kürzeln für die Länder vergeben wird, in die der Artikel verschickt wird. Danach folgt der Aufruf von addShippingServiceOption(), der dazu dient, die Versandkonditionen zu spezifizieren. Der erste Parameter spezifiziert die Versandart. Welche Werte hier unterstützt werden, können Sie wiederum dem Anhang N der API-Dokumentation entnehmen. Der zweite Wert ist die Priorität, mit der der Artikel versandt wird. Hier können Sie Werte von 1 bis 3 vergeben. Danach folgen die Kosten für den Versand des Artikels und Kosten, die anfallen, wenn ein zusätzlicher Artikel bei dem Verkäufer erworben wird. Zu guter Letzt erwartet die Methode die Länder, für die diese Konditionen gelten.

Die Methode AddItem(), die von dem Services_Ebay-Objekt aus aufgerufen wird, bekommt den neu erstellten Artikel übergeben und liefert ihn bei eBay ein. War die Datenübergabe erfolgreich, so können Sie der Eigenschaft Id die Artikelnummer entnehmen, unter der die Auktion eingeliefert wurde, und in EndTime ist die Uhrzeit enthalten, zu der die Auktion endet.

Sie sehen, die eBay-API ist recht komplex, aber durchaus gut zu verstehen und vor allem sehr gut dokumentiert.

In Listing 12.8 habe ich einfach eine Kategorienummer vorgegeben. Möchten Sie ein Interface erstellen, um Artikel einzuliefern, wäre es natürlich ungeschickt, die Kategorie hart im Quelltext zu kodieren. Wie schon erwähnt, können Sie die Nummern und Namen der Kategorien auslesen. Da eBay sehr viele Kategorien kennt, wäre es eine denkbar schlechte Idee, die Kategorien jedes Mal erneut auszulesen. Daher bietet es sich an, die Daten lokal zu cachen. Um Sie dabei zu unterstützen, können Sie bei eBay erst die Versionsnummer der aktuellen Kategorieliste auslesen. Stellen Sie fest, dass die von Ihnen gespeicherten Daten veraltet sind, können Sie die Liste erneut anfordern. Die Nutzung des API-Aufrufs GetCategories könnte wie in Listing 12.9 erfolgen.

// Zeitlimit auf unendlich 
set_time_limit(0); 
require_once ('Services/Ebay.php'); 
require_once('auth.inc.php'); 
 
// Funktion, um Daten im Cache abzulegen 
function safeToCache($data) 
{ 
   file_put_contents('cat_version.data',$data["Version"]); 
   file_put_contents('categories.data',serialize($data)); 
} 
 
// Daten aus Cache lesen 
function getFromCache() 
{ 
   $data = unserialize(file_get_contents('categories.data')); 
   return $data; 
} 
 
// Version der gecachten Daten auslesen 
function cachedVersion() 
{ 
   if (file_exists('cat_version.data')) 
   { 
      $version=file_get_contents('cat_version.data'); 
      return (int) $version; 
   } 
   else 
   { 
      return 0; 
   } 
} 
 
try 
{ 
   $session = Services_Ebay::getSession($devId, 
                                        $appId, $certId); 
   $session->setToken($token); 
   // Site-ID auf Deutschland setzen 
   $session->setSiteId(77); 
 
   // Neues Call-Objekt ableiten 
   $getCategories = Services_Ebay::loadAPICall 
                                   ('GetCategories'); 
   // Nur die Kategorie-Infos sollen geliefert werden 
   $getCategories->setDetailLevel(0); 
 
   // Informationen auslesen 
   $liste = $getCategories->call($session); 
   // Versionsnummer auslesen 
   $version = $liste['Version']; 
   // Testen, ob die Version im Cache aktuell ist 
   if ($version > cachedVersion()) 
   { 
      // Die Version ist nicht aktuell -> Neu anfordern 
      $getCategories->ViewAllNodes=1; 
      $getCategories->setDetailLevel(1); 
      // Liste anfordern 
      $liste = $getCategories->call($session); 
      // Liste im Cache ablegen 
      safeToCache($liste); 
   } 
   else 
   { 
      // Liste im Cache ist noch aktuell -> auslesen 
      $liste = getFromCache(); 
   } 
 
   // Liste verarbeiten 
} 
catch (Exception $e) 
{ 
   die ($e->getMessage()); 
}

Listing 12.9 Auslesen der Kategorieliste

Listing 12.9 ist sicher nicht ideal implementiert. Der Cache könnte geschickter implementiert werden, und Sie sollten für einen Echtbetrieb auch nicht alle Kategorien in einer großen Cache-Datei ablegen. Nichtsdestotrotz wird das System deutlich.

Die Kategorien auszulesen kann sehr lange dauern, weshalb das PHP-typische 30-Sekunden-Limit in der ersten Zeile ausgeschaltet wird.

Nachdem eine neue Session generiert wurde, wird dieser mithilfe von setSiteId() die ID der deutschen eBay-Site übergeben. Die Methode habe ich im vorhergehenden Listing beim Einstellen der Auktion nicht genutzt, da die Testauktionen sowieso nur bei sandbox.ebay.com eingeliefert werden können. Möchten Sie später produktiv mit dem Paket arbeiten, legen Sie damit immer die Site fest, mit der Sie arbeiten wollen.

Die Methode loadAPICall() generiert das entsprechende API-Call-Objekt, mit dem der Aufruf durchgeführt wird. Wenn Sie mit der Methode setDetailLevel() den Detaillierungsgrad auf 0 setzen, bekommen Sie nur Informationen über die Version des Kategoriebaums und die Aktualisierungszeit. Der eigentliche Aufruf wird durch die Methode call() durchgeführt und liefert ein Array zurück. Im Element 'Version' ist die Versionsnummer enthalten, das Element 'UpdateGMTTime' enthält Datum und Uhrzeit der Aktualisierung bezogen auf GMT, und 'UpdateTime' enthält dieselbe Information bezogen auf die eBay-Zeit.

Stellt das Script fest, dass die Versionsnummer, die dieser API-Aufruf liefert, größer ist als die Versionsnummer, die lokal gecacht ist, werden alle Kategorien erneut von eBay angefordert.

Hierzu wird die Eigenschaft ViewAllNodes auf 1 gesetzt, wobei auch true ein gültiger Wert wäre. Die Kategorien werden als Baum zurückgegeben, und diese Eigenschaft entscheidet darüber, ob Sie nur die Blätter (0 oder false) erhalten oder auch die dazwischen liegenden Knoten (1 oder true). Dadurch, dass die Methode setDetailLevel() mit dem Wert 1 aufgerufen wird, liefert der Aufruf von getCategories() die Kategorien und nicht nur eine Übersicht zurück. Wie schon erwähnt wurde, dauert die Datenübertragung recht lange. In der aktuellen Version 44 kennt eBay-Deutschland immerhin 35.465 Kategorien.

Der Rückgabewert ist auch in diesem Fall ein indiziertes Array. Jede Kategorie wird hierin durch ein eigenes Array repräsentiert, das folgenden Aufbau hat:

    [1]=> 
    array(9) { 
      ["CategoryId"]=> 
      string(5) "34407" 
      ["BOE"]=> 
      string(1) "0" 
      ["CategoryLevel"]=> 
      string(1) "2" 
      ["CategoryName"]=> 
      string(24) "Alte Weine & Spirituosen" 
      ["CategoryParentId"]=> 
      string(3) "353" 
      ["IsExpired"]=> 
      string(1) "0" 
      ["IsIntlAutosFixedCat"]=> 
      string(1) "0" 
      ["IsVirtual"]=> 
      string(1) "0" 
      ["LeafCategory"]=> 
      string(1) "0" 
    }

Der Schlüssel CategoryID verweist auf die ID der Kategorie. Über diese IDs werden die Kategorien miteinander verknüpft, so dass auf dieser Basis ein Baum aufgebaut werden kann. BOE steht für Best Offer Enabled und bezeichnet folgende Funktionalität: Wird ein Artikel zum Sofort-Kauf angeboten, kann ein Interessent ein Angebot über einen niedrigeren Preis machen, wenn der Angebotspreis ihm zu hoch ist. Enthält dieses Feld den Wert 1, so wird dieses Feature in dieser Kategorie unterstützt.

CategoryLevel bezeichnet die Tiefe einer Kategorie innerhalb des Baumes. Ist hier eine 1 zu finden, so handelt es sich um ein Element erster Ebene, also einer Hauptkategorie. In diesem Beispiel ist die 2 enthalten, was besagt, dass nur eine Hierarchieebene über dieser Kategorie zu finden ist.

Der eigentliche Name der Kategorie ist im Feld CategoryName enthalten, der für Optionslisten oder Links genutzt werden kann.

Das nächste Element, CategoryParentId, enthält die ID der übergeordneten Kategorie, also der Parent-Kategorie. Mithilfe dieser Information sind Sie in der Lage, einen Baum aufzubauen und zu erkennen, welche Elemente zusammengehören. Bei einem Root-Element, also einer Kategorie erster Ebene, ist hier die eigene Nummer zu finden, um zu verdeutlichen, dass diese Kategorie keinen Vorgänger hat.

Das Element IsExpired wirkt auf den ersten Blick überflüssig. Ist hier eine 1 enthalten, bedeutet das, dass diese Kategorie veraltet ist und keine Produkte in dieser Kategorie mehr eingeliefert werden sollen. Sollten Sie sich fragen, warum die Kategorie dann nicht einfach weggelassen wird, ist die Antwort recht einfach. Es könnten sich immer noch Artikel darin befinden, die verkauft werden. Dass eine Kategorie nicht mehr genutzt werden soll, sollten Sie nicht nur beim neuen Einliefern von Produkten, sondern auch beim Wiedereinstellen von Produkten beachten.

Ist in IsIntlAutosFixedCat eine 1 enthalten, so bedeutet das, dass es sich hierbei um eine fixed-fee Category handelt, bei der es nicht möglich ist, Artikel im eBay Shop Listing-Format einzuliefern. Das Merkmal IsVirtual ist nur bei eBay-Motors anzutreffen und definiert eine virtuelle Kategorie, in die keine Artikel eingeliefert werden können.

Das letzte Element ist LeafCategory. Ist hier eine 1 enthalten, bedeutet das, dass es sich um ein Blatt handelt. Es folgen also keine weiteren Kategorien.

Theoretisch ist es möglich, dass ein solcher Rückgabewert noch andere Elemente enthält. Eine entsprechende Aufstellung finden Sie in der Dokumentation zum API-Aufruf GetCategories.

Leider ist das Bieten als solches in PEAR::Services_Ebay (noch) nicht implementiert. Nichtsdestotrotz können Sie Informationen über eine Auktion erhalten. Dazu ist eine Suchfunktion natürlich sehr hilfreich. Diese können Sie über den API-Aufruf GetSearchResults implementieren. Ein solches Suchformular ist in Listing 12.10 implementiert.

if (false===isset ($_GET['search'])) 
{ 
   // Formular fuer die Suchbegriffe 
   echo "<form> 
         Suchbegriff <input name='search' /><br /> 
         <input type='submit' /> 
         </form>"; 
} 
else 
{ 
   require_once ('Services/Ebay.php'); 
   require_once('auth2.inc.php'); 
   try 
   {_$ret_      $session = Services_Ebay::getSession($devId, 
                                           $appId,$certId); 
      $session->setToken($token); 
      $session->setSiteId(77); 
 
      $getSearch = Services_Ebay::loadAPICall 
                                        ('GetSearchResults'); 
      $args = array ( 
                 'Query' => $_GET['search'], // Suchbegriff 
                 'SearchInDescription' => 1, // Beschreibung 
                                             // durchsuchen? 
                 'Skip' => 0, // Wie viele Artikel sollen 
                              // uebersprungen werden? 
                 'MaxResults'=>20, // Max. Anzahl Ergebnisse 
                 'Category' =>0 //Kat., die durchsucht wird 
                 ); 
      $getSearch->setArgs($args); 
      $res=$getSearch->call($session); 
 
      $cnt=0;  // Zaehler fuer Hintergrundfarbe 
      echo '<table>'; 
      echo '<tr> 
            <td>Nummer</td> 
            <td>Titel</td> 
            <td>Gebote</td> 
            <td>Aktueller<br />Preis</td> 
            </tr>';
 
      // Ergebnisse in einer Schleife abarbeiten 
      foreach ($res as $item) 
      { 
         // Um jede zweite Zeile mit einer Hintergrundfarbe 
         // zu hinterlegen 
         if (1 == $cnt%2) 
         { 
            $bgcolor=' bgcolor="#EEEEEE" '; 
         } 
         else 
         { 
            $bgcolor=''; 
         } 
         echo "<tr $bgcolor>"; 
         echo "<td>$item->Id</td>"; 
         echo "<td><a href ='$item->Link'> 
               $item->Title</a></td>"; 
         echo "<td>$item->BidCount</td>"; 
         echo "<td>$item->CurrentPrice</td>"; 
         echo "</tr>\n"; 
         $cnt++; 
      } 
      echo '</table>'; 
   } 
   catch (Exception $error) 
   { 
      die ("Error: ".$error->getMessage()); 
   } 
}

Listing 12.10 Suchformular für eBay

Der API-Aufruf GetSearchResults benötigt mindestens das Argument Query, in dem der Suchbegriff übergeben wird. Dieses und die anderen Argumente werden in einem Array abgelegt. SearchInDescription akzeptiert einen booleschen Wert bzw. die Zahl 0 oder 1, um festzulegen, ob die Beschreibung des Artikels auch durchsucht werden soll. Ist hier 0 oder false enthalten, wird nur der Titel der Auktionen durchsucht.

Skip ist dazu gedacht, einfach durch die Ergebnisse blättern zu können. Dieses Argument bekommt die Anzahl der Elemente übergeben, die übersprungen werden sollen, wobei das erste Element die Nummer 0 hat. Dieses Argument können Sie gut mit MaxResults kombinieren, womit definiert wird, wie viele Ergebnisse maximal zurückgegeben werden. Der größte hier akzeptierte Wert ist 100.

Das letzte Argument, das hier unterstützt wird, ist Category, mit dem Sie eine Kategorienummer übergeben können, die durchsucht werden soll. Der Wert 0 besagt, dass alle Kategorien in die Suche einbezogen werden sollen.

Nachdem der Aufruf mit call() durchgeführt wurde, erhalten Sie ein Objekt zurück, dass Sie direkt mit einer foreach-Schleife abarbeiten können. Bei jeder Iteration erhalten Sie ein Item-Objekt, aus dem Sie die gewünschten Eigenschaften auslesen können. Die Ausgabe des Scripts sehen Sie in Abbildung 12.8.

Abbildung 12.8 Ergebnis einer Suchabfrage

Die Daten zu einem Angebot können Sie mit der API-Funktion getItem bei eBay auslesen.

require_once ('Services/Ebay.php'); 
require_once('auth2.inc.php'); 
 
try 
{ 
   $session = Services_Ebay::getSession($devId, 
                                            $appId,$certId); 
   $session->setToken($token); 
 
   $getItem= Services_Ebay::loadAPICall('GetItem'); 
   // Argumente festlegen 
   $args=array('Id'=>'4502213532',  //Nummer der Auktion 
               'DetailLevel'=>'0' 
         ); 
   // Argumente festlegen 
   $getItem->setArgs($args); 
   // Session uebergeben 
   $Item=$getItem->call($session); 
 
   // Daten zu der Auktion ausgeben 
   echo "Kategorie: 
         {$Item->Category['CategoryFullName']}<br />"; 
   echo "Artikel: $Item->Title<br />"; 
   echo "Verk&auml;ufer: {$Item->Seller['UserId']}<br />"; 
   echo "Beginn der Auktion: $Item->StartTime<br />"; 
   echo "Ende der Auktion: $Item->EndTime<br />"; 
   echo "Verbleibende Zeit: {$Item->TimeLeft['Days']} Tage 
                {$Item->TimeLeft['Hours']} Stunden 
                {$Item->TimeLeft['Minutes']} Minuten 
                {$Item->TimeLeft['Seconds']} Sekunden <br />"; 
   echo "Startpreis: $Item->StartPrice<br />"; 
   echo "Sofort-Kaufen Preis: $Item->BuyItNowPrice<br />"; 
   echo "Aktueller Preis: $Item->CurrentPrice<br />"; 
} 
catch (Exception $error) 
{ 
   die ("Error: ".$error->getMessage()); 
}

Listing 12.11 Auslesen von Artikelinformationen über die API

Informationen zu einer Auktion abzurufen ist nicht so komplex wie die Auswertung, wie Sie feststellen werden.

Nachdem das API-Call-Objekt geladen worden ist, müssen die Argumente definiert werden, die der Aufruf nutzen soll. Diese werden in einem Array abgelegt. An erster Stelle ist hier natürlich das Argument Id zu nennen, in dem die Nummer der Aktion übergeben wird.

Der Wert in DetailLevel definiert, welche Daten zurückgeliefert werden sollen. Die 0 legt fest, dass (fast) alle Daten zurückgeliefert werden. Sie erhalten also ein komplettes Item-Objekt zurück, in dem alle Daten enthalten sind. Übergeben Sie die Zahl 8 als Wert, werden nur die E-Mail-Adressen des Höchstbietenden und des Verkäufers zurückgegeben. Diese Daten sind nicht enthalten, wenn Sie den Wert 0 nutzen. Weitere Werte, die allerdings zum Großteil nicht in Kombination mit ebay.de genutzt werden können, finden Sie in der API-Dokumentation zu GetItem.

Die einzelnen Argumente, die zurückgeliefert werden und in dem Item-Objekt als Eigenschaften zur Verfügung stehen, können Sie der API-Dokumentation bei der Erläuterung des Item-Objekts entnehmen.

Abbildung 12.9 Daten der Auktion im Browser

 <<   zurück
     
  Zum Katalog
Zum Katalog: PHP PEAR
PHP PEAR
Jetzt bestellen!
 Ihre Meinung?
Wie hat Ihnen das <openbook> gefallen?
Ihre Meinung

 Buchtipps
Zum Katalog: PHP 5.6 und MySQL 5.7






 PHP 5.6 und
 MySQL 5.7


Zum Katalog: Einstieg in PHP 5.6 und MySQL 5.6






 Einstieg in PHP 5.6
 und MySQL 5.6


Zum Katalog: Responsive Webdesign






 Responsive Webdesign


Zum Katalog: Moderne Websites entwickeln






 Moderne Websites
 entwickeln


Zum Katalog: MySQL 5.6






 MySQL 5.6


 Shopping
Versandkostenfrei bestellen in Deutschland und Österreich
InfoInfo








Copyright © Rheinwerk Verlag GmbH 2007
Für Ihren privaten Gebrauch dürfen Sie die Online-Version natürlich ausdrucken. Ansonsten unterliegt das <openbook> denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


[Rheinwerk Computing]

Rheinwerk Verlag GmbH, Rheinwerkallee 4, 53227 Bonn, Tel.: 0228.42150.0, Fax 0228.42150.77, service@rheinwerk-verlag.de