UTL_HTTP , 4 of 59

REQUEST Function

This function returns up to the first 2000 bytes of data retrieved from the given URL. This function can be used directly in SQL queries.

Syntax

UTL_HTTP.REQUEST (

url              IN VARCHAR2,
proxy            IN VARCHAR2 DEFAULT NULL), 
wallet_path      IN VARCHAR2 DEFAULT NULL,
wallet_password  IN VARCHAR2 DEFAULT NULL)

RETURN VARCHAR2;

Pragmas

pragma restrict_references (request, wnds, rnds, wnps, rnps);

Parameters

Table 78-7 shows the parameters for the REQUEST function.

Table 78-7 REQUEST Function Parameters

Parameter	Description
url	Universal resource locator.
`proxy`	(Optional) Specifies a proxy server to use when making the HTTP request. See set_proxy for the full format of the proxy setting.
`wallet_path`	(Optional) Specifies a client-side wallet. The client-side wallet contains the list of trusted certificate authorities required for HTTPS request. The format of `wallet_path` on a PC is, for example, `file:c:\WINNT\Profiles\<username>\WALLETS`, and in Unix is, for example, `file:/home/<username>/wallets` When the UTL_HTTP package is executed in the Oracle database server, the wallet is accessed from the database server. Therefore, the wallet path must be accessible from the database server. See `set_wallet` for a description on how to set up an Oracle wallet. Non-HTTPS requests do not require an Oracle wallet.
`wallet_password`	(Optional) Specifies the password required to open the wallet.

Returns

The return type is a string of length 2000 or less, which contains up to the first 2000 bytes of the HTML result returned from the HTTP request to the argument URL.

Exceptions

INIT_FAILED
REQUEST_FAILED

Usage Notes

The URL passed as an argument to this function is not examined for illegal characters, for example, spaces, per the URL specification RFC 2396. The caller should escape those characters with the UTL_URL package. See the comments of the package for the list of legal characters in URLs. Note that URLs should consist of US-ASCII characters only. The use of non-US-ASCII characters in a URL is generally unsafe.

Please see the documentation of the function set_wallet on the use of an Oracle wallet, which is required for accessing HTTPS Web servers.

Unless response error check is turned on, this function does not raise an exception when a 4xx or 5xx response is received from the Web server. Instead, it returns the formatted error message from the Web server:

<HTML> 
<HEAD> 
<TITLE>Error Message</TITLE> 
</HEAD> 
<BODY> 
<H1>Fatal Error 500</H1> 
Can't Access Document:  http://home.nothing.comm. 
<P> 
<B>Reason:</B> Can't locate remote host:  home.nothing.comm. 
<P> 
<P><HR> 
<ADDRESS><A HREF="http://www.w3.org"> 
CERN-HTTPD3.0A</A></ADDRESS> 
</BODY> 
</HTML>

Example

SQLPLUS> SELECT utl_http.request('http://www.my-company.com/') FROM dual;
UTL_HTTP.REQUEST('HTTP://WWW.MY-COMPANY.COM/')                         
<html>
<head><title>My Company Home Page</title>
<!--changed Jan. 16, 19
1 row selected.

If you are behind a firewall, include the proxy parameter. For example, from within the Oracle firewall, where there might be a proxy server named www-proxy.my-company.com:

SQLPLUS> SELECT 
utl_http.request('http://www.my-company.com', 'www-proxy.us.my-company.com') 
FROM dual;