REQUEST
DOCUMENT FROM
url
|
|||
|
|
WITH
[with-clause] |
|
|
|
|
RETURN
[return-clause] |
|
|
RESPONSE
http-response-code
|
|||
[GIVING
natural-error-number] |
|||
Dieser Abschnitt behandelt folgende Themen:
Eine Erläuterung der in dem Syntax-Diagramm verwendeten Symbole entnehmen Sie dem Abschnitt Syntax-Symbole.
Verwandtes Statement: PARSE JSON
und PARSE XML
Gehört zur Funktionsgruppe: Internet und XML
Mit dem Statement REQUEST DOCUMENT haben Sie die Möglichkeit, im Internet
Dokumente abzurufen und hoch zu laden. Siehe auch Statements für Internet-Zugang und Parsing im
Leitfaden zur Programmierung.
Informationen zur Unicode-Unterstützung siehe Unicode- und Codepage-Unterstützung in der Natural-Programmiersprache, Abschnitt Natural-Statements, Unterabschnitt REQUEST DOCUMENT in der Unicode- und Codepage-Unterstützung-Dokumentation.
Aus technischen Gründen wird das HTTPS-Protokoll nur unter z/OS unterstützt.
Cookies werden nicht unterstützt. Sie werden ignoriert.
Operanden-Definitionstabelle:
| Operand | Mögliche Struktur | Mögliche Formate | Referenzierung erlaubt | Dynam. Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
url
|
C | S | A | ja | nein | ||||||||||||||
http-response-code |
S | I4 | ja | ja | |||||||||||||||
natural-error-number |
S | I4 | ja | nein | |||||||||||||||
Syntax-Element-Beschreibung:
| Syntax-Element | Beschreibung | |
|---|---|---|
url
|
Adresse des Dokuments:
Falls Es ist nicht möglich, eine Internet Protocol Version 4 (IPv6)-Adresse in eine IPv6-Adresse einzubetten. |
|
with-clause |
WITH-Klausel:
Siehe |
|
return-clause |
RETURN-Klausel:
Siehe |
|
http-response-code |
RESPONSE:
Siehe auch HTTP/HTTPS Status Codes weitergeleitet und verweigert. Eine Liste der möglichen HTTP/HTTPS Status Codes finden Sie unter dem RFC 2616 Memorandum, das vom World Wide Web Consortium (W3C) publiziert wird. |
|
natural-error-number |
GIVING-Option: natural-error-number
enthält die vierstellige Natural-Fehlernummer, wenn die Anfrage nicht ausgeführt
werden konnte.
|
|
[USER
user-id]
|
[PASSWORD
user-password]
|
[HEADER {[NAME] header-name-out [VALUE] header-value-out} ...]
|
[DATA {ALL
outbound-document [ENCODED [[IN] CODEPAGE
code-page-out]]
|
|{[NAME] variable-name-out [VALUE] variable-value-out} ...}]
|
Sie können die with-clause benutzen, um
optional Benutzer/Passwort, Header und Einzelheiten zu den Daten für die Anfrage
anzugeben.
Eine leere with-clause wird ignoriert (d.h.,
wenn nach WITH kein Wert angegeben wird).
Operanden-Definitionstabelle:
| Operand | Mögliche Struktur | Mögliche Formate | Referenzierung erlaubt | Dynam. Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
user-id
|
C | S | A | ja | nein | ||||||||||||||
user-password
|
C | S | A | ja | nein | ||||||||||||||
header-name-out
|
C | S | A | ja | nein | ||||||||||||||
header-value-out
|
C | S | A | N | P | I | F | D | T | L | ja | nein | |||||||
outbound-document
|
C | S | A | U | N | P | I | F | B | D | T | L | ja | nein | |||||
code-page-out
|
C | S | A | ja | nein | ||||||||||||||
variable-name-out
|
C | S | A | ja | nein | ||||||||||||||
variable-value-out
|
C | S | A | N | P | I | F | D | T | L | ja | nein | |||||||
Syntax-Element-Beschreibung:
| Syntax-Element | Beschreibung | |
|---|---|---|
user-id
|
Benutzerkennung:
|
|
user-password
|
Benutzer-Passwort:
|
|
header-name-out
|
HEADER NAME/VALUE-Option:
header-name-out:
Header-Namen dürfen keinen header-value-out:
Header-Werte dürfen nicht Siehe auch Automatisch erzeugte Headers. |
|
outbound-document
|
DATA ALL-Option:
|
|
code-page-out |
DATA ALL ENCODED-Option: Bei der
Datenübertragung mit dem REQUEST DOCUMENT-Statement erfolgt
normalerweise keine Codepage-Konvertierung. Wenn Sie ausgehende Daten in einer
bestimmten Codepage kodieren möchten, müssen Sie die
CODEPAGE-Option benutzen:
Kodierung und Charset-Attribute
Falls das Beispiel: Wenn ein ausgehendes XML-Dokument die Attribut-Kodierung
|
|
variable-name-out
|
DATA NAME/VALUE-Option:
Einschränkung:
Wenn Während der Anfrage werden
|
|
[HEADER [ALL
header-all-in] [[NAME] header-name-in [VALUE] header-value-in ...]]
|
[PAGE
inbound-document [ENCODED [[FOR
TYPES
mime-type
...] [IN] CODEPAGE
code-page-in]]]
|
Operanden-Definitionstabelle:
| Operand | Mögliche Struktur | Mögliche Formate | Referenzierung erlaubt | Dynam. Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
header-all-in
|
S | A | ja | ja | |||||||||||||||
header-name-in
|
C | S | A | ja | nein | ||||||||||||||
header-value-in
|
S | A * | A | N | P | I | F | B | D | T | L | ja | ja | ||||||
inbound-document
|
S | A | U | B | ja | ja | |||||||||||||
mime-type
|
C | S | A | ja | nein | ||||||||||||||
code-page-in |
C | S | A | ja | nein | ||||||||||||||
Mit der return-clause können Sie die
Return-Informationen für die Headers und/oder das Dokument angeben.
Syntax-Element-Beschreibung:
| Syntax-Element | Beschreibung | |
|---|---|---|
header-all-in |
HEADER ALL-Option:
Die erste Zeile enthält die Status-Informationen, und alle folgenden Zeilen
enthalten die Headers als Paare mit Namen und Werten. Die Namen enden immer
auf einen Doppelpunkt (:), und die Werte enden mit einem Zeilenvorschub
( |
|
header-name-in
|
HEADER NAME/VALUE-Option:
|
|
inbound-document |
PAGE ALL-Option:
|
|
code-page-in |
ENCODED-Option:
Bei der Datenübertragung mit dem Falls nötig, wird das
Wenn der Wert von Anmerkung Beispiele für die Verwendung der Klausel |
|
mime-type |
FOR TYPES-Option:
Die als Antwort auf eine HTTP/HTTPS-Anfrage eintreffenden Daten können
Binärdaten enthalten (z.B. Bilddaten/gif) oder Zeichendaten (z.B. Text/html).
Zusammen mit der Antwort erhält das Falls der zurückgegebene MIME-Typ eine Kodierung enthält, wird das
Falls der zurückgegebene MIME-Typ keine Kodierung enthält, dann wird
das Falls der zurückgegebene MIME-Typ keine Kodierung enthält, dann
erfolgt eine zusätzliche Prüfung, ob der zurückgegebene MIME-Typ mit einem der
in |
|
Für eine HTTP-Anfrage werden einige Headers benötigt, z.B. REQUEST-METHOD
oder Content Type. Diese Headers werden in Abhängigkeit von den Parametern, die mit dem
REQUEST DOCUMENT-Statement mitgegeben werden, automatisch erzeugt.
Anmerkung
Es ist möglich, die automatisch erzeugten Headers zu überschreiben. Natural prüft
diese jedoch nicht auf Fehler. Es können unerwartete Fehler auftreten.
Das REQUEST DOCUMENT-Statement unterstützt folgende
REQUEST-METHODs: HEAD, POST, GET
und PUT.
Die folgende Tabelle zeigt die HTTP REQUEST-METHOD, die in Abhängigkeit
von den gegebenen Operanden erzeugt wird:
WITH HEADER |
WITH DATA |
RETURN HEADER |
RETURN PAGE |
|
| HEAD | o | - | x | - |
|---|---|---|---|---|
| POST | o | x | o | x |
| GET | o | - | o | x |
| PUT | o | DATA ALL
* |
o | o |
Zusätzlich zu den oben aufgeführten Standard-REQUEST-METHODs können in
einem REQUEST-METHOD Header die Methoden DELETE,
PATCH, OPTIONS und TRACE angegeben werden.
| o | Optional. Operand kann optional angegeben werden. |
| - | Operand kann nicht angegeben werden. |
| x | Operand wird immer angegeben. |
| * | Betrifft nur DATA ALL und nicht DATA NAME
VALUE.
|
Die REQUEST-METHOD POST erfordert einen Content Type Header für die
HTTP-Anfrage. Wenn kein Content Type Header explizit angegeben wird, fügt Natural den
folgenden Standard Content Type Header in die Anfrage ein:
application/x-www-form-urlencoded
Wenn POST-Daten mit dem Content-Typ
application/x-www-form-urlencoded gesendet werden, müssen bestimmte Zeichen
mittels URL-Kodierung dargestellt werden, was bedeutet, dass das Zeichen ersetzt wird
durch %hexadecimal-character-code. Nachfolgend
sind einige grundsätzliche Informationen aufgeführt.
Ausführliche Informationen, wann und warum eine URL-Kodierung notwendig ist, finden Sie in den Memoranden RFC 1630, RFC 1738 und RFC 1808, die vom World Wide Web Consortium (W3C) veröffentlicht werden.
Alle Nicht-ASCII-Zeichen (d.h., gültige ISO 8859/1-Zeichen, die nicht ebenfalls
ASCII-Zeichen sind) müssen URL-kodiert werden. Beispielsweise erscheint die Datei
köln.html in einer URL als k%F6ln.html.
Um Server-Fehler zu vermeiden, sollten Sie nicht eindeutige Zeichen URL-kodiert angeben:
| Nicht eindeutiges Zeichen | URL-Kodierung |
|---|---|
| Tabulatorzeichen | %09 |
| Leerzeichen | %20 |
| [ | %5B |
| \ | %5C |
| ] | %5D |
| ^ | %5E |
| ` | %60 |
| { | %7B |
| | | %7C |
| } | %7D |
| ~ | %7E |
Einige Zeichen haben spezielle Bedeutungen in URLs, z.B. der Doppelpunkt (:), der das URL-Schema vom Rest des URLs abtrennt, der doppelte Schrägstrich (//), der angibt, dass der URL der Common Internet Scheme-Syntax entspricht, und das Prozentzeichen (%). Wenn diese Zeichen als Teile von Dateinamen erscheinen, müssen sie generell URL-kodiert werden, um sie von ihrer Sonderbedeutung in URLs zu unterscheiden (dies ist eine vereinfachte Erklärung, vollständige Informationen finden Sie in den RFCs).
Reservierte Zeichen sind:
| Reserviertes Zeichen | URL-Kodierung |
|---|---|
| " | %22 |
| # | %23 |
| % | %25 |
| & | %26 |
| + | %2B |
| , | %2C |
| / | %2F |
| : | %3A |
| < | %3C |
| = | %3D |
| > | %3E |
| ? | %3F |
| @ | %40 |
Eine Liste der HTTP/HTTPS Status Codes finden Sie im Memorandum RFC 2616, das vom World Wide Web Consortium (W3C) publiziert wird.
Bei HTTP/HTTPS-Status Codes für umgeleitete oder zurückgewiesene Anfragen gelten folgende Besonderheiten.
Die HTTP Status Codes 301, 302 oder 303 bedeuten, dass sich der URL, unter dem sich das
Dokument befindet, geändert hat und dass die Anfrage deshalb an einen anderen URL per
Umleitung weitergeleitet wurde. Als Statuscode wird der Rückgabe-Header mit dem Namen
LOCATION (Adresse) angezeigt. Dieser Header enthält den URL, wohin die
angeforderte Seite umgezogen ist. Es kann eine neue REQUEST
DOCUMENT-Anfrage benutzt werden, um die umgezogene Seite zu suchen.
HTTP-Browser leiten automatisch zum neuen URL weiter, aber das Statement REQUEST
DOCUMENT nimmt die Weiterleitung nicht automatisch vor.
Der HTTP Status Code 401 bedeutet, dass die angeforderte Seite nur aufgerufen werden
kann, wenn mit der Anfrage eine gültige Benutzerkennung und ein gültiges Passwort
angegeben werden. Als Rückmeldung wird der Rückgabe-Header mit dem Namen
WWW-AUTHENTICATE mit dem für diese Anfrage erforderlichen REALM (Bereich)
übermittelt.
HTTP-Browser zeigen üblicherweise einen Dialog mit Benutzerkennung und Passwort an,
aber beim Statement REQUEST DOCUMENT wird kein Dialog angezeigt.
Beispiel 3 - Einfacher HEAD-Request (keine zurückgelieferte Seite)
Beispiel 4 - Einfacher POST-Request (Standard-REQUEST-METHOD)
Beispiel 7 - GET-Request einer IPv6-Adresse an Port-Nummer 8080
Anmerkung
Es gibt einen Beispiel-Dialog V5-RDOC für dieses Statement in der
Beispiel-Library SYSEXV.
REQUEST DOCUMENT FROM "http://bolsap1:5555/invoke/sap.demo/handle_RFC_XML_POST"
WITH
USER #User PASSWORD #Password
DATA
NAME 'XMLData' VALUE #Queryxml
NAME 'repServerName' VALUE 'NT2'
RETURN
PAGE #Resultxml
RESPONSE #rc
REQUEST DOCUMENT FROM "http://pcnatweb:8080"
RETURN
PAGE #Resultxml
RESPONSE #rc
REQUEST DOCUMENT FROM "http://pcnatweb" RESPONSE #rc
REQUEST DOCUMENT FROM "http://pcnatweb/cgi-bin/nwwcgi.exe/sysweb/nat-env"
WITH
DATA
NAME 'XMLData' VALUE #Queryxml
NAME 'repServerName' VALUE 'NT2'
RETURN
PAGE #Resultxml
RESPONSE #rc
REQUEST DOCUMENT FROM "http://pcnatweb/test.txt"
WITH
DATA ALL #document
RETURN
PAGE #Resultxml
RESPONSE #rc
DEFINE DATA
LOCAL
1 #URL (A) DYNAMIC
1 #PAGE (A) DYNAMIC
1 #HTTPSTAT (I4)
1 #PATH (A) DYNAMIC
1 #NAME (A) DYNAMIC
1 #VALUE (A) DYNAMIC
1 #USERID (A8)
1 #PASSWORD (A8)
1 #AUTHHDR (A) DYNAMIC
1 #CREDENTIALS (A) DYNAMIC
1 #PADDCHAR (A2/0:2) INIT <' ','==','='>
1 #LENGTH (I4)
1 #FACTOR (I4)
1 #REMAINDER (I4)
/*
/* #USR4210
1 PARM-FUNCTION (A2) INIT <'BA'>
1 PARM-RC (I4)
1 PARM-ERRTXT (A72)
1 PARM-A (A) DYNAMIC
1 PARM-B (B) DYNAMIC
1 PARM-RFC (B1)
END-DEFINE
**
ASSIGN #URL = 'http://www.softwareag.com/corporate/default.asp'
REQUEST DOCUMENT FROM #URL
RETURN PAGE #PAGE ENCODED CODEPAGE ' '
RESPONSE #HTTPSTAT
*************************************************************
** HTTP response 407 means, that the proxy server requires **
** the client to identify itself! **
*************************************************************
IF #HTTPSTAT = 407
INPUT 'Please enter userid and password' (AD=I) /
'Userid :' #USERID / 'Password:' #PASSWORD
ASSIGN #AUTHHDR = 'Proxy-Authorization'
COMPRESS #USERID ':' #PASSWORD INTO PARM-B LEAVING NO
*************************************************************
** Convert credentials to ASCII **
*************************************************************
MOVE ENCODED PARM-B TO PARM-B
CODEPAGE 'ASCII'
*************************************************************
** ENCODE CREDENTIALS WITH BASE64 **
*************************************************************
** BASE64 demands that the length of the encoded string is **
** a multiple of 3. If encoding length does not match this **
** the encoded string has to be padded with '=' characters.**
** Since USR4210 does not support padding of the base64 **
** string with trailing '=' characters, we have to do this **
** our selfs. **
*************************************************************
CALLNAT 'USR4210N' PARM-FUNCTION PARM-RC PARM-ERRTXT PARM-B PARM-A
PARM-RFC
*
#LENGTH := *LENGTH(PARM-A)
WRITE PARM-A (AL=40) #LENGTH EJECT
DIVIDE 3 INTO #LENGTH GIVING #FACTOR REMAINDER #REMAINDER
COMPRESS PARM-A #PADDCHAR(#REMAINDER)
INTO #CREDENTIALS LEAVING NO
*************************************************************
** Build Proxy-Authorization HTTP header **
*************************************************************
COMPRESS 'Basic ' #CREDENTIALS
INTO #CREDENTIALS
ASSIGN #AUTHHDR = 'Proxy-Authorization'
*************************************************************
** Repeat HTTP request with valid client identification **
*************************************************************
REQUEST DOCUMENT FROM #URL
WITH HEADER NAME #AUTHHDR VALUE #CREDENTIALS
RETURN PAGE #PAGE ENCODED CODEPAGE ' '
RESPONSE #HTTPSTAT
END-IF
END
REQUEST DOCUMENT FROM "http://[2BFC:5022:4081:0000::C:41]:8080"
RETURN
PAGE #Resultxml
RESPONSE #rc
Server gibt einen Header zurück: 'Content-type:
text/html;charset=UTF-8'
Programmcode-Beispiel 1:
... RETURN PAGE inbound-document
Resultierende Verarbeitung:
inbound-document remains UTF-8 encoded.
Programmcode-Beispiel 2:
... RETURN PAGE inbound-document ENCODED [..]
Resultierende Verarbeitung:
inbound-document wird unabhängig davon, ob
code-page-in und
mime-type angegeben werden, von UTF-8 in
die Standard-Codepage umgesetzt. Wenn im Content Type Header eine gültige Kodierung
zurückgeliefert wird, werden mime-type und
code-page-in ignoriert.
Server liefert einen Header zurück: 'Content-type: text/xml'
Programmcode-Beispiel 1:
... RETURN PAGE inbound-document ENCODED
Resultierende Verarbeitung:
inbound-document wird nicht umgesetzt, weil
der Content Type-Header keine gültige Kodierung enthält.
Programmcode-Beispiel 2:
... RETURN PAGE inbound-document ENCODED FOR TYPES 'text/xml' IN CODEPAGE 'USASCII'
Resultierende Verarbeitung:
inbound-document wird von USASCII-Codepage
in die Standard-Codepage umgesetzt. In diesem Fall erfolgt die Umsetzung gemäß der
Annahme des Programmierers über die Kodierung der empfangenen Seite.
Programmcode-Beispiel 3:
...
RETURN PAGE inbound-document ENCODED FOR TYPES 'text/html'
IN CODEPAGE ' '
Resultierende Verarbeitung:
inbound-document wird nicht umgesetzt, weil
der in mime-type angegebene MIME-Typ
'text/html' nicht mit dem im Content Type Header angegebenen Mime-Typ
'text/xml' übereinstimmt.
Programmcode-Beispiel 4:
... RETURN PAGE inbound-document ENCODED IN CODEPAGE ' '
Resultierende Verarbeitung:
inbound-document wird von der mit dem
Subparameter RDCP des Profilparameters
XML angegebenen Standard-Codepage in die Standard-Codepage
umgesetzt.
Anmerkung:
Der Standardwert für den RDCP-Subparameter, der gültig
ist, wenn nichts anderes explizit angegeben wird, ist ISO-8859-1. Siehe
auch Statements PARSE XML und REQUEST
DOCUMENT aktivieren/deaktivieren in der
Parameter-Referenz-Dokumentation.
DEFINE DATA
LOCAL
1 #FROM (A) DYNAMIC
1 #HEADER (A) DYNAMIC
1 #PAGE (A) DYNAMIC
1 #COOKIES (A20/1:3,1:4,2:5)
1 #RC (I4)
END-DEFINE
ASSIGN #FROM = 'http://www.myserver.com'
REQUEST DOCUMENT FROM #FROM
RETURN
HEADER NAME 'Set-Cookie' VALUE #COOKIES(1,2:3,3)
PAGE #PAGE
RESPONSE #RC
PRINT #COOKIES(*,*,*)
END
Im obigen Beispiel-Programm wären die folgenden Array-Definitionen (mit mehreren Dimensionen) ungültig:
RETURN HEADER NAME 'Set-Cookie' VALUE #COOKIES(1:3,2:3,3) RETURN HEADER NAME 'Set-Cookie' VALUE #COOKIES(*,2,*)