EloquaJdbc Treiber
Einleitung
Der EloquaJdbc Treiber erlaubt es Objekte aus Eloqua über jdbc zu lesen.
Mit Hilfe von SQL-Abfragen können damit Daten von einem Eloqua Objekt genauso wie aus einer Datenbanktabelle extrahiert und weiterverarbeitet werden.
Da in Eloqua nicht alle Objekte über eine API gelesen werden können, muss der Anwender die verschiedenen Möglichkeiten der APIs verstehen. Zur Unterstützung des Anwenders stellt der Treiber die Metadaten der Eloqua Objekte zur Verfügung, sodass pro API mitgeteilt wird, welche Objekte jeweils zur Verfügung stehen.
Hier ein Überblick über die "Datanbankobjekte" des Treibers:
- Schema: Entweder die API wie rest, odata und bulk oder system für die Metadatentabellen
- Tabelle: Bei Schema system der Name einer Systemtabelle. Ansonsten ein Objekt aus der mit dem Schema bezeichneten Eloqua API
- Spalten: Die jeweiligen Spalten des Objekts beziehungsweise der Systemtabellen
- Identifier: Identifier wie Schemanamen, Tabellennamen oder Spaltennamen sind nicht case sensitiv in Eloqua. Identifier sollten deshalb nicht in doppelten Anführungszeichen angegeben werden.
Mit der nachfolgenden Query kann man zum Beispiel mit Hilfe des Treibers alle Datensätze des Objekts emailgroup über die odata Schnittstelle lesen:
SELECT email_group_id
, email_group
, email_group_description
, is_deleted
, last_modified_date
FROM odata.emailgroup
SQL Syntax
Abweichend zu der unter SQL-Parser vorgestellten SQL Syntax gibt es folgende Abweichung / Ergänzungen:
- Die FILES() Funktionalität wird nicht unterstützt. Somit auch nicht die Pseudospalten DIRECTORY und FILENAME.
- Die angegebenen Keywörter COLUMNS, HEADLINE, SEPARATED BY, QUOTED BY und ENCODING werden nicht unterstützt.
- Das FILTER Keywort wird unterstützt. Hierbei unterscheidet sich jedoch pro API, welche Syntax zu verwenden ist. Gibt man einen Filter an, erfolgt die Selektion bei Eloqua. Bei einer WHERE-Bedingung werden alle Daten geladen und dann im JDBC-Treiber gefiltert (Performance).
- Das ORDERBY Keywort wird nur in der ODATA Api unterstützt.
Systemtabellen
Der Treiber unterstützt Systemtabellen. Diese erlauben Metadaten über Eloqua Objekte, Spalten und Primärschlüssel zu laden. Die Systemtabellen liegen immer unter dem Schema system.
Die Metadaten der Systemtabellen selbst werden nicht bei den Abfragen der Systemtabellen oder der jdbc Metadatenmethoden getTables, getColumns und getPrimaryKeys zurückgeliefert.
Spaltenwerte für Katalog-, Schema-, Tabellen-, Spaltenbezeichner, usw. sind immer in Kleinbuchstaben.
Es gibt die folgenden Systemtabellen:
| Schema | Tabellenname | Beschreibung |
|---|---|---|
| system | table_list | Eine Liste aller Objekte in Eloqua |
| system | column_list | Eine Liste aller Spalten von allen Objekten in Eloqua |
| system | primary_key_list | Eine Liste aller Primärschlüsselspalten von allen Objekten in Eloqua |
Systmtabelle für die Liste der Tabellen
Hier werden die Metadaten aller verfügbaren Objekte in Eloqua zur Verfügung gestellt.
??? Die Menge der sichtbaren Objekte hängt von den Berechtigungen ab, die der technische User besitzt, mit dem die Verbindung aufgebaut wird. Dieses gilt auch für alle anderen Systemtabellen.
Die folgenden Metaddatenspalten stehen für die Selektion zur Verfügung:
| Name | Datentyp | Wert | Bemerkung |
|---|---|---|---|
| table_cat | VARCHAR(100) | datasqill | Der Katalog des Objekts ist immer datasqill |
| table_schem | VARCHAR(100) | Das Schema des Objekts ist abhängig von der API die das Objekt bereitstellt | |
| table_name | VARCHAR(100) | Objektname | Name des Objects |
| table_type | VARCHAR(100) | TABLE | Hat immer den Wert TABLE |
| remarks | VARCHAR(4000) | Beschreibung | Eine Beschreibung des Objekts |
| type_cat | VARCHAR(100) | NULL | Nicht unterstützt. Immer NULL |
| type_schem | VARCHAR(100) | NULL | Nicht unterstützt. Immer NULL |
| type_name | VARCHAR(100) | NULL | Nicht unterstützt. Immer NULL |
| self_referencing_col_name | VARCHAR(100) | NULL | Nicht unterstützt. Immer NULL |
| ref_generation | VARCHAR(20) | NULL | Nicht unterstützt. Immer NULL |
Der gleiche ResultSet wird geliefert, falls man über das jdbc Interface java.sql.DatabaseMetaData getTables aufruft.
Systmtabelle für die Liste der Spalten
Hier werden die Metadaten aller Spalten von allen verfügbaren Objekten in Eloqua zur Verfügung gestellt.
Die folgenden Metaddatenspalten stehen für die Selektion zur Verfügung:
| Name | Datentyp | Wert | Bemerkung |
|---|---|---|---|
| table_cat | VARCHAR(100) | datasqill | Der Katalog des Objekts ist immer datasqill |
| table_schem | VARCHAR(100) | Das Schema des Objekts ist abhängig von der API die das Objekt bereitstellt | |
| table_name | VARCHAR(100) | Objektname | Name des Objects |
| column_name | VARCHAR(100) | Spaltenname | Name der Spalte |
| data_type | Ganzzahlig | JDBC-Datentyp | Der jdbc-Datentyp (siehe java.sql.JDBCType) |
| type_name | VARCHAR(100) | Datentyp | Der Name des Datentypen (siehe unten) |
| column_size | Ganzzahlig | Länge | Die Länge der Spalte |
| buffer_length | Ganzzahlig | 0 | Wird von jdbc nicht mehr unterstützt. Immer 0 |
| decimal_digits | Ganzzahlig | Anzahl Nachkommastellen | Nur bei Datentypen mit Nachkommastellen. Sonst NULL |
| num_prec_radix | Ganzzahlig | 10 | Steht immer auf 10 |
| nullable | Ganzzahlig | 2 | Steht für unbekannt (columnNullableUnknown) |
| remarks | VARCHAR(4000) | Kommentar | Spaltenkommentar |
| column_def | VARCHAR(4000) | NULL | Default Wert (nicht unterstützt) |
| sql_data_type | Ganzzahlig | NULL | nicht unterstützt |
| sql_datetime_sub | Ganzzahlig | NULL | nicht unterstützt |
| char_octet_length | Ganzzahlig | NULL | nicht unterstützt |
| ordinal_position | Ganzzahlig | Position | Spaltennummer startend mit 1 |
| is_nullable | VARCHAR(18) | leerer String | nicht unterstützt |
| scope_schema | VARCHAR(100) | leerer String | nicht unterstützt |
| scope_table | VARCHAR(100) | leerer String | nicht unterstützt |
| source_data_type | Ganzzahlig | NULL | nicht unterstützt |
| is_autoincrement | VARCHAR(10) | leerer String | nicht unterstützt |
| is_generatedcolumn | VARCHAR(10) | leerer String | nicht unterstützt |
Verwendete Datentypen:
| Name | Länge | Bemerkung |
|---|---|---|
| BIGINT | 0 | Ganzzahlig. Kann auch als Integer Datentyp verwendet werden |
| BOOLEAN | 0 | Boolscher Wert true / false |
| DATE | 0 | Datum |
| DECIMAL | wie angegeben | Zahl mit Vor und Nachkommastellen. Die Anzahl der Nachkommastellen steht in decimal_digits |
| TIMESTAMP | 0 | Zeitstempel. Der Zeitstempel ist immer in der lokale Zeitzone |
| VARCHAR | wie angegeben | Zeichenkette |
Der gleiche ResultSet wird geliefert, falls man über das jdbc Interface java.sql.DatabaseMetaData getColumns aufruft.
Systmtabelle für die Liste der Primärschlüssel
Hier werden die Metadaten aller Primärschlüsselspalten aller Objekte in Eloqua zur Verfügung gestellt.
Die folgenden Metaddatenspalten stehen für die Selektion zur Verfügung:
| Name | Datentyp | Wert | Bemerkung |
|---|---|---|---|
| table_cat | VARCHAR(100) | datasqill | Der Katalog des Objekts ist immer datasqill |
| table_schem | VARCHAR(100) | Das Schema des Objekts ist abhängig von der API die das Objekt bereitstellt | |
| table_name | VARCHAR(100) | Objektname | Name des Objects |
| column_name | VARCHAR(100) | Spaltenname | Name der Spalte des Primärschlüssels |
| key_seq | Ganzzahlig | Position | Position im Primärschlüssel startend mit 1 |
| pk_name | VARCHAR(100) | = pk_$table_name | Name des Primärschlüssels. Automisch generiert |
Der gleiche ResultSet wird geliefert, falls man über das jdbc Interface java.sql.DatabaseMetaData getPrimaryKeys aufruft.
Die APIs von Eloqua
Die APIs sind in allen Aspekten sehr unterschiedlich. Metadaten werden unterschiedlich abgefragt, Filter sind unterschiedlich implementiert, die Datenmengen sind bei der rest API stark eingeschränkt und die Prozessabläufe sind komplett verschieden.
Dieser JDBC Treiber übernimmt die Aufgabe diese unterschiedlichen Zugriffswege auf eine einheitliche Schnittstelle zu reduzieren.
Rest API
Die rest API stellt nur wenige Objekte zur Verfügung. https://docs.oracle.com/en/cloud/saas/marketing/eloqua-develop/Developers/RESTAPI/Tutorials/search_parameter.htm?cshid=SearchParam
Filter und Orderby
Die Rest API unterstützt sowohl das FILTER als auch das ORDERBY Keyword.
Da die Schnittstelle keine Leerzeichen außerhalb von Anführungsstrichen zulässt, werden diese vor der Übertragung beim FILTER und ORDERBY gelöscht.
Das FILTER Keyword liefert den angegebenen Text als URL parameter search an die API. Es ist zu beachten, dass:
- AND oder OR darf nicht angegeben werden kann
- Wenn die Bedingung die gleiche Spalte mehrfach auf Gleichheit prüft, ist es eine ODER-Bedingung für diese Spalte
- Alle Bedingungen mit unterschiedlichen Spalten werden mit UND verknüpft
Das ORDERBY Keyword kann verwendet werden. Es liefert den angegeben Text als URL Paramter orderBy an die API.
Beispiel:
SELECT type
, id
, email_Header_Id
FROM rest.emails
FILTER id<=200
ENDFILTER
ORDERBY id
#### Depth
Der jdbc Treiber erkannt anhand der verwendeten Spalten welche Tiefe bei der Selektion verwendet werden muss.
Es wird ermittelt, welche Tiefe bei der Selektion notwenig ist.
Entsprechnd wird dann das URL Parameter depth auf minimal, partial oder complete gesetzt.
### Bulk API
In der **bulk** API werden sowohl benutzerdefinierte Objekte, als auch Systemobjekte angeboten.
Es ist möglich die Daten zu filtern (Unter Verwendung des FILTER Statements).
Hierbei wird die Eloqua Expression Language verwendet.
Siehe hierzu [Eloqua Expression Language](https://docs.oracle.com/en/cloud/saas/marketing/eloqua-develop/Developers/BulkAPI/Reference/BulkLanguages/eloqua-expression-language.htm).
**Achtung:** Die bulk API hat eine Begrenzung auf 250 Spalten pro SELECT.
### Odata API
Die Filterbedingungen der **odata** API verwenden eine andere Syntax, als die Filter in der **bulk** API.
Sie werden gemäß der Odata Spezfikation angegeben. Unter [Odata Grammer](https://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/abnf/odata-abnf-construction-rules.txt) findet man den Einstieg zur Grammatik für den Filter, wenn man die Definition von *boolCommonExpr* sucht.
Einfacher ist vielleicht das Verständnis, wenn man sich z.B. die Dokumentation von Microsoft [Filter in odata](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/use-filter-expressions-in-odata-uris) ansieht.
Grundsätzlich verwendet man keine =, !=, >, usw. Operatoren, sondern *eq*, *ne*, *gt*, usw.
Das ORDERBY Keyword kann verwendet werden. Es liefert den angegeben Text per $orderby Paramter an die API.
Beispiel:
```sql
SELECT *
FROM odata.user
FILTER user_email_address ne null
ENDFILTER
ORDERBY user_name