Plugin Class mit API Ressource

Das Beispiel zeigt, wie Sie die API um eine eigene Ressource bspw. eine eigene Plugin-Methode erweitern können.

Anwendungsbeispiel

Im nachfolgenden Beispiel soll die Shop-API um eine Ressource, also eine selbst programmierte Klassen-Methode ( product_importBulk($params)) erweitert werden, die eine Liste von Produkten zum Import übergeben werden kann. Mit einer solchen "Bulk"-Methode kann z.B. der Import von Produkten über die API beschleunigt werden, da die Anzahl der Server-Requests kann so deutlich verringert wird.

Vorgehen / Setup

Methode erstellen
Im Prinzip ist egal wo in welchen (eigenen) Klassen sich letztendlich die Methoden befinden, aber natürlich macht es Sinn sich dies nach allgemeingültigen Programmierstrukturen und ggfs. eCMS-Plugin-Strukturen gut zu überlegen und zu verteilen.
Siehe dazu, den folgenden Source Code und die beispielhaften IN-Parameter und RETURN-Values.
Methode für API freischalten
Nachdem die Methode programmiert wurde, kann sie im API-Manager als eine Ressource dort eingetragen, d.h. registriert werden. Dann erst ist sie über die API von außen überhaupt aufrufbar! Weitere Zugriffskontrollen können dann komfortabel über den API-Manager konfiguriert werden.
[ API-Configs in Plugin-Installern ]
API-Ressourcen-Configs können jeweils eigenen Plugins zugewiesen werden, sodass diese später einfach komfortabel installiert werden können. (HIER aber nicht weiter beschrieben!)
Somit können Sie solche Configs direkt in Ihr Plugin mitintegrieren zu Ihren programmierten Methoden oder aber einfache dazu passende "on-top-API-Plugins" erstellen, die lediglich die API-Configs enthalten (empfehlenswert...!).

IN Parameter

Als Parameter erhält die Methode das ISO-Kürzel (z.B. " DE" für Deutsch oder " EN" für Englisch) der Import-Sprache und die Liste ("bulk") der Import-Produkte.

Für jedes Produkt muss ein Produktcode (" pcode") übergeben werden. Die restlichen Produktfelder können sich pro Produkt unterscheiden.

$params['bulk'] = array(
	    array(
	        'pcode' => 'product123',
	        'name' => 'Produkt 123',
	        'desc' => 'Die Beschreibung zum Produkt 123 ...',
	    ),
	    array(
	        'pcode' => 'productXYZ',
	        'price' => 799.49,
	        'vat' => 19,
	    ),
	    ...    
	)

Result Daten

Im Erfolgsfall liefert die Mehtode nur einen Erfolg-Status zurück. Im Fehlerfall wird eine Fehler-Meldung für die fehlgeschlagenen Produkte zurückgeliefert.

Sourcecode

In unserem Beispiel hier, erstellen wir eine eigene PHP-Klasse my_api_extend und fügen dort unsere Methode product_importBulk($params), die wir über die API freischalten wollen ein.

class my_api_extend extends ecs_eApplication{
	/**
	 * Import einer Liste von Produkten
	 *
	 * @param    Array $params must.
	 * [lang_iso] - String, must.  ISO Kürzel der Import-Sprache
	 * [bulk] - Array, must.  Produkt Liste
	 *         [<n>][pcode] - String, must.  Eindeutiger Produktcode
	 *         [<n>][<fields>] - Mixed.  Weitere Produkt und Preis Felder
	 *
	 * @return    Array.
	 * %r_status_msg%
	 */
	public function product_importBulk($params)
	{
	    $R = array('status'=>true, 'msg'=>null);
 
	    /**
	     * Schleife über die Produkt-Import-Liste.
	     */
	    foreach ($params['bulk'] as $product)
	    {
	        /**
	         * Prüft ob ein Produkt zum Produktcode vorhanden ist.
	         *
	         * Über die Vererbung von "ecs_eApplication" erhält die Klasse
	         * mit "$this->eCS" einen Pointer auf den aktiven Shop.
	         *
	         * Über den "filter" Parameter erfolgt die Suche nach dem
	         * Produkt in der Import-Sprache.
	         *
	         * Über die Parameter "skip_state" und "skip_storage" werden die
	         * Prüfung nach auf den Status und Lagerbestand deaktiviert. Damit
	         * auch Offline und Ausverkauft Produkt gefunden werden.
	         *
	         * Mit dem Parameter "skip_variants" wird die Abfrage von Varianten
	         * deaktiviert, was die Abfrage beschleunigt.
	         */
	        $prdGet = $this->eCS->ecs_product->product_get(
	            array(
	                'filter' => array(
	                    'pcode' => $product['pcode'],
	                    'xc__lang_iso' => $params['lang_iso'],
	                ),
	                'skip_state' => true,
	                'skip_storage' => true,
	                'skip_variants' => true,
	            )
	        );
 
 
	        if (is_array($prdGet['data'])==true && $prdGet['data']['xc__id']>0){
 
	            /**
	             * Das Produkt ist bereits vorhanden und wird jetzt aktualisisert.
	             */
	            $prdWrite = $this->eCS->ecs_product->product_update(
	                array(
	                    'filter' => array('xc__id' => $prdGet['data']['xc__id']),
	                    'fields' => $product,
	                    'xc__lang_iso' => $params['lang_iso'],
	                )
	            );
 
 
	        }  else {
 
	            /**
	             * Neues Produkt. Wird jetzt im Shop angelegt.
	             */
	            $prdWrite = $this->eCS->ecs_product->product_create(
	                array(
	                    'fields' => $product,
	                    'xc__lang_iso' => $params['lang_iso'],
	                )
	            );
 
	        }
 
 
	        if ($prdWrite['status']==true){
	            /**
	             * Speichern des Produktes war erfolgreich.
	             */
	            $this->log_ok('Produkt "'.$product['pcode'].'" in Sparache "'.$params['lang_iso'].'" erfolgreich importiert.');
 
	        } else {
	            /**
	             * Fehler in Produkt Import erkannt.
	             */
	            $this->log_error('Fehler bei Import von Produkt "'.$product['pcode'].'" in Sparache "'.$params['lang_iso'].'".');
 
	            $R['msg'][] = $this->msg_error('Import-Fehler bei Produkt "'.$product['pcode'].'".');
	            $R['status'] = false;
	        }
	    }
 
 
	    return $R;
	}
	}

API Ressource anlegen

Um die Plugin-Methode in der Shop-API zu aktivieren, muss eine neue API Ressource anlegt werden. Ein API Ressource können Sie im eCMS Backup unter "Administration > API Verwaltung > Ressourcen" anlegen. Als aktive Site muss das Shop-Frontend ausgewählt sein.

Wenn Sie die neue API Ressource in die Standard-eCS-API einfügen, vergeben Sie bitte ein projektbezogenes Ressourcen Label um Konfikte mit Standard-API-Ressouren zu vermeiden. Alternative können Sie auch eine eigene API ("Administration > API Verwaltung > APIs") erstellen. In Ihrer eigenen API sind Sie vor Namenskonflikten mit der Standard-API geschützt.

Im Feld "Ressourcen Komponente" tragen Sie den Aufrufpfad zu Ihrer Plugin-Methode ein.

In den "defaults" Parameter können Sie Standard-Wert für Parameter hinterlegen, wenn diese im API Aufruf nicht übergeben wurden. In unserem Beispiel setzen wir für die Import-Sprache standardmäßig auf "DE".

In den "whitelist" Parameter müssen die Parameter freigeschaltet werden, die von aussen an die API-Ressource übergeben werden können. In unserem Beispiel sind dies "lang_iso" für die Import-Sprache und "bulk" für die Produkt-Liste.

Nach dem Anlegen der Ressource muss diese für die Verwendung noch freigeschaltet werden.

Die Freischaltung einer Ressource erfolgt über die "User für Ressource aktivieren/deaktivieren..." Aktion in der API Ressourcen Liste. Wählen Sie im Dialog den API User aus, den Sie für die API Ressource freischalten möchten und bestätigen Sie die Freigabe mit "OK".