HTTP(S) Connector | X4Documentation

Dieser Adapter kommuniziert mit Servern über das HyperText Transfer Protocol (HTTP) oder HTTP Secure (HTTPS) auf Basis des Apache HttpClient in Version 4. Der Adapter bietet die Standard-HTTP-Methoden GET, POST, PUT, DELETE, HEAD, OPTIONS, TRACE und PATCH. Zusätzlich können benutzerdefinierte HTTP-Methoden verwendet werden. Dabei unterstützt der Adapter HTTP-Basic-, Digest- und NTLMv2-Authentifizierung sowie Proxy-Server und präemptive Authentifizierung. Zudem unterstützt der Adapter auch Server Name Indication für HTTPS-Verbindungen sowie Client-Zertifikate zur Validierung von Requests.

Hinweis:

Im Standardmodus (Parameter fromXML deaktiviert) verarbeitet der Adapter je nach Operation ggf. ein beliebiges Input-Dokument mit unverändertem Content Type und Zeichenkodierung.
Im Expertenmodus (Parameter fromXML aktiviert) verarbeitet der Adapter ein spezifisches XML-Dokument, das Header, Cookie-Informationen etc. enthalten kann und mit dem sich die HTTP(S)-Operation detailliert steuern lässt, siehe Parameter fromXML und die Beschreibung der Input-Struktur.
Dieser Adapter löst den bestehenden Adapter HTTP(S) Communication ab.

Eigenschaften (Properties)

Operation

Bestimmt, welche Operation der Funktions-Adapter durchführt

Mögliche Werte:

Get: Daten von einer URL mit der GET-Methode anfordern
Post: Daten im Body des HTTP-Requests per POST an eine URL senden
Put: Daten im Body des HTTP-Requests über die PUT-Methode auf einer URL publizieren
Delete: die in der HTTP-Anfrage aufgerufene Ressource per DELETE-Methode löschen
Head: Nur die Header-Informationen per HEAD-Methode anfordern
Options: Vom Server per OPTIONS-Methode eine Liste der unterstützten HTTP-Methoden abrufen
Trace: Die vom Server empfangene Anfrage zurückgeben, um ggf. Änderungen von dazwischen liegenden Servern sichtbar zu machen
Patch: Die im Body des HTTP-Requests abgelegten Daten partiell aktualisieren
Execute: Daten im Body des HTTP-Request mit einer beliebigen HTTP-Methode senden, siehe auch Input-Beispiel

Parameter

Adapter	Hauptklasse des Adapters (nicht verändern!) Mögliche Werte: de.softproject.integration.adapter.http4.HttpClient4Adapter: Hauptklasse (Standard)
protocol	Verwendetes Protokoll (HTTP oder HTTPS) Mögliche Werte: `http`: HTTP (unverschlüsselt) verwenden (Standard) `https`: HTTPS (SSL-verschlüsselt) verwenden
host	IP-Adresse oder Host-Name des physikalischen Servers Hinweis: Der Parameter `host` fügt einen `HTTP-Header` namens `host` hinzu. Mögliche Werte: Beliebige gültige Zeichenkette ohne Protokollangabe (z. B. `google.com`)
vHost	Host-Name eines logischen Servers (virtual host), falls dieser durch die physikalische Angabe in Parameter host nicht eindeutig identifiziert werden kann Hinweis: Der Parameter `vHost` überschreibt den Wert für den `HTTP-Header` namens `host`, siehe Parameter `host`. Hier können die Ports angegeben werden, ausgenommen der Ports 80 (Standard für HTTP-Verbindungen) und 443 (Standard für HTTPS-Verbindungen). Mögliche Werte: Beliebige gültige Zeichenkette ohne Protokollangabe (z. B. `google.com`)
port	Portnummer des HTTP(S)-Dienstes Mögliche Werte: Beliebige ganze Zahl (z. B. `8080`) `-1`: Für HTTP-Verbindungen Port 80 verwenden; bei HTTPS-Verbindungen Port 443 verwenden (Standard)
path	Ordnerpfad auf dem Server, beginnend mit einem Schrägstrich Mögliche Werte: Beliebige Pfadangabe (z. B. `/intl/en_ALL/images/logo.gif`)
method	Name der HTTP-Methode, die bei der Operation `Execute` verwendet werden soll. Optional kann die Methode auch über den XML-Request gesetzt werden. Mögliche Werte: beliebige Zeichenkette
authenticationEncoding	Zeichenkodierung für die Anmeldedaten Mögliche Werte: Angabe einer Zeichenkodierung, z. B. `UTF-8` oder `ISO-8859-1` Mithilfe dieses Parameters können auch Umlaute in den Anmeldedaten verwendet werden.
query	Argument(e) für die HTTP(S)-Anfrage Mögliche Werte: Beliebige URL-kodierte Argumente ohne führendes Fragezeichen (z. B. `Arg1=V1&Arg2=V2`)
username	Benutzername für eine Basic-, Digest- oder NTLM-Authentifizierung Mögliche Werte: Bei HTTP-Basic-Authentifizierung: der Benutzername Bei HTTP-Basic-Authentifizierung an einer Windows-Domäne: Zeichenkette nach dem Muster `<Domäne>\<Benutzername>` (z. B. `MyDomain\MyUserName`) Bei NTLM-Authentifizierung an einer Windows-Domäne: nur der Benutzername (und in Parameter ntlmDomain die Domäne angeben) (z. B. `MyUsername`)
password	Passwort für eine Basic-, Digest- oder NTLM-Authentifizierung Mögliche Werte: Beliebige Zeichenkette
token	Token für Bearer-Authentifizierung Es ist auch möglich, den Token in die Input-XML-Datei einzutragen.
ntlmWorkstation	Workstation (Computer-Name) des Clients (nur für NTLM-Authentifizierung, siehe Parameter `allowNtlm`) Mögliche Werte: Beliebiger gültiger Workstation-Name
ntlmDomain	Name der Domäne (nur für NTLM-Authentifizierung, siehe Parameter `allowNtlm`) Mögliche Werte: Beliebiger gültiger Domäne-Name (NetBIOS Name)
usePreemptiveBasicAuth	Präemptive Authentifizierung (mit den Zugangsdaten aus Parameter username und password) für HTTP(S)-Aufrufe aktivieren (nur für Basic-Authentifizierung, siehe Parameter allowBasic) Mögliche Werte: `True`: Zugangsdaten direkt (präemptiv) bei jedem HTTP(S)-Aufruf mitschicken `False`: Keine präemptive Authentifizierung (Standard)
allowBasic	HTTP(S)-Basic-Authentifizierung verwenden Mögliche Werte: `True`: Basic-Authentifizierung verwenden `False`: Keine Basic-Authentifizierung verwenden (Standard)
allowDigest	Digest-Authentifizierung verwenden Mögliche Werte: `True`: Per Digest authentifizieren `False`: Nicht per Digest authentifizieren (Standard)
allowNtlm	Proprietäre NTLM-Server-Authentifizierung von Microsoft verwenden Mögliche Werte: `True`: Per NTLM authentifizieren `False`: Nicht per NTLM authentifizieren (Standard)
fromXml	Expertenmodus aktivieren. Der Adapter erwartet ein spezifisches XML-Dokument inklusive Headern, Cookie-Informationen etc., mit dem sich die HTTP(S)-Operation detailliert steuern lässt. Hinweis: Im Expertenmodus kann der HTTP-Header `host` ausschließlich über den Parameter `host` gesetzt werden (nicht im XML-Dokument). Alternativ kann der Parameter `host` durch den Parameter `vHost` überschrieben werden, siehe die Parameter `host` bzw. `vHost`. Mögliche Werte: `True`: Expertenmodus aktivieren (Adapter erwartet ein spezifisches Input-XML-Dokument) `False`: Adapter-Input direkt verarbeiten
toXml	Alle Header als Elemente und den Inhalt des Bodys als Base64-kodierten Text in einem XML-Dokument ausgeben Mögliche Werte: `True`: XML-Dokument ausgeben `False`: Server-Antwort unverändert ausgeben (Standard)
hideCookieHeader	Im Ergebnis-XML-Dokument auch die Header-Elemente mit Cookie-Informationen ausgeben (wenn Parameter `toXml` aktiviert ist); Nur zu Entwicklungs- und Testzwecken deaktivieren oder bei Cookies, die vom Standard abweichen Mögliche Werte: `True`: Keine Cookie-Informationen als Header im Ergebnis-XML-Dokument (Standard) `False`: Cookie-Informationen als Header im Ergebnis-XML-Dokument ausgeben
useProxy	Proxy-Server für den Verbindungsaufbau verwenden Mögliche Werte: `True`: Verbindung über den in Parameter proxyHost angegeben Proxy-Server aufbauen `False`: Kein Proxy-Server (Standard)
proxyHost	IP-Adresse oder Host-Name eines Proxy-Servers Mögliche Werte: Beliebige gültige Zeichenkette (z. B. `192.168.1.1`)
proxyPort	Portnummer des Proxy-Servers Mögliche Werte: Beliebige ganze Zahl -`1`: Standard-Port verwenden (Standard)
proxyUsername	Benutzername für eine Basic-, Digest- oder NTLM-Authentifizierung am Proxy-Server Mögliche Werte: Bei HTTP-Basic-Authentifizierung: der Benutzername Bei HTTP-Basic-Authentifizierung an einer Windows-Domäne: Zeichenkette nach dem Muster `<Domäne>\<Benutzername>` (z. B. `MyDomain\MyUserName`) Bei NTLM-Authentifizierung an einer Windows-Domäne: nur der Benutzername (und in Parameter `ntlmDomain` die Domäne angeben) (z. B. `MyUsername`)
proxyPassword	Passwort für den Proxy-Server Mögliche Werte: Beliebige Zeichenkette
proxyNtlmWorkstation	Workstation (Computer-Name), von der die Authentifizierungsanfrage ausgeht (für eine NTLM-Authentifizierung via NTLM-Proxy) Mögliche Werte: Beliebiger Workstation-Name
proxyNtlmDomain	Windows-Domäne für eine NTLM-Authentifizierung via NTLM-Proxy Mögliche Werte: Beliebiger Domänenname
proxyUsePreemptiveBasicAuth	Präemptive Authentifizierung (mit den Zugangsdaten aus Parameter `proxyUsername` und `proxyPassword)` für den Proxy-Server aktivieren (nur für Basic-Authentifizierung, siehe Parameter `proxyAllowBasic)` Mögliche Werte: `True`: Zugangsdaten direkt (präemptiv) bei jedem Proxy-Aufruf mitschicken `False`: Keine präemptive Authentifizierung (Standard)
proxyAllowBasic	Basic-Authentifizierung für den Proxy verwenden Mögliche Werte: `True`: Basic-Authentifizierung für den Proxy verwenden `False`: Keine Basic-Authentifizierung für den Proxy verwenden (Standard)
proxyAllowDigest	Digest-Authentifizierung für den Proxy verwenden Mögliche Werte: `True`: Am Proxy per Digest authentifizieren `False`: Nicht per Digest am Proxy authentifizieren (Standard)
proxyAllowNtlm	Proprietäre NTLM-Server-Authentifizierung von Microsoft für den Proxy verwenden Mögliche Werte: `True`: Am Proxy per NTLM authentifizieren `False`: Nicht per NTLM am Proxy authentifizieren (Standard)
connectTimeout	Timeout-Wert für den Verbindungsaufbau in Millisekunden Mögliche Werte: `>0`: Timeout-Wert in Millisekunden `<=0`: Kein Timeout (Standard)
socketTimeout	Timeout-Wert zwischen zwei eingehenden Datenpaketen in Millisekunden; Dieser sagt nichts über die Gesamt-Anfragezeit aus. Mögliche Werte: `>0`: Timeout-Wert in Millisekunden `<=0`: Kein Timeout (Standard)
redirectsEnabled	URL-Weiterleitungen bei einer Server-Antwort mit HTTP-Status `301 Moved Permanently` zulassen Mögliche Werte: `True`: URL-Redirects ausführen (Standard) `False`: Keine URL-Redirects ausführen
circularRedirectsEnabled	Zirkuläre Weiterleitungen bei einer Server-Antwort mit HTTP-Status `301 Moved Permanently` zulassen Mögliche Werte: `True`: Zirkuläre Weiterleitungen ausführen (Standard) `False`: Keine zirkulären Weiterleitungen ausführen
maxRedirects	Maximale Anzahl der möglichen URL-Weiterleitungen bei einer Server-Antwort mit HTTP-Status `301 Moved Permanently` Mögliche Werte: Beliebige ganze Zahl `-1`: Keine Beschränkung (Standard)
acceptAllCertificates	Zertifikatsprüfung abschalten Mögliche Werte: `beliebiger String`: Zertifikate werden auf Vertrauen geprüft (Standard) `Yes, I want to disable security by accepting untrusted certificates.`: Zertifikatsprüfung wird abgeschaltet Bitte beachten: Hier muss die genaue Zeichenfolge eingegeben werden!
acceptAllSslHostnames	Hostname-Überprüfung für Zertifikate abschalten Mögliche Werte: `beliebiger String`: Hostname muss zum Zertifikat passen (Standard) `Yes, I want to disable security by accepting non-matching hostnames.`: Hostname-Überprüfung wird abgeschaltet Bitte beachten: Hier muss die genaue Zeichenfolge eingegeben werden!
useClientCertificate	Client-Zertifikate zur Validierung des Requests verwenden Mögliche Werte: `True`: Client-Zertifikate zur Validierung des Requests verwenden `False`: Kein Client-Zertifikat zur Validierung des Requests verwenden (Standard)
keystoreType	Keystore-Typ für die Speicherung von Client-Zertifikaten (gemäß http://docs.oracle.com/javase/6/docs/technotes/guides/security/StandardNames.html#KeyStore) Mögliche Werte: `jceks`: Proprietäre Keystore-Implementierung von SunJCE verwenden `jks`: Proprietäre Keystore-Implementierung von SUN verwenden `pkcs12`: Keystore-Transferformat PKCS12 verwenden
keystoreURL	URL zum Keystore für die Validierung des Requests über Client-Zertifikate Mögliche Werte: Beliebige gültige URL, z.B. `file:/C:/Folder/ExampleKeystore`
keystorePassword	Passwort für den Keystore zur Validierung des Requests über Client-Zertifikate Mögliche Werte: Beliebige gültige Zeichenkette
keyAlias	Schlüssel-Alias zur Zugriff auf einen bestimmten Schlüssel innerhalb des Keystores Mögliche Werte: Beliebige gültige Zeichenkette
aliasPassword	Zugehöriges Passwort für einen bestimmten Schlüssel innerhalb des Keystores Mögliche Werte: Beliebige gültige Zeichenkette

Statuswerte

-1	Technischer Fehler: Server antwortet nicht, oder das Adapter-Input-XML kann nicht verarbeitet werden (nur wenn der Expertenmodus über Parameter fromXml aktiviert ist)
>=100	Dreistelliger HTTP-Statuscode je nach Ergebnis des Aufrufs, siehe http://tools.ietf.org/html/rfc2616#section-6.1.1

Input (Standardmodus)

Im Standardmodus (Parameter fromXML deaktiviert) verarbeitet der Adapter je nach Operation ggf. ein beliebiges Input-Dokument mit unverändertem Content Type und Zeichenkodierung; siehe (7.4.3-de) Document Properties Changer.

Input (Expertenmodus)

Im Expertenmodus (Parameter fromXML aktiviert) verarbeitet der Adapter ein spezifisches XML-Dokument, das Header, Cookie-Informationen etc. enthalten kann und mit dem sich die HTTP(S)-Operation detailliert steuern lässt.

Diese XML-Struktur entspricht im Wesentlichen sowohl der XML-Struktur, die der Adapter ausgibt, wenn Parameter toXml aktiviert ist, als auch der X4 ReST-Schnittstelle (wenn für die jeweilige URI-Operation in der Konfigurationsdatei <X4>/X4DB/0/restconfig.xml in Attribut isDirect="false" definiert wurde). Einziger Unterschied zum Ergebnis-XML-Dokument von X4 ReST ist, dass dieses den Base64-kodierten Body in einem Element <Content> (statt <Body> beim Adapter) bereitstellt.

In Element <Cookies> sind ggf. zudem Cookie-Informationen in jeweils einem Element <Cookie> enthalten:

<Request>
   <Headers>
      <Header>
         <Name><!--HTTP-Header-Name--></Name>
         <Value><!--Header-Wert--></Value>
      </Header>
      <!-- Oder bei Datumswerten: -->
      <Header>
         <Name><!--HTTP-Header-Name--></Name>
         <Date timezone="Zeitzone"><!--Header-Datumswert--></Date>
      </Header>
   </Headers>
   <Cookies>
      <Cookie expires="Verfallsdatum" path="Pfad" domain="Domäne">
         <Version><!--Versionsnummer--></Version>
         <Secure/>       <!-- Wenn Secure-Attribut gesetzt -->
         <Persistent />  <!-- Bei einem persistenten Cookie -->
         <Domain><!--Domäne--></Domain>
         <Path><!--Pfad--></Path>
         <Name><!--Cookie-Name--></Name>
         <Value><!--Cookie-Wert--></Value>
         <ExpiryDate><!--Verfallsdatum im Format YYYY-MM-DD hh:mm:ss--></ExpiryDate>
      </Cookie>
   </Cookies>
   <Body><!--Base64-kodierte Daten der HTTP-Anfrage--></Body>
</Request>

Operation Execute

Bei der Operation Execute in Verbindung mit dem aktiviertem Parameter fromXML kann die HTTP-Methode auch im Input-XML wie folgt gesetzt werden:

XML

 <Request method="CUSTOM_METHOD">
   <Headers>
      <!-- ... -->
   </Headers>
   <Cookies>
      <!-- ... -->
   </Cookies>
   <Body><!--Base64-kodierte Daten der HTTP-Anfrage--></Body>
</Request>

Output

Standardmäßig (wenn Parameter toXml deaktiviert ist) wird das Ergebnisdokument des HTTP(S)-Aufrufs ausgegeben.

Wenn Parameter toXml aktiviert ist, wird ein XML-Dokument ausgegeben, das alle HTTP-Header der Antwort jeweils in einem Element <Header> enthält. Falls ein Header-Wert mehrere Werte enthält, die durch Kommas getrennt sind, so werden diese Teilwerte zusätzlich in jeweils einem Element <Element> in den Kindelementen <Name> und <Value> angegeben.

Der Inhalt des Bodys ist als Base64-kodierte Zeichenkette in Element <Body> enthalten. Wenn Parameter hideCookieHeader deaktiviert wurde, wird zusätzlich jeder Header ausgegeben, der zum Cookie geführt hat.

<Response>
   <Request line="HTTP-Anfragezeile">
      <Method><!--HTTP-Methode--></Method>
      <URI><!--Pfad auf dem Server--></URI>
      <Protocol>HTTP/1.1</Protocol>
   </Request>
   <Status line="HTTP-Statuszeile">
      <Code><!--Dreistelliger Statuscode--></Code>
      <Reason><!--Statusname--></Reason>
      <Protocol><!--HTTP/1.1</Protocol>
   </Status>
   <Headers>
      <Header>
         <Name><!--HTTP-Header-Name--></Name>
         <Value><!--Header-Wert--></Value>
      </Header>
      <!-- Oder bei Datumswerten: -->
      <Header>
         <Name><!--HTTP-Header-Name--></Name>
         <Date timezone="Zeitzone"><!--Header-Datumswert--></Date>
      </Header>
   </Headers>
   <Cookies>
      <Cookie expires="Verfallsdatum" path="Pfad" domain="Domäne">
         <Version><!--Versionsnummer--></Version>
         <Secure/>       <!-- Wenn Secure-Attribut gesetzt -->
         <Persistent />  <!-- Bei einem persistenten Cookie -->
         <Domain><!--Domäne--></Domain>
         <Path><!--Pfad</Path>
         <Name><!--Cookie-Name--></Name>
         <Value><!--Cookie-Wert--></Value>
         <ExpiryDate><!--Verfallsdatum im Format YYYY-MM-DD hh:mm:ss--></ExpiryDate>
      </Cookie>
   </Cookies>
   <Body><!--Base64-kodierte Daten im Body der Antwort--></Body>
</Response>