|
|
xdmp:http-get(
|
|
$uri as xs:string,
|
|
[$options as node()?]
|
| ) as item()+ |
|
|
|
Summary:
Sends the http GET method to the specified URI. Returns the http response
as well as whatever information is identified by the specified URI
(for example, an html document).
|
Parameters:
|
$uri
:
The URI of the requested document.
|
$options
(optional):
The options node for this request. The default value is ().
The node for the xdmp:http-get options must be in the
xdmp:http namespace. This parameter can also include
certain option elements (for example, repair,
encoding, default-language) in the
xdmp:document-load and
xdmp:document-get
namespaces.
The xdmp:http-get options include:
<headers> - A sequence of <name>value</name> pairs. The names can be
anything, but many HTTP servers understand HTTP names such as
content-type. These are turned into name:value HTTP
headers. An error is raised if the child elements of the
<headers> option are not of the form
<name>value</name>.
<authentication> - The credentials and the authentication method to use for
this request. This option has child elements for the
username and password.
The username is the name of the user to be authenticated
on the http server. The password is that user's password.
You can optionally specify a method attribute on the
<authentication> element. If it is specified it must be either
'basic' or 'digest'. If a method is specified and the HTTP server
requests a different type of authentication, then an error is raised.
If the attribute is not specified, or matches the server's requested
method, the authentication proceeds.
<timeout> - The amount of time, in seconds, to wait until the HTTP connection
times out. The default value is the request timeout for the group.
<ciphers> - A standard cipher string. For details on legal ciper strings, see
http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS.
<client-cert> - A PEM encoded client certificate for identifying the client to
the remote server.
<client-key> - The private key that corresponds to
client-cert.
<pass-phrase> - A pass phrase, if one is needed to decrypt client-key.
<method> - The authentication method, which can be either "basic" or "digest".
<username> - A user name, if required for authentication.
<password> - A password, if required for authentication.
<allow-sslv3> - A boolean value to specify whether to communicate using the SSL v3 protocol.
The default is
true, which indicates communication using the
SSL v3 protocol.
<allow-tls> - A boolean value to specify whether to communicate using the TLS protocol.
The default is
true, which indicates communication using the
TLS protocol.
<verify-cert> - A boolean value to specify whether the server's certificate should be
verified. The default value is
true. A value of false
should only be specfied after careful consideration of the security risks since it
permits communication with servers whose certificates are expired, revoked,
or signed by unknown or untrusted authorities. A value of false
also removes protection against a man-in-the-middle attack.
|
|
Usage Notes:
The http functions only operate on URIs that use the http or https
schemes; specifying a URI that does not begin with http://
or https:// throws an exception.
If an http function times out, it throws a socket received
exception (SVC-SOCRECV).
If no encoding option (in the xdmp:document-get
namespace) is specified, the encoding defaults to the encoding specified
in the http header. If there is no encoding in the http header, the encoding
defaults to UTF-8.
The first node in the output of xdmp:http-get is the
response header from the http server.
The second node in the output of xdmp:http-get is the
response from the http server. The response is treated as
text, XML, or binary, depending on the content-type header sent from the
http server. If the node is html, the header should indicate
text/html, which is returned as a text document by default.
The type of document is determined by the mimetypes mappings, and
you can change the mappings in the Admin Interface as needed.
If you happen to know that the response is XML, even if the header
does not specify it as XML, and want to process the response as XML,
you can wrap the response in an xdmp:unquote call to
parse the response as XML. You could also use the
<format>xml</format> option (in the
xdmp:document-get namespace) to tell the API to treat the
document as XML. Also, if you know the response is an HTML document,
you can wrap the response in an xdmp:tidy call, which
will treat the text as HTML, clean it up, and return an XHTML XML
document.
|
Example:
xdmp:http-get("http://www.my.com/document.xhtml",
<options xmlns="xdmp:http">
<authentication method="basic">
<username>myname</username>
<password>mypassword</password>
</authentication>
</options>)
=> the response from the server as well as the specified document
|
Example:
xdmp:http-get("http://www.my.com/iso8859document.html",
<options xmlns="xdmp:document-get">
<encoding>iso-8859-1</encoding>
</options>)[2]
=> The specified document, transcoded from ISO-8859-1
to UTF-8 encoding. This assumes the document is
encoded in ISO-8859-1. Note that the encoding option
is in the "xdmp:document-get" namespace.
|
Example:
xdmp:unquote(
xdmp:http-get("http://www.my.com/somexml.xml")[2])
=> The specified xml document, parsed as XML by
xdmp:unquote. If the header specifies a
mimetype that is configured to be treated as
XML, the xdmp:unquote call is not needed.
Alternately, you can treat the response as XML
by specifying XML in the options node as
follows (note that the format option is in
the "xdmp:document-get" namespace:
xdmp:http-get("http://www.my.com/somexml.xml",
<options xmlns="xdmp:http-get">
<format xmlns="xdmp:document-get">xml</format>
</options>)[2]
|
Example:
xdmp:tidy(
xdmp:http-get("http://www.my.com/somehtml.html")[2])[2]
=> The specified html document, cleaned and transformed
to xhtml by xdmp:tidy. The second node of the tidy
output is the xhtml node (the first node is the status).
You could then perform XPath on the output to return
portions of the document. Note that the document (and
all of its elements) will be in the XHTML namespace, so
you need to specify the namespace in the XPath steps.
For example:
xquery version "1.0-ml";
declare namespace xh="http://www.w3.org/1999/xhtml";
xdmp:tidy(
xdmp:http-get("http://www.my.com/somehtml.html")[2])[2]//xh:title
|
|
|
|
xdmp:http-post(
|
|
$uri as xs:string,
|
|
[$options as node()?]
|
| ) as item()+ |
|
|
|
Summary:
Sends the http POST request to the server.
|
Parameters:
|
$uri
:
The URI to which the data is to be posted.
|
$options
(optional):
The options node for this request. The default value is ().
The node for the xdmp:http-post options must be in the
xdmp:http namespace.
The xdmp:http-post options include
the following option (in the xdmp:http namespace), in
addition to the options documented with the
xdmp:http-get $options
parameter:
<data> - This node can contain any string. Anything in the
data
node is sent as a string in the PUT or POST body. When POSTing to a web
service, the data usually needs to be a SOAP XML structure. If you put
an XML structure in the data element, it will return
an error. Therefore, if you need the data to include a payload that is
an XML structure, you should use xdmp:quote to encode
the XML as a string. See the example
below for a data node that uses xdmp:quote.
The other options are the same as the other xdmp:http-*
functions, and the options are documented with the
xdmp:http-get $options
parameter.
|
|
Usage Notes:
The http functions only operate on URIs that use the http or https
schemes; specifying a URI that does not begin with http://
or https:// throws an exception.
If an http function times out, it throws a socket received
exception (SVC-SOCRECV).
If you expect the request body from this http function to be
processed by another application (via a web service, for example),
you must specify a content-type header. If no content-type header is
specified, the content type defaults to application/x-www-form-urlencoded
and the request body will be empty (the request is still accessible via
the request fields).
|
Example:
xdmp:http-post("http://www.my.com/document.xhtml",
<options xmlns="xdmp:http">
<authentication method="basic">
<username>myname</username>
<password>mypassword</password>
</authentication>
</options>)
=> the response from the server as well as the specified document
|
Example:
(: Use xdmp:unquote to encode the XML as a string
because the <data> options element is a string :)
let $payload := xdmp:quote(
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns:SOAP-ENC='http://schemas.xmlsoap.org/soap/encoding/'
xmlns:my='urn:MyConnection'>
<SOAP-ENV:Body>
<my:LogOn>
<my:User>user</my:User>
<my:Password>pass</my:Password>
<my:Ticket>abc123</my:Ticket>
<my:newData>1234</my:newData>
</my:LogOn>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
)
return
xdmp:http-post("http://www.my.com/document.xhtml",
<options xmlns="xdmp:http">
<authentication method="basic">
<username>myname</username>
<password>mypassword</password>
</authentication>
<data>{$payload}</data>
</options>)
=> the response from the server as well as the specified document
|
|
|
|
xdmp:http-put(
|
|
$uri as xs:string,
|
|
[$options as node()?]
|
| ) as item()+ |
|
|
|
Summary:
Sends an HTTP PUT request to an HTTP server.
The HTTP server should return a response, which will differ depending on
the action the HTTP server takes for the PUT.
|
Parameters:
|
$uri
:
The URI to which the data is to be put.
|
$options
(optional):
The options node for this request. The default value is ().
The node for the xdmp:http-put options must be in the
xdmp:http namespace.
The options include
the following option (in the xdmp:http namespace), in
addition to the options documented with the
xdmp:http-get $options
parameter:
<data> - This node can contain any string. Anything in the
data
node is sent as a string in the PUT or POST body.
The other options are the same as the other xdmp:http-*
functions, and the options are documented with the
xdmp:http-get $options
parameter.
|
|
Usage Notes:
The http functions only operate on URIs that use the http or https
schemes; specifying a URI that does not begin with http://
or https:// throws an exception.
If an http function times out, it throws a socket received
exception (SVC-SOCRECV).
If you expect the request body from this http function to be
processed by another application (via a web service, for example),
you must specify a content-type header. If no content-type header is
specified, the content type defaults to application/x-www-form-urlencoded
and the request body will be empty (the request is still accessible via
the request fields).
|
Example:
xdmp:http-put("http://www.my.com/document.xhtml",
<options xmlns="xdmp:http">
<authentication method="basic">
<username>myname</username>
<password>mypassword</password>
</authentication>
</options>)
=> the response from the HTTP server as well as the specified document
|
|
|