person_getList

Methode zum Abrufen einer Kundenliste.

Datenfelder

Informationen zu den Datenfelder eines Kunden finden Sie unter: Daten-Typ "Kunde".

Schema

Parameter - Array

$Params	Pflicht	Beschreibung	Beispiel
[fields]	optional	String/Array (faster). Liste der Fields, die returned werden sollen. Wird nichts angegeben wird "*" angenommen, d.h. alle im Model hinterlegten Felder. Es sollten nur die Felder angegeben werden, die auch wirklich benötigt werden. Speziell bei Multi-Table-Models werden dann auch nur die Tables im SELECT dazu geJOINed, die benötigt werden.	Als String: "firstname,lastname,birthday". Als Array: [0] = "firstname" [1] = "lastname" [2] = "birthday"
[filter][<field>]	optional	mixed. Pro Field kann hier ein Wert angegeben werden, der dann im WHERE-Statement aufgenommen wird. Im Falle eines virtuellen Fields, wird das in "drvd_select" hinterlegte SQL in das WHERE-Statement mit aufgenommen. Es wird immer mit "<field> = '<auto-escaped Value>' " gesucht. Mehrere Filter-Felder werden mit AND verknüpft. Die übergebenen Werte werden automatisch escaped (Schutz vor SQL-Injection). Ist ein Wert null, so wird mit "...<field> IS NULL" im WHERE gesucht. Hiermit können einfache, SQL-Injection-sichere Filterkriterien realisiert werden. Für komplexere WHERE-Statements bitte [xwhere] benutzen! MySQL-wildcard-Filter "%" können hier aktuell leider nicht verwendet werden, da auch bei Text-Feldern mit "=" geprüft wird und nicht mit SQL LIKE.	['lastname'] ="e-matters"
[filter][<field>][search]	optional	String. Pro Field kann hier ein Suchbegriff angegeben werden, der Field-Typ-spezifisch (INT, FLOAT, TEXT, DATE, DATETIME) interpretiert wird. Wird diese Option genutzt kann natürlich nicht zuvor genannte [filter][<field>]-Abfrage für dieses Feld genutzt werden.	Text: "my_* \|\| ecms_* \|\| .class." Integer: ">10; <100" Float: Integer: ">0.5; <=9.999" Date: "1.12.2012 - 24.12.2012" DateTime: "> 15.12.2012 12:00"
[filter][<field>][in]	optional	Array. Pro Field kann hier eine Liste von Begriffen angegeben werden, nach denen als mögliche exakte Werte des entsprechenden Feldes gesucht werden soll. Wird diese Option genutzt kann natürlich nicht zuvor genannte [filter][<field>]-Abfrage für dieses Feld genutzt werden.	['lastname'] = array("e-matters","demo")
[filter][<field>][range]	optional	Array. Pro Field kann hier ein min-max Bereich angegeben werden, der Field-Typ-spezifisch (INT, FLOAT, TEXT, DATE) interpretiert wird. Es können hierbei wahlweise "min" und "max" oder auch nur einer der beiden Werte angegeben werden Wird diese Option genutzt kann natürlich nicht zuvor genannte [filter][<field>]-Abfrage für dieses Feld genutzt werden.	Text: array("min" => "A000100","max" => "A000200") Integer: array("min" => "100","max" => "200") Float: array("min" => "100,50","max" => "200.30") Date: array("min" => "24.12.2014","max" => "2014-12-31")
[sql][limit][max]	optional	Integer. Die maxinale Treffer-Anzahl aus der Ergebnis-Menge.	30 - Returned die maximal ersten 30 Zeilen. 100 - Returned die maximal ersten 100 Zeilen
[sql][limit][page]	optional	Integer. Die aktuelle Ergebnis-Seite aus einer durch "[sql][limit][max]" unterteilten Ergebnis-Menge. Der "page" Parameter beginnt mit "1". Der "[sql][limit][max]" Parameter kann ohne "page" Parameter verwendet werden.	1 - Returned die erste Seite des Abfrage-Ergebnisses. 3 - Returned die dritte Seite des Abfrage-Ergebnisses.
[sql][order]	optional	String. ORDER BY-Statement.	"firstname DESC"
[sql][group]	optional	String. GROUP BY-Statement.	"a_id"

Return - Array

Array-Key	Typ	Beschreibung
[status]	boolean	TRUE: Wenn die Datenabfrage durchgeführt werden konnte. FALSE: Wenn es bei der Ausführung einen Fehler gab.
[msg][<n>][type\|text]	string	Message-Stack Ein optionales Array, um Message-Strings zur Ausgabe in der GUI und Message-Codes zurückzugeben. Vor allem bei Ausführungsfehlern ( [status]=FALSE) sollte hier etwas zurückgegeben werden. Numerisches Array (mit n von 0 bis N). Es können prinzipiell beliebig viele Messages zurückgegeben werden. Pro Message können jeweils optional [type] und [text] zurückgegeben werden. [ type] ist typischerweise einer der folgenden Werte: "ERROR" - Schwerer Ausführungsfehler. "WARNING" - Warnung bei Ausführung. "INFO" - Zusätzliche (Debug) Meldungen. "OK" - Ausführung OK.
[data][<n>][<fields>]	mixed	Die eigentlichen Daten als 2-dimensionales Array. Die erste Array-Ebene ( <n>, von 0 bis N) nummeriert typischerweise die zurückgelieferten Datensätze durch. In der zweiten Array-Ebene befinden sich jeweils die Daten der angeforderten Datensätze in einem assoziativen Array.

Array-Key

Typ

Beschreibung

[status]

boolean

TRUE: Wenn die Datenabfrage durchgeführt werden konnte.

FALSE: Wenn es bei der Ausführung einen Fehler gab.

[msg][<n>][type|text]

string

Message-Stack

Ein optionales Array, um Message-Strings zur Ausgabe in der GUI und Message-Codes zurückzugeben. Vor allem bei Ausführungsfehlern ( [status]=FALSE) sollte hier etwas zurückgegeben werden.

Numerisches Array (mit n von 0 bis N). Es können prinzipiell beliebig viele Messages zurückgegeben werden.
Pro Message können jeweils optional [type] und [text] zurückgegeben werden.

[ type] ist typischerweise einer der folgenden Werte:

"ERROR" - Schwerer Ausführungsfehler.
"WARNING" - Warnung bei Ausführung.
"INFO" - Zusätzliche (Debug) Meldungen.
"OK" - Ausführung OK.

[data][<n>][<fields>]

mixed

Die eigentlichen Daten als 2-dimensionales Array.

Die erste Array-Ebene ( <n>, von 0 bis N) nummeriert typischerweise die zurückgelieferten Datensätze durch.
In der zweiten Array-Ebene befinden sich jeweils die Daten der angeforderten Datensätze in einem assoziativen Array.

Beispiele

Nachfolgend ein paar Beispiele zur Nutzung der API Ressource person_getList.

a) Liste aller Kunden in Kundengruppe

Es sollen alle Kunden der Kundengruppe "Shopkunden" gefunden werden.

/*
	 * Beispielaufruf des API-URL-Calls für die zu übergebenen Parameter
	 * - der Kundengruppenname muss im Filter übergeben werden
	 */
	<your_api_url>&resource=person_getList&params[filter][grp_name]='Shopkunden'

Das Result der Abfrage ist ein JSON String.

 
	/*
	 * Beispiel-JSON für das Result der Abfrage im Erfolgsfall
	 */
	{
	  "status" : true,
	  "msg" : null,
	  "data" : {
	     0 : {
	       "persid" : 23783, // autoincrement-key der Kundendaten
	       "personid" : "K0000138", // Kundennummer
	       "firstname" : "Emil", // Vorname des Kunden
	       "lastname" : "Matters", // Nachname des Kunden
	       {...} // alle weiteren Felder aus dem Daten-Typ "Kunde" (siehe oben)
	     },
	     1 : {
	       "persid" : 2378,
	       "personid" : "K0000138", 
	       "firstname" : "Emil",
	       "lastname" : "Matters",
	       {...} // alle weiteren Felder aus dem Daten-Typ "Kunde" (siehe oben)
	     },
	     <n> : {...} // weitere Ergebnis-Arrays je nach Result-Menge
	  }
	}

b) Liste aller Kunden mit Feldeinschränkung

Von allen Kunden soll die Kundennummer, E-Mail-Adresse zurückgeliefert werden.

 
	/*
	 * Beispielarray des API-URL-Calls für die zu übergebenen Parameter
	 */
	<your_api_url>&resource=person_getList&params[fields]=personid,email

Das Result der Abfrage ist eine Liste der abgefragten Bestellungen als Array.

 
	/*
	 * Beispiel-JSON für das Result der Abfrage im Erfolgsfall
	 */
	{
	  "status" : true,
	  "msg" : null,
	  "data" : {
	     0 : {
	       "personid" : "K0000138", // Kundennummer
	       "email" : "emil.matters@example.com", // E-Mail des Kunden
	     },
	     1 : {
	       "personid" : "K0000139",
	       "email" : "max.mustermann@example.com",
	     },
	     <n> : {...} // weitere Ergebnis-Arrays je nach Result-Menge
	  }
	}