Die ersten drei Teile dieser Reihe hatten sich mit der theoretischen und praktischen Implementierung des User Consent Flow Prozesses, der für die Authentifizierung des Nutzers mit und der Verwendung der eBay Trading API notwendig ist, befasst. Im vierten und letzten Teil sollen die Implementierungen der letzten drei Teile (Teil 1, Teil 2, Teil 3) dieser Reihe in die Controller und Views umgesetzt und so ein visueller Anmelde- und Authentifizierungsprozess geschaffen werden.

Was wird Teil 4 dieses Guides zeigen?

Wir werden einen Prozess schaffen, der es dem Nutzer erlaubt den eBay User Consent Flow mit Hilfe unserer Webapplikation zu durchschreiten. Dieser Prozess soll möglichst unkompliziert, direkt und intuitiv bedienbar sein. Ich empfehle also die Verwendung von Ajax-Methoden um das User Interface und den darzustellenden Prozess zu visualisieren. Wie das Zend Framework mit Ajax Anfragen umgehen kann wird hier also auch Thema sein.

Warum Ajax?

Wenn wir uns eben an den Ablauf des (in Teil 1 ausführlich beschriebenen) Consent Flow Prozesses erinnern: Der Benutzer muss selbst nur wenige Klicks und Eingaben machen – namentlich die Anmeldung auf der eBay Login-Seite zu der er weitergeleitet wird. Im Hintergrund muss unsere Applikation allerdings zwei Anfragen machen. (1) Eine SessionID von der eBay trading API anfragen und (2) nach der Rückkehr des Benutzers zur Applikation den mit der SessionID verknüpften Auth-Token anfragen.

Hier empfehle ich Ajax: Dem Benutzer soll visualisiert werden, dass sich hinter den Kulissen etwas tut und nicht lange auf den Seitenaufbau warten müssen (die API-Anfragen dauern ein paar wenige Sekunden). Wir werden also die Seite ausliefern, und von dieser eine Ajax-Anfrage starten, die die getSessionID und später die fetchToken Actionen anstoßen wird. Der Benutzer wird ein Lade-Grafik sehen und damit merken, dass sich etwas tut. Die Weiterleitung soll vollautomatisch erfolgen. Das Ergebnis sieht also keinerlei Actionen vom Benutzer auf unserer Applikation vor. Er muss lediglich warten bis er zu eBay weiter geleitet wird und sich dort anmelden kann.

Die benötigten Actions

Wie in Teil 2 bereits aufgestellt brauchen wir neben dem Ebayauth Controller folgende fünf Actions:

• index (stößt den Consent Flow an)
  
• step1 (ist Ziel eines Ajax-Requests – übernimmt getSessionID)
• success (bei erfolgreichem Login auf eBay wird der Benutzer hierhin weitergeleitet)
• step2 (ist Ziel eines Ajax-Requests – übernimmt fetchToken)
• und denied (bei fehlgeschlagenem oder abgebrochenen Login)
  

und vier Views für den Controller Ebayauth:

• index.phtml
• step1.ajax.phtml
• success.phtml
  
• step2.ajax.phtml
• und denied.phtml

Ajax Requests erkennen und entsprechend handeln

Um die Unterscheidung zwischen ‘normalem’ Request und einem Ajax-Request können wir einen Context-Switcher verwenden, den uns das Zend Framework zur Verfügung stellt. Dieser muss in der init()-Methode des Controllers initialisiert werden uns sieht in unserem Fall so aus:

$contextSwitch = $this->_helper->getHelper('AjaxContext');
$contextSwitch->addActionContext('step1', 'html') // wir geben html zurück
              ->addActionContext('step2', 'html') // möglich wäre auch xml oder json
              ->initContext();

// Das übrige Layout abschalten
if($this->_request->isXmlHttpRequest()) {
     $this->_helper->layout->disableLayout();
}

Unsere zwei step Actions benötigen noch eine kleine Fallunterscheidung. Wir möchten sie nur ausführen lassen, wenn es sich tatsächlich um einen Ajax-Request handelt:

if(!$this->_request->isXmlHttpRequest()) {
    $this->_redirect('/ebayauth/index'); // zum Start des Auth-Prozesses umleiten
}

Der Controller Ebayauth

Springen wir gleich in den Code:

public function indexAction() {}

public function step1Action()
{
    if(!$this->_request->isXmlHttpRequest()) {
        $this->_redirect('/ebayauth/index');
    }

    // die getSessionID API-Anfrage durchführen
    $tokenAdapter = new Ebay_Auth_ConsentFlow();
    $return = $tokenAdapter->getSessionID();

    // Wir müssen die SessionID in einer Datenbank oä. zwischenspeichern
    $modelAccount = new Model_Account();

    if($return != false) {
        // zwischenspeichern - bitte durch eigenen Implementierung ersetzen
        $modelAccount->writeEbaySessionId($this->accountID, $return['sessionId']);
        if(isset($return->ShortMessage)) {
            // bei Fehler ist ShortMessage teil der API Rückgabe
            $this->view->error = (string)$return->ShortMessage;
        } else {
            $this->view->redirectURL = $return['redirectUrl'];
        }
    } else {
        $this->view->error = 'Keine Verbindung zu eBay.';
    }
}

public function successAction() {}

public function step2Action()
{
    if(!$this->_request->isXmlHttpRequest()) {
        $this->_redirect('/ebayauth/index');
    }

    // die im step1 zwischengespeicherte SessionID aus der Datenbank holen
    $modelAccount = new Model_Account();
    $sessionId = $modelAccount->getEbaySessionId($this->accountID);

    // die fetchToken API Anfrage ausführen
    $tokenAdapter = new Ebay_Auth_ConsentFlow();
    $return = $tokenAdapter->getToken($sessionId);

    if($return != false) {
        // auch hier wieder eigenen Implementierung Verwenden
        $modelAccount->writeEbayTokenId($this->accountID, $return['token'], $return['expiration']);
        if(isset($return->ShortMessage)) {
            $this->view->error = (string)$return->ShortMessage;
        } else {
            // Hier festlegen wohin umgeleitet werden soll
            $this->view->redirectURL = '/'; // zurück zur Startseiten
            $this->view->expiration = $return['expiration'];
        }
    } else {
        $this->view->error = 'Keine Verbindung zu eBay';
    }
}

public function deniedAction() {}

Die drei Actions index, success und denied benötigen keine Methoden im Controller. Der JavaScript, der den Ajax-Request anstößt coden wir einfach fest in die views ein.

Die Views

Das hier ist der index view (index.phtml). Wir binden ein JavaScript ein und rufen die Funktion shootAjaxHtml() auf.

<div>
    <div id="loader" class="redirect"><img src="/images/preloader.gif" /> Weiterleitung an eBay wird vorbereitet ...
        <script type="text/javascript">shootAjaxHtml('/ebay/step1', 'loader')</script>
    </div>
</div>

Der step1.ajax.phtml View:

<?php if(isset($this->redirectURL)) { ?>
<p>Automatische Weiterleitung zu eBay in wenigen Sekunden. <a href="<?php echo($this->redirectURL); ?>" title="Weiterleitung">Oder hier klicken.</a></p>
<script type="text/javascript">window.location = '<?php echo($this->redirectURL); ?>';</script>
<?php } elseif(isset($this->error)) { ?>
<p class="error"><strong>Fehler:</strong> <?php echo $this->error; ?></p>
<?php } ?>

success.phtml:

<div>
    <div id="loader" class="redirect"><img src="<?php echo SKINPATH; ?>/images/preloader.gif" /> eBay Anmeldung wird abgeschlossen ...
        <script type="text/javascript">shootAjaxHtml('/ebay/authgettoken', 'loader')</script>
    </div>
</div>

Und step2.ajax.phtml:

<?php if(isset($this->redirectURL)) { ?>
<p class="info">Die Verknüpfung des Benutzerkontos mit eBay verliert am <?php echo date('d.m.Y', strtotime($this->expiration)); ?> um <?php echo date('H:m', strtotime($this->expiration)); ?> Uhr seine Gültigkeit.</p>
<p><a href="/ebay" class="black" title="Zurück zur Startseite">Weiter</a></p>
<?php } elseif(isset($this->error)) { ?>
<p class="error"><strong>Fehler:</strong> <?php echo $this->error; ?></p>
<?php } ?>

Im denied View gebe ich nur eine Fehlermeldung wie “Anmeldung fehlgeschlagen”.

Der JavaScript (mit mootools):

function shootAjaxHtml(action, loaderid)
{
    var remote = new Request.HTML({
        url: action + "?format=html",
        onSuccess: function(html) {
            $(loaderid).getParent('div').empty().adopt(html);
        },
        onFailure: function(xhr) {
            $(loaderid).getParent('div').empty().adopt(new Element('p').set('text', 'Es ist ein Fehler aufgetreten: ' +xhr.status +' ' +xhr.statusText).addClass('error'));
        }}).get();
}

Und damit sind wir auch schon fertig.

Ich hoffe die ersten drei Teile dieser Einführung in eine Mögliche Implementierung des Consent Flows der eBay trading API in eine Webapplikation mit dem Zend Framework waren gut verständlich und konnten einen guten Überblick über die benötigten Implementierungsschritte geben. Teil vier hat anhand von Codebeispielen gezeigt, wie man den Consent Flow möglichst benutzerfreundlich umsetzen kann.

Empfehlungen, Anmerkungen, Verbesserungsvorschläge? Dazu sind die Kommentare da!

In den beiden ersten Teilen dieses Guides habe ich einen Überblick über die Funktionsweise und den Aufbau des user Consent Flow von eBay Applikationen in Verbindung mit der eBay trading API geschaffen (zum ersten Teil dieses Guides) und den Aufbau unseres Ebay API Adapters und die Implementierung mit Hilfe des Zend Frameworks erläutert (zum zweiten Teil dieses Guides).

Was werde ich hier in Teil 3 beschreiben?

Dieser Teil beschäftigt sich mit der Implementierung des Auth bzw. des Consent Flow Prozesses der eBay trading API. Wir werden uns einen Überblick über die benötigten Klassen und Methoden schaffen und diese dann mit Hilfe des Zend Frameworks in unser bereits vorhandenes Projekt implementieren. Unsere Aufmerksamkeit widmen wir der Ebay_Auth_ConsentFlow Klasse und deren Methoden GetSessionID() und fetchToken(). Außerdem werden wir anhand dieser zwei API-Anfragen die API-Rückgabe untersuchen.

Die Klasse Ebay_Auth_ConsentFlow

Wir benötigen die Klasse Ebay_Auth_ConsentFlow um das Ziel, einen validen AuthToken von der eBay trading API zu erhalten. Wie in Teil 1 dieses Guides beschrieben läuft der eBay User Consent Flow in drei Schritten ab: (1) Session ID anfragen, (2) User zum eBay Anmeldeformular weiterleiten und (3) AuthToken anfragen. Erst mit dem AuthToken können wir im Namen des Nutzers Aktionen mit der eBay trading API durchführen.

Auf Schritt 2 haben wir mit unserer Implementierung keinen Einfluss. Viel mehr müssen wir uns um die beiden API-Anfragen GetSessionID (1) und ConsentFlow (2) kümmern. Die GetSessionID Anfrage implementieren wir in gleichnamiger Methode unserer Ebay_Auth_ConsentFlow Klasse. Die FetchToken Anfrage werden wir analog in der Methode fetchToken() unterbringen. Hier noch einmal der Ablauf:

1. Ebay_Auth_ConsentFlow->getSessionID() aufrufen
   und bei der trading API eine sessionID anfragen
2. Ebay_Auth_ConsentFlow->fetchToken($sessionID)  aufrufen
   und – vorausgesetzt der Benutzer hat sich erfolgreich auf eBay eingelogged – den zur sessionID gehörigen AuthToken erhalten

Zur Erinnerung:

• Die getSessionID Methode wird direkt vom Controller aufgerufen und muss im Erfolgsfall die eBay Signin URL – an die der Benutzer weiter geleitet werden soll – zurück geben.
• Die callApi Methode erwartet die folgenden Parameter:

  callApi($verb, $request, $aditionalXml = true, $requestCredentials = true, $serverUrl = null)
  

  Die GetSessionID Anfrage benötigt keine zusätzlichen XML Paramter und auch keine requestCredentials.

• Die callApi Methode gibt ein zweielementiges Array zurück. Einen Statusflag (‘Success‘) und die Originalantwort (‘Response‘) der eBay API.

Die Implementierung der getSessionID Methode

Werfen wir nun einen Blick auf die getSessionID() Methode:

class Ebay_Auth_ConsentFlow extends Ebay_Abstract
{
    public function getSessionID()
    {
        $callVerb = 'GetSessionID';
        $xmlBody  = '<RuName>' . $this->_apiAdapter->_ruName . '</RuName>';
        $response = $this->_apiAdapter->callApi($callVerb, $xmlBody, false, false);

        if($response['Success'] == false) {
            $return = $response['Response']->shortMessage;
        } else {
            $return = array(
                'redirectUrl' => $this->_apiAdapter->_signinUrl .
                                 '&RuName=' . $this->_apiAdapter->_ruName .
                                 '&SessID=' . $response['Response']->SessionID,
                'sessionId'   => $response['Response']->SessionID
            );
            return $return;
        }
    }
}

Der Vollständigkeit halber und um die Referenz auf $this->_apiAdapter in Zeile 6 erklären zu können hier noch die rudimentäre Ebay_Abstract Klasse. Ebay_Auth_ConsentFlow und alle anderen Ebay API Request Klassen erben den folgende Konstruktor:

class Ebay_Abstract
{
    protected $_apiAdapter;

    public function __construct()
    {
        if(!isset($this->_apiAdapter)) {
            $this->_apiAdapter = Ebay_Api_Adapter::getInstance();
        }
    }
}

Wie zu sehen ist, ist der eigentliche Aufbau des API-Request denkbar einfach.  Wir erstellen den XML-String und setzen mit $callVerb (Zeile 5) den korrekten Anfragen-Namen. Alles weitere macht unsere CallApi Methode der Klasse Ebay_Api_Adapter. Die getSessionID Anfrage benötigt als einzigen Paramter den ruNamen der Applikation um das mit der SessionID verknüpfte eBay Login-Formular mit dem Logo und der Beschreibung unserer Applikation zu versehen.

Als Rückgabe an den Controller sollte uns die getSessionID() Methode eine Sandbox Signin-URL der Form https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RuName=ruNameDerApplikation&SessID=dieAngefragteSessionID zurückgeben.

Wie der Controller und die Views aussehen erkläre ich später in Teil 4 dieses Guides. Nur so viel vorweg: Ich muss zwangsläufig die SessionID mit dem Benutzer Account verknüpfen, damit später sichergestellt werden kann, dass die korrekte SessionID des Benutzers der Methode fetchToken() übergeben wird. Der Benutzer verlässt unsere Seite zwangsläufig für den Login-Prozess für einen kurzen Augenblick. Wir möchten ihn auch nicht aus den Augen verlieren und seine SessionID wieder vergessen.

Die Implementierung der fetchToken Methode

Steigen wir direkt ein – viel Neues gibt es hier nicht:

public function fetchToken($sessionID)
{
    $callVerb  = 'FetchToken';
    $xmlBody   =
        '<SessionID>' . $sessionID . '</SessionID>';
    $response  = $this->_apiAdapter->callApi($callVerb, $xmlBody, false, false);

    if($response['Success'] == false) {
        return $response['Response']->ShortMessage;
    } else {
        return array(
            'token' => $response['Response']->eBayAuthToken,
            'expiration' => date('Y-m-d H:i:s', strtotime($response['Response']->HardExpirationTime))
        );
    }
}

Auch die fetchToken() Methode rufen wir direkt aus dem Controller auf. Wir übergeben die SessionID und erhalten im Idealfall ein zweielementiges Array mit Token und Gültigkeitsdauer des Tokens zurück.

Die Rückgabe der eBay trading API

Anhand dieser zwei API-Anfragen möchte ich hier die beiden XML API-Rückgaben vorstellen:

GetSessionID-Anfrage:

RuName =
'ruNameUnsererApplikation'

Der einzige hier zu übergebende Parameter ist der ruName unserer Applikation.

GetSessionID-Antwort:

Timestamp =
'2010-01-26T20:35:46.118Z'
Ack =
'Success'
Version =
637
Build =
'E637_INTL_BUNDLED_10223050_R1'
SessionID =
'b0**...*f74'

Als Antwort erhalten wir die SessionID.

FetchToken-Anfrage:

SessionID =
'b0**...*f74'

Auch hier muss nur ein Paramter – die SessionID – übergeben werden.

FetchToken-Antwort:

Timestamp =
'2010-01-26T20:31:58.283Z'
Ack =
'Success'
Version =
637
Build =
'E637_INTL_BUNDLED_10223050_R1'
eBayAuthToken =
'AuthToken'
HardExpirationTime =
'2011-07-20T20:27:32.000Z'

Die Antwort enthält den AuthToken und seine Gültigkeitsdauer.

Unsere Api_Adapter und User Consent Flow Implementierung ist damit fast fertig. Wie Controller und Views – und damit unser Frontend – implementiert werden, das soll Thema von Teil 4 dieses Guides sein.

Im ersten Teil dieses Guides hatten wir uns einen Überblick über den Consent Flow und eBay Authentifizierung unserer Nutzer geschaffen und so die Voraussetzung zur praktischen Umsetzung mit dem Zend Framework geschaffen.

Was werde ich hier in Teil 2 beschreiben?

Dieser Teil widmet sich dem Aufbau und Implementierung der Ebay_Api_Adapter Klasse, die wir verwenden werden um Anfragen an die eBay trading API zu senden. Wir benötigen Methoden zur Generierung und Auslieferung der Anfragen und eine geeignete Fehlerbehandlung. Exemplarisch und anhand von Code-Beispielen soll das hier in Teil 2 gezeigt werden.

Unsere Webapplikation muss nicht nur Anfragen an die eBay API senden, sondern auch den Überblick über SessionIDs und Tokens seiner Benutzer behalten. Wir sind also gezwungen diese – in unserem Fall in einer Datenbank – zwischen zu speichern:

Das bedeutet sogleich, dass unsere Applikation auch ein User-System haben muss, so dass die zurückgegebenen SessionIDs und Tokens mit den korrekten Benutzern verknüpft werden können. Ich möchte dies hier nicht noch ausführlich herleiten, sondern setze dieses Feature in der Basis-Applikation voraus. Ich nutze dafür Zend_Acl und ein klassisches User-System mit Register-, Login- und Logout Funktionen. Um voraus zu planen und es eventuell später mehren Nutzern gleichzeitig zu ermöglichen mit einem eBay Account zu arbeiten wird es in meiner Users Tabelle eine account_id und eine n:1 Verknüpfung mit der id des eBay Accounts in der Tabelle Accounts geben. Der Controller User und die dazugehörigen Funktionen existieren also schon.

Die benötigten Controller und Klassen

Für unsere eBay Applikation brauchen wir einen neuen Controller (Ebayauth) und eine neue Library (Ebay) in der wir unsere eBay spezifischen Klassen unterbringen. Wir benötigen:

• Einen Controller Ebayauth
• Fünf Actions (index, step1, step2, success und denied) und fünf Views für den Controller Ebayauth: index.phtml, step1.ajax.phtml, step2.ajax.phtml, success.phtml und denied.phtml
• Eine neue Library mit Namespace Ebay_ (nicht vergessen einen Autoloader im bootstrap anzupassen)
• Zwei Ebay_ Klassen: Ebay_Api_Adapter und Ebay_Auth_ConsentFlow
• Eine keys.xml in der Library Ebay

Die Klasse Ebay_Api_Adapter

Die keys.xml erlaubt es uns unsere API-Keys in einer schönen, ausgelagerten XML zu verwalten anstatt sie hardcoded in der Klasse zu lagern. Werfen wir zunächst einen Blick auf den Constructor, die setOptions Methode und die keys.xml:

class Ebay_Api_Adapter
{
    public function __construct($configfile = 'keys.xml')
    {
        $configfile = '../library/Ebay/' . $configfile;
        $configXml = new Zend_Config_Xml($configfile);
        $this->setOptions($configXml->keys->toArray());
        $this->setOptions($configXml->options->toArray());
    }

    // statische Instanz-Rückgabe
    public static function getInstance()
    {
        if (self::$_instance === null) {
            self::$_instance = new self();
        }
        return self::$_instance;
    }

    private function setOptions($options = array())
    {
        if(is_array($options)) {
            foreach($options as $key => $value) {
                $key = '_' . $key;
                $this->$key = $value;
            }
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?><ebay>
<keys>
    <devId>hier-eintragen</devId>
    <appId>hier-eintragen</appId>
    <certId>hier-eintragen</certId>
    <ruName>hier-eintragen</ruName>
</keys>
<options>
    <siteId>77</siteId>
    <warningLevel>High</warningLevel>
    <compatLevel>647</compatLevel>
    <errorLanguage>77</errorLanguage>
    <serverUrl><![CDATA[https://api.sandbox.ebay.com/ws/api.dll]]></serverUrl>
    <signinUrl><![CDATA[https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn]]></signinUrl>
</options></ebay>

Zu den Optionen in der keys.xml möchte ich noch ein paar Worte loswerden:

• siteID 77 entspricht eBay.de und errorLanguage 77 entspricht Deutsch
• warningLevel ist während wir mit der Sandbox arbeiten auf High gesetzt.
• compatLevel 647 ist die aktuelle eBay trading API Version mit der wir arbeiten möchten.
• serverURL ist unser Ansprechpartner für sämtliche API-Requests.
• signinURL verwenden wir für die Weiterleitung des Benutzers zum Consent Flow.

Für den HTTP-Request (POST) an die eBay trading API nutzen wir Zend_Http_Client. Die API möchte von uns eine Reihe HTTP-Header gesetzt sehen, bevor sie antworten wird. Dazu folgende Funktion:

private function setHeaders()
{
    $this->_headers = array (
        // Die eBay trading API Version, die wir unterstützen
        'X-EBAY-API-COMPATIBILITY-LEVEL: ' . $this->_compatLevel,

        // Unsere Keys und Zertifikate
        'X-EBAY-API-DEV-NAME: '    . $this->_devId,
        'X-EBAY-API-APP-NAME: '    . $this->_appId,
        'X-EBAY-API-CERT-NAME: '   . $this->_certId,

        // Der Name jeder eBay API Anfrage muss im Header noch einmal benannt werden
        'X-EBAY-API-CALL-NAME: '   . $this->_callVerb,
        'X-EBAY-API-SITEID: '      . $this->_siteId,

        // Wichtig: Den Content Type der Daten, die wir senden
        'Content-Type: text/xml; charset=utf-8'
    );
    $this->_request = new Zend_Http_Client();
    $this->_request->setUri($this->_serverUrl);
    $this->_request->setHeaders($this->_headers);
}

Sind die Header gesetzt, so können wir mit dem Zend_Http_Client Object ($this->_request) eine Anfrage senden. Der eigentliche Inhalt der Anfrage wird mittels POST mitgesendet. Das eigentliche Herzstück unseres API Adapters ist die Methode callApi, die wie folgt Abläuft:

1. Die Header setzen
   Wir übergeben der callApi Methode die Bezeichnung des Requests als Parameter und rufen damit die setHeaders() Methode auf. Diese baut die Header zusammen und erstellt ein neues Zend_Http_Client Objekt (siehe oben).
2. Den Request Body zusammensetzen
   Abhängig vom Typ der API Anfrage müssen wir den String des Request-Bodys (xml) zusammensetzen. Eine getSessionID verlangt andere (und weniger) Optionen als eine reguläre Anfrage.
3. Den Http_Client mit dem Request Body versehen und absenden
   Den zuvor in der setHeaders() Methode erstellten Http_Client übergeben wir den Request Body und senden den Request mittels POST an den API-Server. Die Rückgabe speichern wir in einer Variable.
4. Die Rückgabe auswerten und Fehler abfangen
   Die Rückgabe (xml) hat je nach API Anfrage eine bestimmte Form, die wir auswerten müssen. Hier muss auch unsere Fehlerbehandlung implementiert werden.

Hier die Implementierung der callApi Methode der Klasse Ebay_Api_Adapter:

public function callApi($verb, $request, $aditionalXml = true, $requestCredentials = true, $serverUrl = null)
{

    if($serverUrl == null) {
        $serverUrl = $this->_serverUrl;
    }

    $this->_callVerb = $verb;

    $this->setHeaders();

    $requestBody =
        '<?xml version="1.0" encoding="utf-8"?>' .
        '<' . $verb . ' xmlns="urn:ebay:apis:eBLBaseComponents">';

    // request Credentials werden nur bei regulären, nicht bei
    // getSessionID oder fetchToken Anfragen benötigt
    if($requestCredentials) {
        $requestBody .=
            '<RequesterCredentials>' .
            '<eBayAuthToken><![CDATA[' . $this->getToken() . ']]></eBayAuthToken>' .
            '</RequesterCredentials>';
    }

    // Auch diese Optionen benötigen wir nur für reguläre Anfragen
    if($aditionalXml) {
        $requestBody .=
            '<ErrorLanguage>' . $this->_errorLanguage . '</ErrorLanguage>' .
            '<WarningLevel>'  . $this->_warningLevel  . '</WarningLevel>';
    }

    $requestBody .=
        $request . '</' . $verb . '>';

    $this->_request->setUri($serverUrl);
    $this->_request->setRawData($requestBody);
    $response = $this->_request->request('POST');

    $this->responseHeader   = $response->getHeaders();
    $this->responseBody     = $response->getBody();

    // die Rückgabe wandeln wir in ein (hoffentlich gültiges)
    // XML Element um
    $xml = @simplexml_load_string($this->responseBody);

    // Existiert in der Rückgabe kein ACK-Feld (zB. weil der ebay
    // Server nicht geantwortet hat) oder ist es nicht 'Success',
    // so ist etwas schief gelaufen
    if(!isset($xml->Ack) || $xml->Ack != 'Success') {
        $errors = 'Keine Antwort von eBay';
        if(isset($xml->Errors))
            $errors = $xml->Errors;
        return array('Success' => false, 'Response' => $errors);
    }

    return array('Success' => true, 'Response' => $xml);
}

Die in Zeile 21 verwendete gettoken() Methode (siehe unten) gibt mir den mit dem User Account verknüpften Token zurück (Siehe Schaubild oben), ist aber optional und setzt ein User-Model voraus. Alternativ oder zu Testzwecken lässt sich der Token auch in der keys.xml hinterlegen und der Funktionsaufruf in Zeile 21 durch ein $this->_token() ersetzen.

public function getToken()
{
    $accountId        = Zend_Auth::getInstance()->getIdentity()->account_id;
    $modelAccount    = new Model_Account();
    return $modelAccount->getEbayToken($accountId);
}

Mit dieser Implementierung können wir nun beliebige eBay trading API Anfragen versenden. Im dritten Teil dieses Guides beschreibe ich die Implementierung der Klasse Ebay_Auth_ConsentFlow.

Erst mit guter Dokumentation macht es Sinn.

Und gut dokumentiert, das ist sowohl das Zend Framework, wie auch die eBay trading API. Sinn macht es also beide zu kombinieren um schnell große eBay-Webapplikationen zu schaffen. Das Zend Framework erlaubt ein rapid PHP development und die eBay trading API ermöglicht es so ziemlich alles, was der Nutzer auf der eBay-Webseite sowieso schon tun kann in die eigenen Webapplikation zu klonen. Natürlich gibt es auch hier best practices – wie ich das ganze angegangen bin, dass möchte ich hier im folgenden beschreiben.

Was werde ich hier in Teil 1 beschreiben?

Webapplikationen, die die eBay trading API verwenden und damit für einen eBay Nutzer in seinem Namen Aktionen auf der eBay-Webseite durchführen, müssen einen Authorisationsprozess durchlaufen. Nutzer der Webapplikation müssen sich als eBay Nutzer identifizieren und die Applikation authorisieren Aktionen in ihrem Namen durchzufüren. Diesen Prozess möchte ich hier exemplarisch in einer Webapplikation mit Hilfe des Zend Framework abbilden und so den ersten Teil einer jeden eBay-Webapplikation beispielhaft beschreiben.

Was benötigen wir um mit der eBay trading API zu arbeiten?

1. Einen eBay Developers Program Account (https://developer.ebay.com)
   Das eBay Developers Program bietet Zugriff auf die eBay APIs und eine umfangreiche Dokumentation und Support. Es existieren Foren, Referenzen und zahlreiche Code-Beispiele. Ein solcher Account ist zwingen notwendig um die eBay trading API überhaupt ansprechen und nutzen zu können.
2. Mindestens einen eBay Sandbox Account (https://sandbox.ebay.com)
   Es ist notwendig seine Applikationen in der eBay Sandbox zu entwickeln. Die Sandbox ist eine der original eBay Umgebung ähnelnde Spielwiese in der man zunächst einmal nichts kaputt machen und nach Lust und Laune seine Programme entwickeln und testen kann. Mindestens einen Account brauchen wir hier um in dessen Namen die trading API nutzen zu können. Empfehlen kann ich auch einen zweiten Account um beispielsweise und zu testzwecken Produkte des ersten Accounts zu ersteigern.
3. Ein Set Sandbox API Keys (werden über den developers Account angelegt)
   Dazu zählen:
   • Die devID – sie identifiziert uns als Entwickler beim Verwenden der eBay trading API
   • Die AppID – sie identifiziert unsere Applikation beim Verwenden der eBay trading API
   • Eine CertID – ein Zertifikat, dass wir beim Ansprechen der eBay trading API benötigen
   • Ein RuName - mit dem wir das eBay Anmeldeformular beim Authorisierungsprozess gestalten können
     Der RuName wird beim Konfigurieren des Consent Flow (der Authorisierungsprozess) im developers Account generiert. Uns wird beispielsweise die Möglichkeit gegeben das Anmeldeformular mit einem Logo unserer Applikation zu versehen.

Was benötigen wir um mit dem Zend Framework zu arbeiten?

1. Eine aktuelle Version des Zend Servers (Community Edition) und das dazugehörige Zend Framework. Ich verwende das Zend Framework in der Version 1.9.5 und den Zend Server mit der PHP Version 5.2.11.
2. Ich empfehle das Entwicklertool Zend Studio und Erfahrung, was das Arbeiten mit PHP, XML, dem Zend Framework und die Konfiguration eines Webservers angeht. Sollte das Zend Framework bis jetzt völlig unbekannt sein, dann möchte ich zunächst auf die zahlreichen Bücher zum Thema und die vielen Tutorials im Internet verweisen. Ich werde hier keine Einführung in das Framework geben.

Was benötigen wir sonst noch für unsere eBay Webapplikation?

1. Einen MySQL Server oder eine andere Datenbank. Ich verwende hier eine MySQL Datenbank in Verbindung mit der Zend_Db_Table Class, die eine abstraktion Layer besitzt und damit auch für andere Datenbanktypen verwendet werden kann.
2. Ein JavaScript Framework für unsere Ajax-Calls. Natürlich ist kein Framework notwendig, aber es macht die Frontendentwicklung und vor allem unsere Ajax Funktionen wunderbar einfach zu implementieren. Ich verwende mootools, kann aber auch jQuery empfehlen. Wichtig bei der Auswahl des Frameworks ist es, dass die Ajax-Requests ein XmlHttpRequest-Header mitsenden.
3. Eine Basis-Applikation mit einem eingerichtetem Layout, die es dem Benutzer erlaubt sich in unserer Applikation einzuloggen.

Der eBay User Consent Flow

Wenn all das geklärt wurde, dann werden wir hier in Teil1 zunächst mit der Theorie beginnen: Wie sieht der User Consent Flow bei eBay aus? Dazu folgende Grafik:

1. Schritt
   Unsere Applikation wird die eBay API nach einer SessionID beten. Dazu schicken wir den ruName unserer Applikation mit, damit eBay das konfigurierte Anmeldeformular (inklusive unseres tollen Applikationslogos und der Redirect-URLs) generieren und mit der SessionID verknüpfen kann. Als Antwort erhalten wir also eine SessionID, die wir dann verwenden um die Parameter der URL des Anmeldeformulars zu generieren und den Benutzer dann im zweiten Schritt …
2. Schritt
   … an diese URL weiterzuleiten. Dort gibt er sein eBay Passwort und Nutzernamen ein und bestätigt, dass er unserer Webapplikation erlaubt in seinem Namen auf eBay Aktionen durchzuführen. Hat er bestätigt, leitet eBay den Benutzer wieder zurück zu unserer Applikation, die daraufhin im dritten Schritt …
3. Schritt
   … eine fetchToken Anfrage an die eBay API senden kann. Mit der fetchToken Anfrage geben wir gleich die zuvor erhaltene SessionID mit. Wurde diese SessionID verwendet und hat sich der Nutzer mit dieser SessionID im Zuge des Schritt 2 auch korrekt angemeldet, so erhalten wir einen ca. 900 Zeichen langes Token zurück gibt. Dieses Token muss unsere Applikation bei jeder API-Anfrage mitsenden und sich so autorisieren.

Wie die Theorie mit dem Zend Framework möglichst schnell und unkompliziert in die Praxis umgesetzt werden kann werde ich im zweiten Teil dieses Guides beschreiben. Ich gehe konkret auf die benötigten Klassen ein und werde zahlreiche Code-Beispiele geben.