Oracle® Database PL/SQL Packages and Types Reference 10g Release 2 (10.2) Part Number B14258-01 |
|
|
View PDF |
The UTL_HTTP
package makes Hypertext Transfer Protocol (HTTP) callouts from SQL and PL/SQL. You can use it to access data on the Internet over HTTP.
When the package fetches data from a Web site using HTTPS, it requires Oracle Wallet Manager to set up an Oracle wallet. Non-HTTPS fetches do not require an Oracle wallet.
See Also:
Oracle Database Advanced Security Administrator's Guide for more information on Wallet Manager
This chapter contains the following topics:
Overview
Constants
Datatypes
Exceptions
Examples
Session Settings Subprograms
HTTP Requests Subprograms
HTTP Responses Subprograms
HTTP Cookies Subprograms
HTTP Persistent Connections Subprograms
Error Conditions Subprograms
This section contains topics which relate to using the UTL_HTTP
package.
With the UTL_HTTP
package, you can write PL/SQL programs that communicate with Web (HTTP) servers. And UTL_HTTP
contains a function that can be used in SQL queries.
The package also supports HTTP over the Secured Socket Layer protocol (SSL), also known as HTTPS, directly or through an HTTP proxy.
Other Internet-related data-access protocols (such as the File Transfer Protocol (FTP) or the Gopher protocol) are also supported using an HTTP proxy server that supports those protocols.
The UTL_HTTP
package uses the constants shown in following tables.
Table 168-1 UTL_HTTP Constants - HTTP Versions
Name | Type | Value | Description |
---|---|---|---|
HTTP_VERSION_1_0 |
VARCHAR2 (10) |
'HTTP/1.0' |
Denotes HTTP version 1.0 that can be used in the function BEGIN_REQUEST . |
HTTP_VERSION_1 |
VARCHAR2 (10) |
'HTTP/1.1' |
Denotes HTTP version 1.1 that can be used in the function BEGIN_REQUEST . |
Table 168-2 UTL_HTTP Constants - Default Ports
Name | Type | Value | Description |
---|---|---|---|
DEFAULT_HTTP_PORT |
PLS_INTEGER |
80 |
The default TCP/IP port (80) at which a Web server or proxy server listens |
DEFAULT_HTTPS_PORT |
PLS_INTEGER |
443 |
The default TCP/IP port (443) at which an HTTPS Web server listens |
Table 168-3 UTL_HTTP Constants - HTTP 1.1 Status Codes
Name | Type | Value | Description |
---|---|---|---|
HTTP_CONTINUE |
PLS_INTEGER |
100 |
The client should continue with its request. This interim response is used to inform the client that the initial part of the request has been received and has not yet been rejected by the server. |
HTTP_SWITCHING_PROTOCOLS |
PLS_INTEGER |
101 |
The server understands and is willing to comply with the client's request, via the Upgrade message header field, for a change in the application protocol being used on this connection. The server will switch protocols to those defined by the response's Upgrade header field immediately after the empty line which terminates the 101 response. |
HTTP_OK |
PLS_INTEGER |
200 |
The request has succeeded. The information returned with the response is dependent on the method used in the request |
HTTP_CREATED CONSTANT |
PLS_INTEGER |
201 |
The request has been fulfilled and resulted in a new resource being created. |
HTTP_ACCEPTED |
PLS_INTEGER |
202 |
The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. |
HTTP_NON_AUTHORITATIVE_INFO |
PLS_INTEGER |
203 |
The returned metainformation in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy. |
HTTP_NO_CONTENT |
PLS_INTEGER |
204 |
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation. |
HTTP_RESET_CONTENT |
PLS_INTEGER |
205 |
The server has fulfilled the request and the user agent should reset the document view which caused the request to be sent. The response must not include an entity. |
HTTP_PARTIAL_CONTENT |
PLS_INTEGER |
206 |
The server has fulfilled the partial GET request for the resource. |
HTTP_MULTIPLE_CHOICES |
PLS_INTEGER |
300 |
The requested resource corresponds to any one of a set of representations, each with its own specific location, and agent- driven negotiation information is being provided so that the user (or user agent) can select a preferred representation and redirect its request to that location. |
HTTP_MOVED_PERMANENTLY |
PLS_INTEGER |
301 |
The requested resource has been assigned a new permanent URI and any future references to this resource should use one of the returned URIs. |
HTTP_FOUND CONSTANT |
PLS_INTEGER |
302 |
The requested resource resides temporarily under a different URI. |
HTTP_SEE_OTHER |
PLS_INTEGER |
303 |
The response to the request can be found under a different URI and should be retrieved using a GET method on that resource. |
HTTP_NOT_MODIFIED |
PLS_INTEGER |
304 |
If the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server responds with this status code. |
HTTP_USE_PROXY |
PLS_INTEGER |
305 |
The requested resource must be accessed through the proxy given by the Location field. The Location field gives the URI of the proxy. |
HTTP_TEMPORARY_REDIRECT |
PLS_INTEGER |
307 |
The requested resource resides temporarily under a different URI. |
HTTP_BAD_REQUEST |
PLS_INTEGER |
400 |
The request could not be understood by the server due to malformed syntax. |
HTTP_UNAUTHORIZED |
PLS_INTEGER |
401 |
The request requires user authentication. The client may repeat the request with a suitable Authorization header field. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. |
HTTP_PAYMENT_REQUIRED |
PLS_INTEGER |
402 |
This code is reserved for future use. |
HTTP_FORBIDDEN |
PLS_INTEGER |
403 |
The server understood the request, but is refusing to fulfill it. |
HTTP_NOT_FOUND |
PLS_INTEGER |
404 |
The server has not found anything matching the Request-URI. |
HTTP_NOT_ACCEPTABLE |
PLS_INTEGER |
406 |
The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. |
HTTP_PROXY_AUTH_REQUIRED |
PLS_INTEGER |
407 |
This code is similar to 401 (Unauthorized), but indicates that the client must first authenticate itself with the proxy. |
HTTP_REQUEST_TIME_OUT |
PLS_INTEGER |
408 |
The client did not produce a request within the time that the server was prepared to wait. |
HTTP_CONFLICT |
PLS_INTEGER |
409 |
The request could not be completed due to a conflict with the current state of the resource. |
HTTP_GONE |
PLS_INTEGER |
410 |
The requested resource is no longer available at the server and no forwarding address is known. |
HTTP_LENGTH_REQUIRED |
PLS_INTEGER |
411 |
The server refuses to accept the request without a defined Content-Length. |
HTTP_PRECONDITION_FAILED |
PLS_INTEGER |
412 |
The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server. |
HTTP_REQUEST_ENTITY_TOO_LARGE CONSTANT |
PLS_INTEGER |
413 |
The server is refusing to process a request because the request entity is larger than the server is willing or able to process. |
HTTP_REQUEST_URI_TOO_LARGE |
PLS_INTEGER |
414 |
The server is refusing to service the request because the Request-URI is longer than the server is willing to interpret. |
HTTP_UNSUPPORTED_MEDIA_TYPE |
PLS_INTEGER |
415 |
The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. |
HTTP_REQ_RANGE_NOT_SATISFIABLE |
PLS_INTEGER |
416 |
A server returns a response with this status code if a request included a Range request-header field, and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If-Range request-header field. |
HTTP_EXPECTATION_FAILED |
PLS_INTEGER |
417 |
The expectation given in an Expect request-header field could not be met by this server, or, if the server is a proxy, the server has unambiguous evidence that the request could not be met by the next-hop server. |
HTTP_NOT_IMPLEMENTED |
PLS_INTEGER |
501 |
The server does not support the functionality required to fulfill the request. |
HTTP_BAD_GATEWAY |
PLS_INTEGER |
502 |
The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request |
HTTP_SERVICE_UNAVAILABLE |
PLS_INTEGER |
503 |
The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. |
HTTP_GATEWAY_TIME_OUT |
PLS_INTEGER |
504 |
The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (for example, HTTP, FTP, LDAP) or some other auxiliary server (for example, DNS) it needed to access in attempting to complete the request. |
HTTP_VERSION_NOT_SUPPORTED |
PLS_INTEGER |
505 |
The server does not support, or refuses to support, the HTTP protocol version that was used in the request message. |
Use this PL/SQL record type to represent an HTTP request.
Syntax
TYPE req IS RECORD ( url VARCHAR2(32767), method VARCHAR2(64), http_version VARCHAR2(64));
Parameters
Table 168-4 REQ Type Parameters
Parameter | Description |
---|---|
url |
The URL of the HTTP request. It is set after the request is created by BEGIN_REQUEST . |
method |
The method to be performed on the resource identified by the URL. It is set after the request is created by BEGIN_REQUEST . |
http_version |
The HTTP protocol version used to send the request. It is set after the request is created by BEGIN_REQUEST . |
Usage Notes
The information returned in REQ
from the interface begin_request
is for read only. Changing the field values in the record has no effect on the request.
There are other fields in REQ
record type whose names begin with the prefix private_.
The fields are private and are intended for use by implementation of the UTL_HTTP
package. You should not modify the fields.
This PL/SQL record type is used to represent an HTTP response.
Syntax
TYPE resp IS RECORD ( status_code PLS_INTEGER, reason_phrase VARCHAR2(256), http_version VARCHAR2(64));
Parameters
Table 168-5 RESP Type Parameters
Parameter | Description |
---|---|
status_code |
The status code returned by the Web server. It is a 3-digit integer that indicates the results of the HTTP request as handled by the Web server. It is set after the response is processed by GET_RESPONSE . |
reason_phrase |
The short textual message returned by the Web server that describe the status code. It gives a brief description of the results of the HTTP request as handled by the Web server. It is set after the response is processed by GET_RESPONSE . |
http_version |
The HTTP protocol version used in the HTTP response. It is set after the response is processed by GET_RESPONSE . |
Usage Notes
The information returned in RESP
from the interface GET_RESPONSE
is read-only. There are other fields in the RESP
record type whose names begin with the prefix private_.
The fields are private and are intended for use by implementation of the UTL_HTTP
package. You should not modify the fields.
The COOKIE
type is the PL/SQL record type that represents an HTTP cookie. The COOKIE_TABLE
type is a PL/SQL index-by-table type that represents a collection of HTTP cookies.
Syntax
TYPE cookie IS RECORD ( name VARCHAR2(256), value VARCHAR2(1024), domain VARCHAR2(256), expire TIMESTAMP WITH TIME ZONE, path VARCHAR2(1024), secure BOOLEAN, version PLS_INTEGER, comment VARCHAR2(1024)); TYPE cookie_table IS TABLE OF cookie INDEX BY binary_integer;
Fields of COOKIE Record Type
Table 168-6 shows the fields for the COOKIE
and COOKIE_TABLE
record types.
Table 168-6 Fields of COOKIE and COOKIE_TABLE Type
Field | Description |
---|---|
name |
The name of the HTTP cookie |
value |
The value of the cookie |
domain |
The domain for which the cookie is valid |
expire |
The time by which the cookie will expire |
path |
The subset of URLs to which the cookie applies |
secure |
Should the cookie be returned to the Web server using secured means only. |
version |
The version of the HTTP cookie specification the cookie conforms. This field is NULL for Netscape cookies. |
comment |
The comment that describes the intended use of the cookie. This field is NULL for Netscape cookies. |
Usage Notes
PL/SQL programs do not usually examine or change the cookie information stored in the UTL_HTTP
package. The cookies are maintained by the package transparently. They are maintained inside the UTL_HTTP
package, and they last for the duration of the database session only. PL/SQL applications that require cookies to be maintained beyond the lifetime of a database session can read the cookies using GET_COOKIES,
store them persistently in a database table, and re-store the cookies back in the package using ADD_COOKIES
in the next database session. All the fields in the cookie
record, except for the comment field, must be stored. Do not alter the cookie information, which can result in an application error in the Web server or compromise the security of the PL/SQL and the Web server applications. See "Retrieving and Restoring Cookies".
Use the PL/SQL record type to represent the remote hosts and TCP/IP ports of a network connection that is kept persistent after an HTTP request is completed, according to the HTTP 1.1 protocol specification. The persistent network connection may be reused by a subsequent HTTP request to the same host and port. The subsequent HTTP request may be completed faster because the network connection latency is avoided. connection_table
is a PL/SQL table of connection
.
For a direct HTTP persistent connection to a Web server, the host
and port
fields contain the host name and TCP/IP port number of the Web server. The proxy_host
and proxy_port
fields are not set. For an HTTP persistent connection that was previously used to connect to a Web server using a proxy, the proxy_host
and proxy_port
fields contain the host name and TCP/IP port number of the proxy server. The host and port fields are not set, which indicates that the persistent connection, while connected to a proxy server, is not bound to any particular target Web server. An HTTP persistent connection to a proxy server can be used to access any target Web server that is using a proxy.
The SSL
field indicates if Secured Socket Layer (SSL) is being used in an HTTP persistent connection. An HTTPS request is an HTTP request made over SSL. For an HTTPS (SSL) persistent connection connected using a proxy, the host and port fields contain the host name and TCP/IP port number of the target HTTPS Web server and the fields will always be set. An HTTPS persistent connection to an HTTPS Web server using a proxy server can only be reused to make another request to the same target Web server.
Syntax
TYPE connection IS RECORD ( host VARCHAR2(256), port PLS_INTEGER, proxy_host VARCHAR2(256), proxy_port PLS_INTEGER, ssl BOOLEAN); TYPE connection_table IS TABLE OF connection INDEX BY BINARY_INTEGER;
The UTL_HTTP
package provides access to the HTTP protocol. The interfaces must be called in the order shown in Figure 168-1, or an exception will be raised.
The following can be called at any time:
Non-protocol interfaces that manipulate cookies
GET_COOKIE_COUNT
GET_COOKIES
ADD_COOKIES
CLEAR_COOKIES
Persistent connections
GET_PERSISTENT_CONN_COUNT
GET_PERSISTENT_CONNS
CLOSE_PERSISTENT_CONN
CLOSE_PERSISTENT_CONNS
Interfaces that manipulate attributes and configurations of the UTL_HTTP
package in the current session
SET_PROXY
GET_PROXY
SET_COOKIE_SUPPORT
GET_COOKIE_SUPPORT
SET_FOLLOW_REDIRECT
GET_FOLLOW_REDIRECT
SET_BODY_CHARSET
GET_BODY_CHARSET
SET_PERSISTENT_CONN_SUPPORT
GET_PERSISTENT_CONN_SUPPORT
SET_DETAILED_EXCP_SUPPORT
GET_DETAILED_EXCP_SUPPORT
SET_WALLET
SET_TRANSFER_TIMEOUT
GET_TRANSFER_TIMEOUT
Interfaces that retrieve the last detailed exception code and message UTL_HTTP
package in the current session
GET_DETAILED_SQLCODE
GET_DETAILED_SQLERRM
NOTE:
Some of the request and response interfaces bear the same name as the interface that manipulates the attributes and configurations of the package in the current session. They are overloaded versions of the interface that manipulate a request or a response.REQUEST
and REQUEST_PIECES
take a string uniform resource locator (URL), contact that site, and return the data (typically HTML) obtained from that site.
You should not expect REQUEST
or REQUEST_PIECES
to succeed in contacting a URL unless you can contact that URL by using a browser on the same machine (and with the same privileges, environment variables, and so on.)
If REQUEST
or REQUEST_PIECES
fails (for example, if it raises an exception, or if it returns an HTML-formatted error message, but you believe that the URL argument is correct), then try contacting that same URL with a browser to verify network availability from your machine. You may have a proxy server set in your browser that needs to be set with each REQUEST
or REQUEST_PIECES
call using the optional proxy
parameter.
Note:
UTL_HTTP
can also use environment variables to specify its proxy behavior. For example, on UNIX, setting the environment variable http_proxy
to a URL uses that service as the proxy server for HTTP requests. Setting the environment variable no_proxy
to a domain name does not use the HTTP proxy server for URLs in that domain. When the UTL_HTTP
package is executed in the Oracle database server, the environment variables are the ones that are set when the database instance is started.Session settings manipulate the configuration and default behavior of UTL_HTTP
when HTTP requests are executed within a database user session. When a request is created, it inherits the default settings of the HTTP cookie support, follow-redirect, body character set, persistent-connection support, and transfer timeout of the current session. Those settings can be changed later by calling the request interface. When a response is created for a request, it inherits those settings from the request. Only the body character set can be changed later by calling the response interface.
See Also:
Session Settings SubprogramsThe HTTP Requests group of subprograms begin an HTTP request, manipulate attributes, and send the request information to the Web server. When a request is created, it inherits the default settings of the HTTP cookie support, follow-redirect, body character set, persistent-connection support, and transfer timeout of the current session. The settings can be changed by calling the request interface.
See Also:
HTTP Requests SubprogramsThe HTTP Responses group of subprograms manipulate an HTTP response obtained from GET_RESPONSE and receive response information from the Web server. When a response is created for a request, it inherits settings of the HTTP cookie support, follow-redirect, body character set, persistent-connection support, and transfer timeout from the request. Only the body character set can be changed by calling the response interface.
See Also:
HTTP Responses SubprogramsThe UTL_HTTP
package provides subprograms to manipulate HTTP cookies.
See Also:
HTTP Cookies SubprogramsThe UTL_HTTP
package provides subprograms to manipulate persistent connections.
See Also:
HTTP Persistent Connections SubprogramsThe UTL_HTTP
package provides subprograms to retrieve error information.
See Also:
Error Conditions SubprogramsTable 168-7 lists the exceptions that the UTL_HTTP
package interface can raise. By default, UTL_HTTP
raises the exception request_failed
when a request fails to execute. If the package is set to raise a detailed exception by set_detailed_excp_support
, the rest of the exceptions will be raised directly (except for the exception end_of_body
, which will be raised by READ_TEXT
, READ_LINE
, and READ_RAW
regardless of the setting).
Table 168-7 UTL_HTTP Exceptions
Exception | Error Code | Reason | Where Raised |
---|---|---|---|
REQUEST_FAILED |
29273 |
The request fails to executes | Any HTTP request or response interface when detailed_exception is disabled |
BAD_ARGUMENT |
29261 |
The argument passed to the interface is bad | Any HTTP request or response interface when detailed_exception is enabled |
BAD_URL |
29262 |
The requested URL is badly formed | BEGIN_REQUEST , when detailed_exception is enabled |
PROTOCOL_ERROR |
29263 |
An HTTP protocol error occurs when communicating with the Web server | SET_HEADER , GET_RESPONSE , READ_RAW , READ_TEXT , and READ_LINE , when detailed_exception is enabled |
UNKNOWN_SCHEME |
29264 |
The scheme of the requested URL is unknown | BEGIN_REQUEST and GET_RESPONSE , when detailed_exception is enabled |
HEADER_NOT_FOUND |
29265 |
The header is not found | GET_HEADER , GET_HEADER_BY_NAME , when detailed_exception is enabled |
END_OF_BODY |
29266 |
The end of HTTP response body is reached | READ_RAW , READ_TEXT , and READ_LINE , when detailed_exception is enabled |
ILLEGAL_CALL |
29267 |
The call to UTL_HTTP is illegal at the current state of the HTTP request |
SET_HEADER , SET_AUTHENTICATION , and SET_PERSISTENT_CONN_SUPPORT , when detailed_exception is enabled |
HTTP_CLIENT_ERROR |
29268 |
From GET_RESPONSE , the response status code indicates that a client error has occurred (status code in 4xx range). Or from begin_request , the HTTP proxy returns a status code in the 4xx range when making an HTTPS request through the proxy. |
GET_RESPONSE , BEGIN_REQUEST when detailed_exception is enabled |
HTTP_SERVER_ERROR |
29269 |
From GET_RESPONSE , the response status code indicates that a client error has occurred (status code in 5xx range). Or from begin_request , the HTTP proxy returns a status code in the 5xx range when making an HTTPS request through the proxy. |
GET_RESPONSE, BEGIN_REQUEST when detailed_exception is enabled |
TOO_MANY_REQUESTS |
29270 |
Too many requests or responses are open | BEGIN_REQUEST , when detailed_exception is enabled |
PARTIAL_MULTIBYTE_EXCEPTION |
29275 |
No complete character is read and a partial multibyte character is found at the end of the response body | READ_TEXT and READ_LINE, when detailed_exception is enabled |
TRANSFER_TIMEOUT |
29276 |
No data is read and a read timeout occurred | READ_TEXT and READ_LINE, when detailed_exception is enabled |
NOTE:
Thepartial_multibyte_char
and transfer_timeout
exceptions are duplicates of the same exceptions defined in UTL_TCP.
They are defined in this package so that the use of this package does not require the knowledge of the UTL_TCP
. As those exceptions are duplicates, an exception handle that catches the partial_multibyte_char
and transfer_timeout
exceptions in this package also catch the exceptions in the UTL_TCP.
For REQUEST
and REQUEST_PIECES
, the request_failed
exception is raised when any exception occurs and detailed_exception
is disabled.
The following examples demonstrate how to use UTL_HTTP
.
SET SERVEROUTPUT ON SIZE 40000 DECLARE req UTL_HTTP.REQ; resp UTL_HTTP.RESP; value VARCHAR2(1024); BEGIN UTL_HTTP.SET_PROXY('proxy.my-company.com', 'corp.my-company.com'); req := UTL_HTTP.BEGIN_REQUEST('http://www-hr.corp.my-company.com'); UTL_HTTP.SET_HEADER(req, 'User-Agent', 'Mozilla/4.0'); resp := UTL_HTTP.GET_RESPONSE(req); LOOP UTL_HTTP.READ_LINE(resp, value, TRUE); DBMS_OUTPUT.PUT_LINE(value); END LOOP; UTL_HTTP.END_RESPONSE(resp); EXCEPTION WHEN UTL_HTTP.END_OF_BODY THEN UTL_HTTP.END_RESPONSE(resp); END;
Retrieving HTTP Response Headers
SET SERVEROUTPUT ON SIZE 40000 DECLARE req UTL_HTTP.REQ; resp UTL_HTTP.RESP; name VARCHAR2(256); value VARCHAR2(1024); BEGIN UTL_HTTP.SET_PROXY('proxy.my-company.com', 'corp.my-company.com'); req := UTL_HTTP.BEGIN_REQUEST('http://www-hr.corp.my-company.com'); UTL_HTTP.SET_HEADER(req, 'User-Agent', 'Mozilla/4.0'); resp := UTL_HTTP.GET_RESPONSE(req); DBMS_OUTPUT.PUT_LINE('HTTP response status code: ' || resp.status_code); DBMS_OUTPUT.PUT_LINE('HTTP response reason phrase: ' || resp.reason_phrase); FOR i IN 1..UTL_HTTP.GET_HEADER_COUNT(resp) LOOP UTL_HTTP.GET_HEADER(resp, i, name, value); DBMS_OUTPUT.PUT_LINE(name || ': ' || value); END LOOP; UTL_HTTP.END_RESPONSE(resp); END;
SET serveroutput ON SIZE 40000 CREATE OR REPLACE PROCEDURE get_page (url IN VARCHAR2, username IN VARCHAR2 DEFAULT NULL, password IN VARCHAR2 DEFAULT NULL, realm IN VARCHAR2 DEFAULT NULL) AS req UTL_HTTP.REQ; resp UTL_HTTP.RESP; my_scheme VARCHAR2(256); my_realm VARCHAR2(256); my_proxy BOOLEAN; BEGIN -- Turn off checking of status code. We will check it by ourselves. UTL_HTTP.HTTP_RESPONSE_ERROR_CHECK(FALSE); req := UTL_HTTP.BEGIN_REQUEST(url); IF (username IS NOT NULL) THEN UTL_HTTP.SET_AUTHENTICATION(req, username, password); -- Use HTTP Basic Authen. Scheme END IF; resp := UTL_HTTP.GET_RESPONSE(req); IF (resp.status_code = UTL_HTTP.HTTP_UNAUTHORIZED) THEN UTL_HTTP.GET_AUTHENTICATION(resp, my_scheme, my_realm, my_proxy); IF (my_proxy) THEN DBMS_OUTPUT.PUT_LINE('Web proxy server is protected.'); DBMS_OUTPUT.PUT('Please supplied the required ' || my_scheme || ' authentication username/password for realm ' || my_realm || ' for the proxy server.'); ELSE DBMS_OUTPUT.PUT_LINE('Web page ' || url || ' is protected.'); DBMS_OUTPUT.PUT('Please supplied the required ' || my_scheme || ' authentication username/password for realm ' || my_realm || ' for the Web page.'); END IF; UTL_HTTP.END_RESPONSE(resp); RETURN; END IF; FOR i IN 1..UTL_HTTP.GET_HEADER_COUNT(resp) LOOP UTL_HTTP.GET_HEADER(resp, i, name, value); DBMS_OUTPUT.PUT_LINE(name || ': ' || value); END LOOP; UTL_HTTP.END_RESPONSE(resp); END;
CREATE TABLE my_cookies ( session_id INTEGER, name VARCHAR2(256), value VARCHAR2(1024), domain VARCHAR2(256), expire DATE, path VARCHAR2(1024), secure VARCHAR2(1), version INTEGER); CREATE SEQUENCE session_id; SET SERVEROUTPUT ON SIZE 40000 REM Retrieve cookies from UTL_HTTP CREATE OR REPLACE FUNCTION save_cookies RETURN PLS_INTEGER AS cookies UTL_HTTP.COOKIE_TABLE; my_session_id PLS_INTEGER; secure VARCHAR2(1); BEGIN /* assume that some cookies have been set in previous HTTP requests. */ UTL_HTTP.GET_COOKIES(cookies); SELECT session_id.nextval INTO my_session_id FROM DUAL; FOR i in 1..cookies.count LOOP IF (cookies(i).secure) THEN secure := 'Y'; ELSE secure := 'N'; END IF; INSERT INTO my_cookies VALUES (my_session_id, cookies(i).name, cookies(i).value, cookies(i).domain, cookies(i).expire, cookies(i).path, secure, cookies(i).version); END LOOP; RETURN my_session_id; END; / REM Retrieve cookies from UTL_HTTP CREATE OR REPLACE PROCEDURE restore_cookies (this_session_id IN PLS_INTEGER) AS cookies UTL_HTTP.COOKIE_TABLE; cookie UTL_HTTP.COOKIE; i PLS_INTEGER := 0; CURSOR c (c_session_id PLS_INTEGER) IS SELECT * FROM my_cookies WHERE session_id = c_session_id; BEGIN FOR r IN c(this_session_id) LOOP i := i + 1; cookie.name := r.name; cookie.value := r.value; cookie.domain := r.domain; cookie.expire := r.expire; cookie.path := r.path; IF (r.secure = 'Y') THEN cookie.secure := TRUE; ELSE cookie.secure := FALSE; END IF; cookie.version := r.version; cookies(i) := cookie; END LOOP; UTL_HTTP.CLEAR_COOKIES; UTL_HTTP.ADD_COOKIES(cookies); END; /
UTL_HTTP
subprograms are grouped by function:
REQUEST
and REQUEST_PIECES
take a string uniform resource locator (URL), contact that site, and return the data (typically HTML) obtained from that site.
Table 168-8 UTL_HTTP Subprograms—Simple HTTP Fetches in a Single Call
Subprogram | Description |
---|---|
REQUEST Function |
Returns up to the first 2000 bytes of the data retrieved from the given URL. This function can be used directly in SQL queries. |
REQUEST_PIECES Function |
Returns a PL/SQL table of 2000-byte pieces of the data retrieved from the given URL |
Table 168-9 UTL_HTTP Subprograms—Session Settings
Subprogram | Description |
---|---|
GET_BODY_CHARSET Procedure |
Retrieves the default character set of the body of all future HTTP requests |
GET_COOKIE_SUPPORT Procedure |
Retrieves the current cookie support settings |
GET_DETAILED_EXCP_SUPPORT Procedure |
Checks if the UTL_HTTP package will raise a detailed exception or not |
GET_FOLLOW_REDIRECT Procedure |
Retrieves the follow-redirect setting in the current session |
GET_PERSISTENT_CONN_SUPPORT Procedure |
Checks if the persistent connection support is enabled and gets the maximum number of persistent connections in the current session |
GET_PROXY Procedure |
Retrieves the current proxy settings |
GET_RESPONSE_ERROR_CHECK Procedure |
Checks if the response error check is set or not |
GET_TRANSFER_TIMEOUT Procedure |
Retrieves the current network transfer timeout value |
SET_TRANSFER_TIMEOUT Procedure |
Sets the default character set of the body of all future HTTP requests when the media type is text and the character set is not specified in the Content-Type header |
SET_COOKIE_SUPPORT Procedures |
Sets whether or not future HTTP requests will support HTTP cookies; sets the maximum number of cookies maintained in the current database user session |
SET_DETAILED_EXCP_SUPPORT Procedure |
Sets the UTL_HTTP package to raise a detailed exception |
SET_FOLLOW_REDIRECT Procedures |
Sets the maximum number of times UTL_HTTP follows the HTTP redirect instruction in the HTTP responses to future requests in the GET_RESPONSE function |
SET_PERSISTENT_CONN_SUPPORT Procedure |
Sets whether or not future HTTP requests will support the HTTP 1.1 persistent connection; sets the maximum number of persistent connections maintained in the current database user session |
SET_PROXY Procedure |
Sets the proxy to be used for requests of HTTP or other protocols |
SET_RESPONSE_ERROR_CHECK Procedure |
Sets whether or not GET_RESPONSE raises an exception when the Web server returns a status code that indicates an error—a status code in the 4xx or 5xx ranges |
SET_TRANSFER_TIMEOUT Procedure |
Sets the timeout value for UTL_HTTP to read the HTTP response from the Web server or proxy server |
SET_WALLET Procedure |
Sets the Oracle Wallet used for all HTTP requests over Secured Socket Layer (SSL), that is, HTTPS |
Table 168-10 UTL_HTTP Subprograms—HTTP Requests
Subprogram | Description |
---|---|
BEGIN_REQUEST Function |
Begins a new HTTP request.UTL_HTTP establishes the network connection to the target Web server or the proxy server and sends the HTTP request line. |
END_REQUEST Procedure |
Ends the HTTP request |
SET_HEADER Procedure |
Sets an HTTP request header. The request header is sent to the Web server as soon as it is set. |
SET_AUTHENTICATION Procedure |
Sets HTTP authentication information in the HTTP request header. The Web server needs this information to authorize the request. |
SET_BODY_CHARSET Procedures |
Sets the character set of the request body when the media type is text but the character set is not specified in the Content-Type header |
SET_COOKIE_SUPPORT Procedures |
Enables or disables support for the HTTP cookies in the request |
SET_FOLLOW_REDIRECT Procedures |
Sets the maximum number of times UTL_HTTP follows the HTTP redirect instruction in the HTTP response to this request in the GET_RESPONSE Function |
SET_PERSISTENT_CONN_SUPPORT Procedure |
Enables or disables support for the HTTP 1.1 persistent-connection in the request |
SET_PROXY Procedure |
Writes a text line in the HTTP request body and ends the line with new-line characters (CRLF as defined in UTL_TCP ) |
WRITE_RAW Procedure |
Writes some binary data in the HTTP request body |
WRITE_TEXT Procedure |
Writes some text data in the HTTP request body |
Table 168-11 UTL_HTTP Subprograms—HTTP Responses
Subprogram | Description |
---|---|
END_RESPONSE Procedure |
Ends the HTTP response. It completes the HTTP request and response. |
GET_AUTHENTICATION Procedure |
Retrieves the HTTP authentication information needed for the request to be accepted by the Web server as indicated in the HTTP response header |
GET_HEADER Procedure |
Returns the nth HTTP response header name and value returned in the response |
GET_HEADER_BY_NAME Procedure |
Returns the HTTP response header value returned in the response given the name of the header |
GET_HEADER_COUNT Function |
Returns the number of HTTP response headers returned in the response |
GET_RESPONSE Function |
Reads the HTTP response. When the function returns, the status line and the HTTP response headers have been read and processed. |
READ_LINE Procedure |
Reads the HTTP response body in text form until the end of line is reached and returns the output in the caller-supplied buffer |
READ_RAW Procedure |
Reads the HTTP response body in binary form and returns the output in the caller-supplied buffer |
READ_TEXT Procedure |
Reads the HTTP response body in text form and returns the output in the caller-supplied buffer |
SET_BODY_CHARSET Procedures |
Sets the character set of the response body when the media type is "text" but the character set is not specified in the "Content-Type" header |
Table 168-12 UTL_HTTP Subprograms—HTTP Cookies
Subprogram | Description |
---|---|
ADD_COOKIES Procedure |
Adds the cookies maintained by UTL_HTTP |
CLEAR_COOKIES Procedure |
Clears all cookies maintained by the UTL_HTTP package |
GET_COOKIE_COUNT Function |
Returns the number of cookies currently maintained by the UTL_HTTP package set by all Web servers |
GET_COOKIES Function |
Returns all the cookies currently maintained by the UTL_HTTP package set by all Web servers |
Table 168-13 UTL_HTTP Subprograms—HTTP Persistent Connections
Subprogram | Description |
---|---|
CLOSE_PERSISTENT_CONN Procedure |
Closes an HTTP persistent connection maintained by the UTL_HTTP package in the current database session |
CLOSE_PERSISTENT_CONNS Procedure |
Closes a group of HTTP persistent connections maintained by the UTL_HTTP package in the current database session |
GET_PERSISTENT_CONN_COUNT Function |
Returns the number of network connections currently kept persistent by the UTL_HTTP package to the Web servers |
GET_PERSISTENT_CONNS Procedure |
Returns all the network connections currently kept persistent by the UTL_HTTP package to the Web servers |
Table 168-14 UTL_HTTP Subprograms—Error Conditions
Subprogram | Description |
---|---|
GET_DETAILED_SQLCODE Function |
Retrieves the detailed SQLCODE of the last exception raised |
GET_DETAILED_SQLERRM Function |
Retrieves the detailed SQLERRM of the last exception raised |
Table 168-15 UTL_HTTP Package Subprograms
Subprogram | Description | Group |
---|---|---|
ADD_COOKIES Procedure |
Adds the cookies maintained by UTL_HTTP |
HTTP Cookies Subprograms |
BEGIN_REQUEST Function |
Begins a new HTTP request. UTL_HTTP establishes the network connection to the target Web server or the proxy server and sends the HTTP request line |
HTTP Requests Subprograms |
CLEAR_COOKIES Procedure |
Clears all cookies maintained by the UTL_HTTP package |
HTTP Cookies Subprograms |
CLOSE_PERSISTENT_CONN Procedure |
Closes an HTTP persistent connection maintained by the UTL_HTTP package in the current database session |
HTTP Persistent Connections Subprograms |
CLOSE_PERSISTENT_CONNS Procedure |
Closes a group of HTTP persistent connections maintained by the UTL_HTTP package in the current database session |
HTTP Persistent Connections Subprograms |
END_REQUEST Procedure |
Ends the HTTP request | HTTP Requests Subprograms |
END_RESPONSE Procedure |
Ends the HTTP response. It completes the HTTP request and response | HTTP Responses Subprograms |
GET_AUTHENTICATION Procedure |
Retrieves the HTTP authentication information needed for the request to be accepted by the Web server as indicated in the HTTP response header | HTTP Responses Subprograms |
GET_BODY_CHARSET Procedure |
Retrieves the default character set of the body of all future HTTP requests | Session Settings Subprograms |
GET_COOKIE_COUNT Function |
Returns the number of cookies currently maintained by the UTL_HTTP package set by all Web servers |
HTTP Cookies Subprograms |
GET_COOKIE_SUPPORT Procedure |
Retrieves the current cookie support settings | Session Settings Subprograms |
GET_COOKIES Function |
Returns all the cookies currently maintained by the UTL_HTTP package set by all Web servers |
HTTP Cookies Subprograms |
GET_DETAILED_EXCP_SUPPORT Procedure |
Checks if the UTL_HTTP package will raise a detailed exception or not |
Session Settings Subprograms |
GET_DETAILED_SQLCODE Function |
Retrieves the detailed SQLCODE of the last exception raised |
Error Conditions Subprograms |
GET_DETAILED_SQLERRM Function |
Retrieves the detailed SQLERRM of the last exception raised |
Error Conditions Subprograms |
GET_FOLLOW_REDIRECT Procedure |
Retrieves the follow-redirect setting in the current session | Session Settings Subprograms |
GET_HEADER Procedure |
Returns the nth HTTP response header name and value returned in the response | HTTP Responses Subprograms |
GET_HEADER_BY_NAME Procedure |
Returns the HTTP response header value returned in the response given the name of the header | HTTP Responses Subprograms |
GET_HEADER_COUNT Function |
Returns the number of HTTP response headers returned in the response | HTTP Responses and HTTP Responses Subprograms |
GET_PERSISTENT_CONN_COUNT Function |
Returns the number of network connections currently kept persistent by the UTL_HTTP package to the Web servers |
HTTP Persistent Connections Subprograms |
GET_HEADER_COUNT Function |
Sees whether or not future HTTP requests will support the HTTP 1.1 persistent connection; sets the maximum number of persistent connections maintained in the current database user session | Session Settings Subprograms |
GET_PERSISTENT_CONN_SUPPORT Procedure |
Checks if the persistent connection support is enabled and gets the maximum number of persistent connections in the current session (see Session Settings Subprograms) | HTTP Persistent Connections Subprograms |
GET_PERSISTENT_CONNS Procedure |
Returns all the network connections currently kept persistent by the UTL_HTTP package to the Web servers |
HTTP Persistent Connections Subprograms |
GET_PROXY Procedure |
Retrieves the current proxy settings | Session Settings Subprograms |
GET_RESPONSE Function |
Reads the HTTP response. When the function returns, the status line and the HTTP response headers have been read and processed | HTTP Responses Subprograms |
GET_RESPONSE_ERROR_CHECK Procedure |
Checks if the response error check is set or no | Session Settings Subprograms |
GET_TRANSFER_TIMEOUT Procedure |
Retrieves the current network transfer timeout value | Session Settings Subprograms |
READ_LINE Procedure |
Reads the HTTP response body in text form until the end of line is reached and returns the output in the caller-supplied buffer | HTTP Responses Subprograms |
READ_RAW Procedure |
Reads the HTTP response body in binary form and returns the output in the caller-supplied buffer | HTTP Responses Subprograms |
READ_TEXT Procedure |
Reads the HTTP response body in text form and returns the output in the caller-supplied buffer | HTTP Responses Subprograms |
REQUEST Function |
Returns up to the first 2000 bytes of the data retrieved from the given URL. This function can be used directly in SQL queries. | Simple HTTP Fetches in a Single Call Subprograms |
REQUEST_PIECES Function |
Returns a PL/SQL table of 2000-byte pieces of the data retrieved from the given URL | Simple HTTP Fetches in a Single Call Subprograms |
SET_AUTHENTICATION Procedure |
Sets HTTP authentication information in the HTTP request header. The Web server needs this information to authorize the request. | HTTP Requests Subprograms |
SET_BODY_CHARSET Procedures |
Sets the default character set of the body of all future HTTP requests when the media type is text and the character set is not specified in the Content-Type header |
Session Settings Subprograms |
SET_BODY_CHARSET Procedures |
Sets the character set of the request body when the media type is text but the character set is not specified in the Content-Type header |
HTTP Requests Subprograms |
SET_BODY_CHARSET Procedures |
Sets the character set of the response body when the media type is "text" but the character set is not specified in the "Content-Type" header | HTTP Responses Subprograms and Session Settings Subprograms |
SET_COOKIE_SUPPORT Procedures |
Enables or disables support for the HTTP cookies in the request | HTTP Requests Subprograms |
SET_DETAILED_EXCP_SUPPORT Procedure |
Sets whether or not future HTTP requests will support HTTP cookies; sets the maximum number of cookies maintained in the current database user session | Session Settings Subprograms |
SET_DETAILED_EXCP_SUPPORT Procedure |
Sets the UTL_HTTP package to raise a detailed exception |
Session Settings Subprograms |
SET_FOLLOW_REDIRECT Procedures |
Sets the maximum number of times UTL_HTTP follows the HTTP redirect instruction in the HTTP response to this request in the GET_RESPONSE function |
HTTP Requests Subprograms |
SET_HEADER Procedure |
Sets the maximum number of times UTL_HTTP follows the HTTP redirect instruction in the HTTP responses to future requests in the GET_RESPONSE function |
Session Settings Subprograms |
SET_HEADER Procedure |
Sets an HTTP request header. The request header is sent to the Web server as soon as it is set. | HTTP Requests Subprograms |
SET_PERSISTENT_CONN_SUPPORT Procedure |
Enables or disables support for the HTTP 1.1 persistent-connection in the request | HTTP Requests Subprograms |
SET_PROXY Procedure |
Sets the proxy to be used for requests of HTTP or other protocols | Session Settings and Session Settings Subprograms |
SET_RESPONSE_ERROR_CHECK Procedure |
Sets whether or not GET_RESPONSE raises an exception when the Web server returns a status code that indicates an error—a status code in the 4xx or 5xx ranges |
Session Settings Subprograms |
SET_TRANSFER_TIMEOUT Procedure |
Sets the timeout value for UTL_HTTP to read the HTTP response from the Web server or proxy server |
Session Settings and Session Settings Subprograms |
SET_WALLET Procedure |
Sets the Oracle Wallet used for all HTTP requests over Secured Socket Layer (SSL), that is, HTTPS | Session Settings Subprograms |
WRITE_LINE Procedure |
Writes a text line in the HTTP request body and ends the line with new-line characters (CRLF as defined in UTL_TCP | HTTP Requests Subprograms |
WRITE_RAW Procedure |
Writes some binary data in the HTTP request body | HTTP Requests Subprograms |
WRITE_TEXT Procedure |
Writes some text data in the HTTP request body | HTTP Requests Subprograms |
This procedure adds the cookies maintained by UTL_HTTP
.
Syntax
UTL_HTTP.ADD_COOKIES ( cookies IN cookie_table);
Parameters
Usage Notes
The cookies that the package currently maintains are not cleared before new cookies are added.
This functions begins a new HTTP request. UTL_HTTP
establishes the network connection to the target Web server or the proxy server and sends the HTTP request line. The PL/SQL program continues the request by calling some other interface to complete the request. The URL may contain the username and password needed to authenticate the request to the server. The format is
scheme://[user[:password]@]host[:port]/[...]
Syntax
UTL_HTTP.BEGIN_REQUEST ( url IN VARCHAR2, method IN VARCHAR2 DEFAULT 'GET', http_version IN VARCHAR2 DEFAULT NULL) RETURN req;
Parameters
Table 168-17 BEGIN_REQUEST Function Parameters
Parameter | Description |
---|---|
url |
The URL of the HTTP request |
method |
The method performed on the resource identified by the URL |
http_version |
The HTTP protocol version that sends the request. The format of the protocol version is HTTP/major-version.minor-version , where major-version and minor-version are positive numbers. If this parameter is set to NULL , UTL_HTTP uses the latest HTTP protocol version that it supports to send the request. The latest version that the package supports is 1.1 and it can be upgraded to a later version. The default is NULL . |
Usage Notes
The URL passed as an argument to this function is not examined for illegal characters, such as spaces, according to URL specification RFC 2396. You should escape those characters with the UTL_URL
package to return illegal and reserved characters. URLs should consist of US-ASCII characters only. See Chapter 179, "UTL_URL" for a 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.
UTL_HTTP
.BEGIN_REQUEST
can send a URL whose length is up to 32767 bytes. However, different web servers impose different limits on the length of the URL they can accept. This limit is often about 4000 bytes. If this limit is exceeded, the outcome will depend on the web server. For example, a web server might simply drop the HTTP connection without returning a response of any kind. If this happens, a subsequent invocation of UTL_HTTP
.GET_RESPONSE
will raise the UTL_HTTP
.PROTOCOL_ERROR
exception.
A URL will be long when its QUERY_STRING
(that is, the information that follows the question mark (?)) is long. In general, it is better to send this parameterization in the body of the request using the POST
method.
req := UTL_HTTP.BEGIN_REQUEST (url=>the_url, method=>'POST'); UTL_HTTP.SET_HEADER (r => req, name => 'Content-Type', value => 'application/x-www-form-urlencoded'); UTL_HTTP.SET_HEADER (r => req, name => 'Content-Length', value =>' <length of data posted in bytes>'); UTL_HTTP.WRITE_TEXT (r => req, data => 'p1 = value1&p2=value2...'); resp := UTL_HTTP.GET_RESPONSE (r => req); ...
The programmer must determine whether a particular web server may, or may not, accept data provided in this way.
An Oracle wallet must be set before accessing Web servers over HTTPS. See the SET_WALLET
procedure on how to set up an Oracle wallet.
This procedure clears all cookies maintained by the UTL_HTTP
package.
Syntax
UTL_HTTP.CLEAR_COOKIES;
This procedure closes an HTTP persistent connection maintained by the UTL_HTTP
package in the current database session.
Syntax
UTL_HTTP.CLOSE_PERSISTENT_CONN ( conn IN connection);
Parameters
Table 168-18 CLOSE_PERSISTENT_CONN Procedure Parameters
Parameter | Description |
---|---|
conn |
The HTTP persistent connection to close |
This procedure closes a group of HTTP persistent connections maintained by the UTL_HTTP
package in the current database session. This procedure uses a pattern-match approach to decide which persistent connections to close.
To close a group of HTTP persistent connection that share a common property (for example, all connections to a particular host, or all SSL connections), set the particular parameters and leave the rest of the parameters NULL
. If a particular parameter is set to NULL
when this procedure is called, that parameter will not be used to decide which connections to close.
For example, the following call to the procedure closes all persistent connections to foobar
:
UTL_HTTP.CLOSE_PERSISTENT_CONNS(host => 'foobar');
And the following call to the procedure closes all persistent connections through the proxy www-proxy at TCP/IP port 80:
UTL_HTTP.CLOSE_PERSISTENT_CONNS(proxy_host => 'foobar', proxy_port => 80);
And the following call to the procedure closes all persistent connections:
UTL_HTTP.CLOSE_PERSISTENT_CONNS;
Syntax
UTL_HTTP.CLOSE_PERSISTENT_CONNS ( host IN VARCHAR2 DEFAULT NULL, port IN PLS_INTEGER DEFAULT NULL, proxy_host IN VARCHAR2 DEFAULT NULL, proxy_port IN PLS_INTEGER DEFAULT NULL, ssl IN BOOLEAN DEFAULT NULL);
Parameters
Table 168-19 CLOSE_PERSISTENT_CONNS Procedure Parameters
Parameter | Description |
---|---|
host |
The host for which persistent connections are to be closed |
port |
The port number for which persistent connections are to be closed |
proxy_host |
The proxy host for which persistent connections are to be closed |
proxy_port |
The proxy port for which persistent connections are to be closed |
ssl |
Close persistent SSL connection |
Usage Notes
Connections to the same Web server at different TCP/IP ports are counted individually. The host names of the Web servers are identified as specified in the URL of the original HTTP requests. Therefore, fully qualified host names with domain names will be counted differently from the host names without domain names.
Note that the use of a NULL
value in a parameter when this procedure is called means that the caller does not care about its value when the package decides which persistent connection to close. If you want a NULL
value in a parameter to match only a NULL
value of the parameter of a persistent connection (which is when you want to close a specific persistent connection), you should use the CLOSE_PERSISTENT_CONN
procedure that closes a specific persistent connection.
This procedure ends the HTTP request. To terminate the HTTP request without completing the request and waiting for the response, the program can call this procedure. Otherwise, the program should go through the normal sequence of beginning a request, getting the response, and closing the response. The network connection will always be closed and will not be reused.
Syntax
UTL_HTTP.END_REQUEST ( r IN OUT NOCOPY req);
Parameters
This procedure ends the HTTP response. It completes the HTTP request and response. Unless HTTP 1.1 persistent connection is used in this request, the network connection is also closed.
Syntax
UTL_HTTP.END_RESPONSE ( r IN OUT NOCOPY resp);
Parameters
This procedure retrieves the HTTP authentication information needed for the request to be accepted by the Web server as indicated in the HTTP response header.
Syntax
UTL_HTTP.GET_AUTHENTICATION( r IN OUT NOCOPY resp, scheme OUT VARCHAR2, realm OUT VARCHAR2, for_proxy IN BOOLEAN DEFAULT FALSE);
Parameters
Table 168-22 GET_AUTHENTICATION Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP response |
scheme |
The scheme for the required HTTP authentication |
realm |
The realm for the required HTTP authentication |
for_proxy |
Returns the HTTP authentication information required for the access to the HTTP proxy server instead of the Web server? Default is FALSE |
Usage Notes
When a Web client is unaware that a document is protected, at least two HTTP requests are required for the document to be retrieved. In the first HTTP request, the Web client makes the request without supplying required authentication information; so the request is denied. The Web client can determine the authentication information required for the request to be authorized by calling GET_AUTHENTICATION
. The Web client makes the second request and supplies the required authentication information with SET_AUTHORIZATION
. If the authentication information can be verified by the Web server, the request will succeed and the requested document is returned. Before making the request, if the Web client knows that authentication information is required, it can supply the required authentication information in the first request, thus saving an extra request.
This procedure retrieves the default character set of the body of all future HTTP requests.
Syntax
UTL_HTTP.GET_BODY_CHARSET ( charset OUT NOCOPY VARCHAR2);
Parameters
Table 168-23 GET_BODY_CHARSET Procedure Parameters
Parameter | Description |
---|---|
charset |
The default character set of the body of all future HTTP requests |
This function returns the number of cookies currently maintained by the UTL_HTTP
package set by all Web servers.
Syntax
UTL_HTTP.GET_COOKIE_COUNT RETURN PLS_INTEGER;
This procedure retrieves the current cookie support settings.
Syntax
UTL_HTTP.GET_COOKIE_SUPPORT ( enable OUT BOOLEAN, max_cookies OUT PLS_INTEGER, max_cookies_per_site OUT PLS_INTEGER);
Parameters
Table 168-24 GET_COOKIE SUPPORT Procedure Parameters
Parameter | Description |
---|---|
enable |
Indicates whether future HTTP requests should support HTTP cookies (TRUE ) or not (FALSE ) |
max_cookies |
Indicates the maximum total number of cookies maintained in the current session |
max_cookies_per_site |
Indicates the maximum number of cookies maintained in the current session for each Web site |
This function returns all the cookies currently maintained by the UTL_HTTP
package set by all Web servers.
Syntax
UTL_HTTP.GET_COOKIES ( cookies IN OUT NOCOPY cookie_table);
Parameters
This procedure checks if the UTL_HTTP
package will raise a detailed exception or not.
Syntax
UTL_HTTP.GET_DETAILED_EXCP_SUPPORT ( enable OUT BOOLEAN);
Parameters
Table 168-26 GET_DETAILED_EXCP_SUPPORT Procedure Parameters
Parameter | Description |
---|---|
enable |
TRUE if UTL_HTTP raises a detailed exception; otherwise FALSE |
This function retrieves the detailed SQLCODE
of the last exception raised.
Syntax
UTL_HTTP.GET_DETAILED_SQLCODE RETURN PLS_INTEGER;
This function retrieves the detailed SQLERRM
of the last exception raised.
Syntax
UTL_HTTP.GET_DETAILED_SQLERRM RETURN VARCHAR2;
This procedure retrieves the follow-redirect setting in the current session
Syntax
UTL_HTTP.GET_FOLLOW_REDIRECT ( max_redirects OUT PLS_INTEGER);
Parameters
Table 168-27 GET_FOLLOW_REDIRECT Procedure Parameters
Parameter | Description |
---|---|
max_redirects |
The maximum number of redirections for all future HTTP requests |
This procedure returns the nth HTTP response header name and value returned in the response.
Syntax
UTL_HTTP.GET_HEADER ( r IN OUT NOCOPY resp, n IN PLS_INTEGER, name OUT NOCOPY VARCHAR2, value OUT NOCOPY VARCHAR2);
Parameters
Table 168-28 GET_HEADER Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP response |
n |
The nth header to return |
name |
The name of the HTTP response header |
value |
The value of the HTTP response header |
Usage Notes
If the response body returned by the remote Web server is encoded in chunked transfer encoding format, the trailer headers that are returned at the end of the response body will be added to the response, and the response header count will be updated. You can retrieve the additional headers after the end of the response body is reached and before you end the response.
This procedure returns the HTTP response header value returned in the response given the name of the header.
Syntax
UTL_HTTP.GET_HEADER_BY_NAME( r IN OUT NOCOPY resp, name IN VARCHAR2, value OUT NOCOPY VARCHAR2, n IN PLS_INTEGER DEFAULT 1);
Parameters
Table 168-29 GET_HEADER_BY_NAME Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP response |
name |
The name of the HTTP response header for which the value is to return |
value |
The value of the HTTP response header |
n |
The nth occurrence of an HTTP response header by the specified name to return. The default is 1. |
Usage Notes
If the response body returned by the remote Web server is encoded in chunked transfer encoding format, the trailer headers that are returned at the end of the response body will be added to the response, and the response header count will be updated. You can retrieve the additional headers after the end of the response body is reached and before you end the response.
This function returns the number of HTTP response headers returned in the response.
Syntax
UTL_HTTP.GET_HEADER_COUNT ( r IN OUT NOCOPY resp) RETURN PLS_INTEGER;
Parameters
Usage Notes
If the response body returned by the remote Web server is encoded in chunked transfer encoding format, the trailer headers that are returned at the end of the response body will be added to the response, and the response header count will be updated. You can retrieve the additional headers after the end of the response body is reached and before you end the response.
This function returns the number of network connections currently kept persistent by the UTL_HTTP
package to the Web servers.
Syntax
UTL_HTTP.GET_PERSISTENT_CONN_COUNT RETURN PLS_INTEGER;
Usage Notes
Connections to the same Web server at different TCP/IP ports are counted individually. The host names of the Web servers are identified as specified in the URL of the original HTTP requests. Therefore, fully qualified host names with domain names will be counted differently from the host names without domain names.
This procedure checks:
If the persistent connection support is enabled
Gets the maximum number of persistent connections in the current session
Syntax
UTL_HTTP.GET_PERSISTENT_CONN_SUPPORT ( enable OUT BOOLEAN, max_conns OUT PLS_INTEGER);
Parameters
Table 168-31 GET_PERSISTENT_CONN_SUPPORT Procedure Parameters
Parameter | Description |
---|---|
enable |
TRUE if persistent connection support is enabled; otherwise FALSE |
max_conns |
the maximum number of persistent connections maintained in the current session |
This procedure returns all the network connections currently kept persistent by the UTL_HTTP
package to the Web servers.
Syntax
UTL_HTTP.get_persistent_conns ( connections IN OUT NOCOPY connection_table);
Parameters
Table 168-32 GET_PERSISTENT_CONNS Procedure Parameters
Parameter | Description |
---|---|
connections |
The network connections kept persistent |
Usage Notes
Connections to the same Web server at different TCP/IP ports are counted individually. The host names of the Web servers are identified as specified in the URL of the original HTTP requests. Therefore, fully qualified host names with domain names will be counted differently from the host names without domain names.
This procedure retrieves the current proxy settings.
Syntax
UTL_HTTP.GET_PROXY ( proxy OUT NOCOPY VARCHAR2, no_proxy_domains OUT NOCOPY VARCHAR2);
Parameters
Table 168-33 GET_PROXY Procedure Parameters
Parameter | Description |
---|---|
proxy |
The proxy (host and an optional port number) currently used by the UTL_HTTP package |
no_proxy_domains |
The list of hosts and domains for which no proxy is used for all requests |
This function reads the HTTP response. When the function returns, the status line and the HTTP response headers have been read and processed. The status code, reason phrase, and the HTTP protocol version are stored in the response record. This function completes the HTTP headers section.
Syntax
UTL_HTTP.GET_RESPONSE ( r IN OUT NOCOPY req) RETURN resp;
Parameters
This procedure checks if the response error check is set or not.
Syntax
UTL_HTTP.GET_RESPONSE_ERROR_CHECK ( enable OUT BOOLEAN);
Parameters
Table 168-35 GET_RESPONSE_ERROR_CHECK Procedure Parameters
Parameter | Description |
---|---|
enable |
TRUE if the response error check is set; otherwise FALSE |
This procedure retrieves the default timeout value for all future HTTP requests.
Syntax
UTL_HTTP.GET_TRANSFER_TIMEOUT ( timeout OUT PLS_INTEGER);
Parameters
Table 168-36 GET_TRANSFER_TIMEOUT Procedure Parameters
Parameter | Description |
---|---|
timeout |
The network transfer timeout value in seconds |
This procedure reads the HTTP response body in text form until the end of line is reached and returns the output in the caller-supplied buffer. The end of line is as defined in the function read_line
of UTL_TCP. The end_of_body
exception will be raised if the end of the HTTP response body is reached. Text data is automatically converted from the response body character set to the database character set.
Syntax
UTL_HTTP.READ_LINE( r IN OUT NOCOPY resp, data OUT NOCOPY VARCHAR2 CHARACTER SET ANY_CS, remove_crlf IN BOOLEAN DEFAULT FALSE);
Parameters
Table 168-37 READ_LINE Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP response |
data |
The HTTP response body in text form |
remove_crlf |
Removes the newline characters if set to TRUE |
Usage Notes
The UTL_HTTP
package supports HTTP 1.1 chunked transfer-encoding. When the response body is returned in chunked transfer-encoding format as indicated in the response header, the package automatically decodes the chunks and returns the response body in de-chunked format.
If transfer timeout is set in the request of this response, read_line
waits for each data packet to be ready to read until timeout occurs. If it occurs, this procedure stops reading and returns all the data read successfully. If no data is read successfully, the transfer_timeout
exception is raised. The exception can be handled and the read operation can be retried later.
If a partial multibyte character is found at the end of the response body, read_line
stops reading and returns all the complete multibyte characters read successfully. If no complete character is read successfully, the partial_multibyte_char
exception is raised. The exception can be handled and the bytes of that partial multibyte character can be read as binary by the read_raw
procedure. If a partial multibyte character is seen in the middle of the response body because the remaining bytes of the character have not arrived and read timeout occurs, the transfer_timeout
exception is raised instead. The exception can be handled and the read operation can be retried later.
When the "Content-Type" response header specifies the character set of the response body and the character set is unknown or unsupported by Oracle, the "ORA-01482: unsupported character set" exception is raised if you try to read the response body as text. You can either read the response body as binary using the READ_RAW
procedure, or set the character set of the response body explicitly using the SET_BODY_CHARSET
procedure and read the response body as text again.
This procedure reads the HTTP response body in binary form and returns the output in the caller-supplied buffer. The end_of_body
exception will be raised if the end of the HTTP response body is reached.
Syntax
UTL_HTTP.READ_RAW( r IN OUT NOCOPY resp, data OUT NOCOPY RAW, len IN PLS_INTEGER DEFAULT NULL);
Parameters
Table 168-38 READ_RAW Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP response |
data |
The HTTP response body in binary form |
len |
The number of bytes of data to read. If len is NULL , this procedure will read as much input as possible to fill the buffer allocated in data . The actual amount of data returned may be less than that specified if not much data is available before the end of the HTTP response body is reached or the transfer_timeout amount of time has elapsed. The default is NULL |
Usage Notes
The UTL_HTTP
package supports HTTP 1.1 chunked transfer-encoding. When the response body is returned in chunked transfer-encoding format as indicated in the response header, the package automatically decodes the chunks and returns the response body in de-chunked format.
If transfer timeout is set in the request of this response, read_raw
waits for each data packet to be ready to read until timeout occurs. If it occurs, read_raw
stops reading and returns all the data read successfully. If no data is read successfully, the transfer_timeout
exception is raised. The exception can be handled and the read operation can be retried later.
This procedure reads the HTTP response body in text form and returns the output in the caller-supplied buffer. The end_of_body
exception will be raised if the end of the HTTP response body is reached. Text data is automatically converted from the response body character set to the database character set.
Syntax
UTL_HTTP.READ_TEXT( r IN OUT NOCOPY resp, data OUT NOCOPY VARCHAR2 CHARACTER SET ANY_CS, len IN PLS_INTEGER DEFAULT NULL);
Parameters
Table 168-39 READ_TEXT Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP response |
data |
The HTTP response body in text form |
len |
The maximum number of characters of data to read. If len is NULL, this procedure will read as much input as possible to fill the buffer allocated in data . The actual amount of data returned may be less than that specified if little data is available before the end of the HTTP response body is reached or the transfer_timeout amount of time has elapsed. The default is NULL. |
Usage Notes
The UTL_HTTP
package supports HTTP 1.1 chunked transfer-encoding. When the response body is returned in chunked transfer-encoding format as indicated in the response header, the package automatically decodes the chunks and returns the response body in de-chunked format.
If transfer timeout is set in the request of this response, read_text
waits for each data packet to be ready to read until timeout occurs. If it occurs, this procedure stops reading and returns all the data read successfully. If no data is read successfully, the transfer_timeout
exception is raised. The exception can be handled and the read operation can be retried later.
If a partial multibyte character is found at the end of the response body, read_text
stops reading and returns all the complete multibyte characters read successfully. If no complete character is read successfully, the partial_multibyte_char
exception is raised. The exception can be handled and the bytes of that partial multibyte character can be read as binary by the read_raw
procedure. If a partial multibyte character is seen in the middle of the response body because the remaining bytes of the character have not arrived and read timeout occurs, the transfer_timeout
exception is raised instead. The exception can be handled and the read operation can be retried later.
When the "Content-Type" response header specifies the character set of the response body and the character set is unknown or unsupported by Oracle, the "ORA-01482: unsupported character set
" exception is raised if you try to read the response body as text. You can either read the response body as binary using the READ_RAW
procedure, or set the character set of the response body explicitly using the SET_BODY_CHARSET
procedure and read the response body as text again.
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. The URL may contain the username and password needed to authenticate the request to the server. The format is
scheme://[user[:password]@]host[:port]/[...]
You can define a username/password for the proxy to be specified in the proxy string. The format is
[http://][user[:password]@]host[:port][/]
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 168-40 REQUEST Function Parameters
Parameter | Description |
---|---|
url |
Uniform 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 |
wallet_password |
(Optional) Specifies the password required to open the wallet |
Return Values
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, according to 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>
Examples
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;
This function returns a PL/SQL table of 2000-byte pieces of the data retrieved from the given URL. You can define a username/password for the proxy to be specified in the proxy string. The format is
[http://][user[:password]@]host[:port][/]
Syntax
TYPE html_pieces IS TABLE OF VARCHAR2(2000) INDEX BY BINARY_INTEGER; UTL_HTTP.REQUEST_PIECES ( url IN VARCHAR2, max_pieces IN NATURAL DEFAULT 32767, proxy IN VARCHAR2 DEFAULT NULL, wallet_path IN VARCHAR2 DEFAULT NULL, wallet_password IN VARCHAR2 DEFAULT NULL) RETURN html_pieces;
Pragmas
PRAGMA RESTRICT_REFERENCES (request_pieces, WNDS, RNDS, WNPS, RNPS);
Parameters
Table 168-41 REQUEST_PIECES Function Parameters
Parameter | Description |
---|---|
url |
Uniform resource locator |
max_pieces |
(Optional) The maximum number of pieces (each 2000 characters in length, except for the last, which may be shorter), that REQUEST_PIECES should return. If provided, then that argument should be a positive integer. |
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, See |
wallet_password |
(Optional) Specifies the password required to open the wallet |
Return Values
REQUEST_PIECES
returns a PL/SQL table of type UTL_HTTP
.HTML_PIECES
. Each element of that PL/SQL table is a string of maximum length 2000. The elements of the PL/SQL table returned by REQUEST_PIECES
are successive pieces of the data obtained from the HTTP request to that URL.
Exceptions
INIT_FAILED REQUEST_FAILED
Usage Notes
The URL passed as an argument to this function will not be examined for illegal characters, for example, spaces, according to 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.
Each entry of the PL/SQL table (the "pieces") returned by this function may not be filled to their fullest capacity. The function may start filling the data in the next piece before the previous "piece" is totally full.
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>
Examples
SET SERVEROUTPUT ON DECLARE x UTL_HTTP.HTML_PIECES; len PLS_INTEGER; BEGIN x := UTL_HTTP.REQUEST_PIECES('http://www.oracle.com/', 100); DBMS_OUTPUT.PUT_LINE(x.count || ' pieces were retrieved.'); DBMS_OUTPUT.PUT_LINE('with total length '); IF x.count < 1 THEN DBMS_OUTPUT.PUT_LINE('0'); ELSE len := 0; FOR i in 1..x.count LOOP len := len + length(x(i)); END LOOP; DBMS_OUTPUT.PUT_LINE(i); END IF; END; / -- Output Statement processed. 4 pieces were retrieved. with total length 7687
This procedure sets HTTP authentication information in the HTTP request header. The Web server needs this information to authorize the request.
Syntax
UTL_HTTP.SET_AUTHENTICATION( r IN OUT NOCOPY req, username IN VARCHAR2, password IN VARCHAR2, scheme IN VARCHAR2 DEFAULT 'Basic', for_proxy IN BOOLEAN DEFAULT FALSE);
Parameters
Table 168-42 SET_AUTHENTICATION Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP request |
username |
The username for the HTTP authentication |
password |
The password for the HTTP authentication |
scheme |
The HTTP authentication scheme. The default, BASIC , denotes the HTTP Basic Authentication scheme. |
for_proxy |
Identifies if the HTTP authentication information is for access to the HTTP proxy server instead of the Web server. Default is FALSE . |
Usage Notes
Only the HTTP Basic Authentication scheme is supported.
This procedure is overloaded. The description of different functionality is located alongside the syntax declarations.
See Also:
Syntax
Sets the default character set of the body of all future HTTP requests when the media type is text
and the character set is not specified in the Content-Type
header. Following the HTTP protocol standard specification, if the media type of a request or a response is text
, but the character set information is missing in the Content-Type
header, the character set of the request or response body should default to ISO-8859-1
. A response created for a request inherits the default body character set of the request instead of the body character set of the current session. The default body character set is ISO-8859-1 in a database user session. The default body character set setting affects only future requests and has no effect on existing requests. After a request is created, the body character set can be changed by using the other SET_BODY_CHARSET
procedure that operates on a request:
UTL_HTTP.SET_BODY_CHARSET ( charset IN VARCHAR2 DEFAULT NULL);
Sets the character set of the request body when the media type is text
but the character set is not specified in the Content-Type
header. According to the HTTP protocol standard specification, if the media type of a request or a response is "text" but the character set information is missing in the Content-Type
header, the character set of the request or response body should default to "ISO-8859-1
". Use this procedure to change the default body character set a request inherits from the session default setting:
UTL_HTTP.SET_BODY_CHARSET( r IN OUT NOCOPY req, charset IN VARCHAR2 DEFAULT NULL);
Sets the character set of the response body when the media type is "text" but the character set is not specified in the "Content-Type" header. For each the HTTP protocol standard specification, if the media type of a request or a response is "text" but the character set information is missing in the "Content-Type" header, the character set of the request or response body should default to "ISO-8859-1". Use this procedure to change the default body character set a response inherits from the request:
UTL_HTTP.SET_BODY_CHARSET( r IN OUT NOCOPY resp, charset IN VARCHAR2 DEFAULT NULL);
Parameters
Table 168-43 SET_BODY_CHARSET Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP response. |
charset |
The default character set of the response body. The character set can be in Oracle or Internet Assigned Numbers Authority (IANA) naming convention. If charset is NULL , the database character set is assumed. |
This procedure is overloaded. The description of different functionality is located alongside the syntax declarations.
This procedure
See Also:
Syntax
Enables or disables support for the HTTP cookies in the request. Use this procedure to change the cookie support setting a request inherits from the session default setting:
UTL_HTTP.SET_COOKIE_SUPPORT( r IN OUT NOCOPY REQ, enable IN BOOLEAN DEFAULT TRUE);
Sets whether or not future HTTP requests will support HTTP cookies, and the maximum number of cookies maintained in the current database user session:
UTL_HTTP.SET_COOKIE_SUPPORT ( enable IN BOOLEAN, max_cookies IN PLS_INTEGER DEFAULT 300, max_cookies_per_site IN PLS_INTEGER DEFAULT 20);
Parameters
Table 168-44 SET_COOKIE_SUPPORT Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP request |
enable |
Set enable to TRUE to enable HTTP cookie support; FALSE to disable |
max_cookies |
Sets the maximum total number of cookies maintained in the current session |
max_cookies_per_site |
Sets the maximum number of cookies maintained in the current session for each Web site |
Usage Notes
If cookie support is enabled for an HTTP request, all cookies saved in the current session and applicable to the request are returned to the Web server in the request in accordance with HTTP cookie specification standards. Cookies set in the response to the request are saved in the current session for return to the Web server in the subsequent requests if cookie support is enabled for those requests. If the cookie support is disabled for an HTTP request, no cookies are returned to the Web server in the request and the cookies set in the response to the request are not saved in the current session, although the Set-Cookie
HTTP headers can still be retrieved from the response.
Cookie support is enabled by default for all HTTP requests in a database user session. The default setting of the cookie support (enabled versus disabled) affects only the future requests and has no effect on the existing ones. After your request is created, the cookie support setting may be changed by using the other SET_COOKIE_SUPPORT
procedure that operates on a request.
The default maximum number of cookies saved in the current session is 20 for each site and 300 total.
If you lower the maximum total number of cookies or the maximum number of cookies for each Web site, the oldest cookies will be purged first to reduce the number of cookies to the lowered maximum. HTTP cookies saved in the current session last for the duration of the database session only; there is no persistent storage for the cookies. Cookies saved in the current session are not cleared if you disable cookie support.
See "Examples" for how to use GET_COOKIES
and ADD_COOKIES
to retrieve, save, and restore cookies.
This procedure sets the UTL_HTTP
package to raise a detailed exception. By default, UTL_HTTP
raises the request_failed
exception when an HTTP request fails. Use GET_DETAILED_SQLCODE
and GET_DETAILED_SQLEERM
for more detailed information about the error.
Syntax
UTL_HTTP.SET_DETAILED_EXCP_SUPPORT ( enable IN BOOLEAN DEFAULT FALSE);
Parameters
Table 168-45 SET_DETAILED_EXCP_SUPPORT Procedure Parameters
Parameter | Description |
---|---|
enable |
Asks UTL_HTTP to raise a detailed exception directly if set to TRUE ; otherwise FALSE |
This procedure sets the maximum number of times UTL_HTTP
follows the HTTP redirect instruction in the HTTP response to this request, or future requests, in the GET_RESPONSE
function.
See Also:
Syntax
Use this procedure to set the maximum number of redirections:
UTL_HTTP.SET_FOLLOW_REDIRECT ( max_redirects IN PLS_INTEGER DEFAULT 3);
Use this procedure to change the maximum number of redirections a request inherits from the session default setting:
UTL_HTTP.SET_FOLLOW_REDIRECT( r IN OUT NOCOPY req, max_redirects IN PLS_INTEGER DEFAULT 3);
Parameters
Table 168-46 SET_FOLLOW_REDIRECT Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP request |
max_redirects |
The maximum number of redirects. Set to zero to disable redirects. |
Usage Notes
If max_redirects
is set to a positive number, the GET_RESPONSE Function will automatically follow the redirected URL for the HTTP response status code 301, 302, and 307 for the HTTP HEAD and GET methods, and 303 for all HTTP methods, and retry the HTTP request (the request method will be changed to HTTP GET for the status code 303) at the new location. It follows the redirection until the final, non-redirect location is reached, or an error occurs, or the maximum number of redirections has been reached (to prevent an infinite loop). The URL and method fields in the REQ
record will be updated to the last redirected URL and the method used to access the URL. Set the maximum number of redirects to zero to disable automatic redirection.
While it is set not to follow redirect automatically in the current session, it is possible to specify individual HTTP requests to follow redirect instructions the function FOLLOW_REDIRECT
and vice versa.
The default maximum number of redirections in a database user session is 3. The default value affects only future requests and has no effect on existing requests.
The SET_FOLLOW_REDIRECT
procedure must be called before GET_RESPONSE
for any redirection to take effect.
This procedure sets an HTTP request header. The request header is sent to the Web server as soon as it is set.
Syntax
UTL_HTTP.SET_HEADER ( r IN OUT NOCOPY req, name IN VARCHAR2, value IN VARCHAR2);
Parameters
Table 168-47 SET_HEADER Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP request |
name |
The name of the HTTP request header |
value |
The value of the HTTP request header |
Usage Notes
Multiple HTTP headers with the same name are allowed in the HTTP protocol standard. Therefore, setting a header does not replace a prior header with the same name.
If the request is made using HTTP 1.1, UTL_HTTP
sets the Host header automatically for you.
When you set the Content-Type header with this procedure, UTL_HTTP
looks for the character set information in the header value. If the character set information is present, it is set as the character set of the request body. It can be overridden later by using the SET_BODY_CHARSET
procedure.
When you set the Transfer-Encoding header with the value chunked,
UTL_HTTP
automatically encodes the request body written by the WRITE_TEXT, WRITE_LINE
and WRITE_RAW
procedures.
Note that some HTTP-1.1-based Web servers or CGI programs do not support or accept the request body encoding in the HTTP 1.1 chunked transfer-encoding format.
This procedure enables or disables support for the HTTP 1.1 persistent-connection in the request.
Syntax
UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT( r IN OUT NOCOPY req, enable IN BOOLEAN DEFAULT FALSE);
Parameters
Table 168-48 SET_PERSISTENT_CONN_SUPPORT Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP request |
enable |
TRUE to keep the network connection persistent. FALSE otherwise. |
Usage Notes
If the persistent-connection support is enabled for an HTTP request, the package will keep the network connections to a Web server or the proxy server open in the package after the request is completed properly for a subsequent request to the same server to reuse for each HTTP 1.1 protocol specification. With the persistent connection support, subsequent HTTP requests may be completed faster because the network connection latency is avoided. If the persistent-connection support is disabled for a request, the package will always send the HTTP header "Connection: close" automatically in the HTTP request and close the network connection when the request is completed. This setting has no effect on HTTP requests that follows HTTP 1.0 protocol, for which the network connections will always be closed after the requests are completed.
When a request is being made, the package attempts to reuse an existing persistent connection to the target Web server (or proxy server) if one is available. If none is available, a new network connection will be initiated. The persistent-connection support setting for a request affects only whether the network connection should be closed after a request completes.
Use this procedure to change the persistent-connection support setting a request inherits from the session default setting.
Users should note that while the use of persistent connections in UTL_HTTP
may reduce the time it takes to fetch multiple Web pages from the same server, it consumes precious system resources (network connections) in the database server. Also, excessive use of persistent connections may reduce the scalability of the database server when too many network connections are kept open in the database server. Network connections should be kept open only if they will be used immediately by subsequent requests and should be closed immediately when they are no longer needed. Set the default persistent connection support as disabled in the session, and enable persistent connection in individual HTTP requests as shown in "Examples".
The default value of the maximum number of persistent connections in a database session is zero. To truly enable persistent connections, you must also set the maximum number of persistent connections to a positive value or no connections will be kept persistent.
Examples
Using SET_PERSISTENT_CONN_SUPPORT in HTTP Requests
DECLARE TYPE vc2_table IS TABLE OF VARCHAR2(256) INDEX BY BINARY_INTEGER; paths VC2_TABLE; UTL_HTTP.fetch_pages(paths IN vc2_table) AS url_prefix VARCHAR2(256) := 'http://www.my-company.com/'; req UTL_HTTP.REQ; resp UTL_HTTP.RESP; data VARCHAR2(1024); BEGIN FOR i IN 1..paths.count LOOP req := UTL_HTTP.BEGIN_REQUEST(url_prefix || paths(i)); -- Use persistent connection except for the last request IF (i < paths.count) THEN UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(req, TRUE); END IF; resp := UTL_HTTP.GET_RESPONSE(req); BEGIN LOOP UTL_HTTP.READ_TEXT(resp, data); -- do something with the data END LOOP; EXCEPTION WHEN UTL_HTTP.END_OF_BODY THEN NULL; END; UTL_HTTP.END_RESPONSE(resp); END LOOP; END; BEGIN UTL_HTTP.SET_PERSISTENT_CONN_SUPPORT(FALSE, 1); paths(1) := '...'; paths(2) := '...'; ... fetch_pages(paths); END;
This procedure sets the proxy to be used for requests of the HTTP or other protocols, excluding those for hosts that belong to the domain specified in no_proxy_domains.no_proxy_domains
is a comma-, semi-colon-, or space-separated list of domains or hosts for which HTTP requests should be sent directly to the destination HTTP server instead of going through a proxy server.
Syntax
UTL_HTTP.SET_PROXY ( proxy IN VARCHAR2, no_proxy_domains IN VARCHAR2);
Parameters
Table 168-49 SET_PROXY Procedure Parameters
Parameter | Description |
---|---|
proxy |
The proxy (host and an optional port number) to be used by the UTL_HTTP package |
no_proxy_domains |
The list of hosts and domains for which no proxy should be used for all requests |
Usage Notes
The proxy may include an optional TCP/IP port number at which the proxy server listens. The syntax is [http://]host[:port][/]
, for example, www-proxy.my-company.com:80
. If the port is not specified for the proxy, port 80 is assumed.
Optionally, a port number can be specified for each domain or host. If the port number is specified, the no-proxy restriction is only applied to the request at the port of the particular domain or host, for example, corp.my-company.com, eng.my-company.com:80
. When no_proxy_domains
is NULL
and the proxy is set, all requests go through the proxy. When the proxy is not set, UTL_HTTP
sends requests to the target Web servers directly.
You can define a username/password for the proxy to be specified in the proxy string. The format is
[http://][user[:password]@]host[:port][/]
If proxy settings are set when the database server instance is started, the proxy settings in the environment variables http_proxy
and no_proxy
are assumed. Proxy settings set by this procedure override the initial settings.
This procedure sets whether or not GET_RESPONSE
raises an exception when the Web server returns a status code that indicates an error—a status code in the 4xx or 5xx ranges. For example, when the requested URL is not found in the destination Web server, a 404 (document not found) response status code is returned.
Syntax
UTL_HTTP.SET_RESPONSE_ERROR_CHECK ( enable IN BOOLEAN DEFAULT FALSE);
Parameters
Table 168-50 SET_RESPONSE_ERROR_CHECK Procedure Parameters
Parameter | Description |
---|---|
enable |
TRUE to check for response errors; otherwise FALSE |
Usage Notes
If the status code indicates an error—a 4xx or 5xx code—and this procedure is enabled, GET_RESPONSE
will raise the HTTP_CLIENT_ERROR
or HTTP_SERVER_ERROR
exception. If SET_RESPONSE_ERROR_CHECK
is set to FALSE
, GET_RESPONSE
will not raise an exception when the status code indicates an error.
Response error check is turned off by default.
The GET_RESPONSE
function can raise other exceptions when SET_RESPONSE_ERROR_CHECK
is set to FALSE
.
This procedure sets the default time out value for all future HTTP requests that the UTL_HTTP
package should attempt while reading the HTTP response from the Web server or proxy server. This time out value may be used to avoid the PL/SQL programs from being blocked by busy Web servers or heavy network traffic while retrieving Web pages from the Web servers.
Syntax
UTL_HTTP.SET_TRANSFER_TIMEOUT ( timeout IN PLS_INTEGER DEFAULT 60);
Parameters
Table 168-51 SET_TRANSFER_TIMEOUT Procedure Parameters
Parameter | Description |
---|---|
timeout |
The network transfer timeout value in seconds. |
Usage Notes
The default value of the time out is 60 seconds.
This procedure sets the Oracle wallet used for all HTTP requests over Secured Socket Layer (SSL), namely HTTPS. When the UTL_HTTP
package communicates with an HTTP server over SSL, the HTTP server presents its digital certificate, which is signed by a certificate authority, to the UTL_HTTP
package for identification purpose. The Oracle wallet contains the list of certificate authorities that are trusted by the user of the UTL_HTTP
package. An Oracle wallet is required to make an HTTPS request.
Syntax
UTL_HTTP.SET_WALLET ( path IN VARCHAR2, password IN VARCHAR2 DEFAULT NULL);
Parameters
Table 168-52 SET_WALLET Procedure Parameters
Parameter | Description |
---|---|
path |
The directory path that contains the Oracle wallet. The format is file:<directory-path> .
The format of wallet_path on a PC is, for example, |
password |
The password needed to open the wallet. A second copy of a wallet in a wallet directory that may be opened without a password. That second copy of the wallet is read-only. If the password is NULL , the UTL_HTTP package will open the second, read-only copy of the wallet instead. |
Usage Notes
To set up an Oracle wallet, use the Oracle Wallet Manager to create a wallet. In order for the HTTPS request to succeed, the certificate authority that signs the certificate of the remote HTTPS Web server must be a trust point set in the wallet.
When a wallet is created, it is populated with a set of well-known certificate authorities as trust points. If the certificate authority that signs the certificate of the remote HTTPS Web server is not among the trust points, or the certificate authority has new root certificates, you should obtain the root certificate of that certificate authority and install it as a trust point in the wallet using Oracle Wallet Manager
See Also:
Oracle Database Advanced Security Administrator's Guide for more information on Wallet ManagerThis procedure writes a text line in the HTTP request body and ends the line with new-line characters (CRLF as defined in UTL_TCP
). As soon as some data is sent as the HTTP request body, the HTTP request headers section is completed. Text data is automatically converted from the database character set to the request body character set.
Syntax
UTL_HTTP.WRITE_LINE( r IN OUT NOCOPY req, data IN VARCHAR2 CHARACTER SET ANY_CS);
Parameters
Table 168-53 WRITE_LINE Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP request |
data |
The text line to send in the HTTP request body |
Usage Notes
An HTTP client must always let the remote Web server know the length of the request body it is sending. If the amount of data is known beforehand, you can set the Content-Length header in the request, where the length of the content is measured in bytes instead of characters. If the length of the request body is not known beforehand, you can send the request body using the HTTP 1.1 chunked transfer-encoding format. The request body is sent in chunks, where the length of each chunk is sent before the chunk is sent. The UTL_HTTP
package performs chunked transfer-encoding on the request body transparently when the Transfer-Encoding: chunked header is set. Note that some HTTP-1.1-based Web servers or CGI programs do not support or accept the request body encoding in the HTTP 1.1 chunked transfer-encoding format. See the SET_HEADER
procedure for details.
If you send the Content-Length header, you should note that the length specified in the header should be the byte-length of the textual request body after it is converted from the database character set to the request body character set. When either one of the two character sets is a multibyte character set, the precise byte-length of the request body in the request body character set cannot be known beforehand. In this case, you can perform the character set conversion explicitly, determine the byte-length of the results, send the Content-Length header, and the results using the WRITE_RAW
procedure to avoid the automatic character set conversion. Or, if the remove Web server or CGI programs allow, you can send the request body using the HTTP 1.1 chunked transfer-encoding format, where UTL_HTTP
handles the length of the chunks transparently.
This procedure writes some binary data in the HTTP request body. As soon as some data is sent as the HTTP request body, the HTTP request headers section is completed.
Syntax
UTL_HTTP.WRITE_RAW( r IN OUT NOCOPY REQ, data IN RAW);
Parameters
Table 168-54 WRITE_RAW Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP request |
data |
The binary data to send in the HTTP request body |
Usage Notes
An HTTP client must always let the remote Web server know the length of the request body it is sending. If the amount of data is known beforehand, you can set the Content-Length header in the request, where the length of the content is measured in bytes instead of characters. If the length of the request body is not known beforehand, you can send the request body using the HTTP 1.1 chunked transfer-encoding format. The request body is sent in chunks, where the length of each chunk is sent before the chunk is sent. UTL_HTTP
performs chunked transfer-encoding on the request body transparently when the Transfer-Encoding:chunked
header is set. Note that some HTTP-1.1-based Web servers or CGI programs do not support or accept the request body encoding in the HTTP 1.1 chunked transfer-encoding format. See the SET_HEADER
procedure for details.
This procedure writes some text data in the HTTP request body. As soon as some data is sent as the HTTP request body, the HTTP request headers section is completed. Text data is automatically converted from the database character set to the request body character set.
Syntax
UTL_HTTP.WRITE_TEXT( r IN OUT NOCOPY REQ, data IN VARCHAR2 CHARACTER SET ANY_CS);
Parameters
Table 168-55 WRITE_TEXT Procedure Parameters
Parameter | Description |
---|---|
r |
The HTTP request |
data |
The text data to send in the HTTP request body |
Usage Notes
An HTTP client must always let the remote Web server know the length of the request body it is sending. If the amount of data is known beforehand, you can set the Content-Length header in the request, where the length of the content is measured in bytes instead of characters. If the length of the request body is not known beforehand, you can send the request body using the HTTP 1.1 chunked transfer-encoding format. The request body is sent in chunks, where the length of each chunk is sent before the chunk is sent. UTL_HTTP
performs chunked transfer-encoding on the request body transparently when the Transfer-Encoding: chunked
header is set. Note that some HTTP-1.1-based Web servers or CGI programs do not support or accept the request body encoding in the HTTP 1.1 chunked transfer-encoding format. See the SET_HEADER
procedure for details.
If you send the Content-Length header, you should note that the length specified in the header should be the byte-length of the textual request body after it is converted from the database character set to the request body character set. When either one of the two character sets is a multibyte character set, the precise byte-length of the request body in the request body character set cannot be known beforehand. In this case, you can perform the character set conversion explicitly, determine the byte-length of the results, send the Content-Length header, and the results using the WRITE_RAW
procedure to avoid the automatic character set conversion. Or, if the remove Web server or CGI programs allow, you can send the request body using the HTTP 1.1 chunked transfer-encoding format, where UTL_HTTP
handles the length of the chunks transparently.