UTL_HTTP v16
The UTL_HTTP
package provides a way to use the HTTP or HTTPS protocol to retrieve information found at a URL. EDB Postgres Advanced Server supports the following functions and procedures.
Function/procedure | Return type | Description |
---|---|---|
BEGIN_REQUEST(url, method, http_version) | UTL_HTTP.REQ | Initiates a new HTTP request. |
END_REQUEST(r IN OUT) | n/a | Ends an HTTP request before allowing it to complete. |
END_RESPONSE(r IN OUT) | n/a | Ends the HTTP response. |
END_OF_BODY(r IN OUT) | n/a | Ends package body. |
GET_BODY_CHARSET | VARCHAR2 | Returns the default character set of the body of future HTTP requests. |
GET_BODY_CHARSET(charset OUT) | n/a | Returns the default character set of the body of future HTTP requests. |
GET_FOLLOW_REDIRECT(max_redirects OUT) | n/a | Current setting for the maximum number of redirections allowed. |
GET_HEADER(r IN OUT, n, name OUT, value OUT) | n/a | Returns the nth header of the HTTP response. |
GET_HEADER_BY_NAME(r IN OUT, name, value OUT, n) | n/a | Returns the HTTP response header for the specified name. |
GET_HEADER_COUNT(r IN OUT) | INTEGER | Returns the number of HTTP response headers. |
GET_RESPONSE(r IN OUT) | UTL_HTTP.RESP | Returns the HTTP response. |
GET_RESPONSE_ERROR_CHECK(enable OUT) | n/a | Returns whether or not response error check is set. |
GET_TRANSFER_TIMEOUT(timeout OUT) | n/a | Returns the transfer timeout setting for HTTP requests. |
READ_LINE(r IN OUT, data OUT, remove_crlf) | n/a | Returns the HTTP response body in text form until the end of line. |
READ_RAW(r IN OUT, data OUT, len) | n/a | Returns the HTTP response body in binary form for a specified number of bytes. |
READ_TEXT(r IN OUT, data OUT, len) | n/a | Returns the HTTP response body in text form for a specified number of characters. |
REQUEST(url) | VARCHAR2 | Returns the content of a web page. |
REQUEST_PIECES(url, max_pieces) | UTL_HTTP. HTML_PIECES | Returns a table of 2000-byte segments retrieved from an URL. |
SET_BODY_CHARSET(charset) | n/a | Sets the default character set of the body of future HTTP requests. |
SET_FOLLOW_REDIRECT(max_redirects) | n/a | Sets the maximum number of times to follow the redirect instruction. |
SET_FOLLOW_REDIRECT(r IN OUT, max_redirects) | n/a | Sets the maximum number of times to follow the redirect instruction for an individual request. |
SET_HEADER(r IN OUT, name, value) | n/a | Sets the HTTP request header. |
SET_RESPONSE_ERROR_CHECK(enable) | n/a | Determines whether to treat HTTP 4xx and 5xx status codes as errors. |
SET_TRANSFER_TIMEOUT(timeout) | n/a | Sets the default transfer timeout value for HTTP requests. |
SET_TRANSFER_TIMEOUT(r IN OUT, timeout) | n/a | Sets the transfer timeout value for an individual HTTP request. |
WRITE_LINE(r IN OUT, data) | n/a | Writes CRLF-terminated data to the HTTP request body in TEXT form. |
WRITE_RAW(r IN OUT, data) | n/a | Writes data to the HTTP request body in BINARY form. |
WRITE_TEXT(r IN OUT, data) | n/a | Writes data to the HTTP request body in TEXT form. |
EDB Postgres Advanced Server's implementation of UTL_HTTP
is a partial implementation when compared to Oracle's version. Only the functions and procedures listed in the table are supported.
Note
In EDB Postgres Advanced Server, an HTTP 4xx
or HTTP 5xx
response produces a database error. In Oracle, you can configure this option. It is FALSE
by default.
In EDB Postgres Advanced Server, the UTL_HTTP
text interfaces expect the downloaded data to be in the database encoding. All interfaces that are currently available are text interfaces. In Oracle, the encoding is detected from HTTP headers. Without the header, the default is configurable and defaults to ISO-8859-1
.
EDB Postgres Advanced Server ignores all cookies it receives.
The UTL_HTTP
exceptions that can be raised in Oracle aren't recognized by EDB Postgres Advanced Server. In addition, the error codes returned by EDB Postgres Advanced Server aren't the same as those returned by Oracle.
UTL_HTTP exception codes
If a call to a UTL_HTTP
procedure or function raises an exception, you can use the condition name to catch the exception. The UTL_HTTP
package reports the following exception codes compatible with Oracle databases.
Exception code | Condition name | Description | Raised where |
---|---|---|---|
-29266 | END_OF_BODY | The end of HTTP response body is reached | READ_LINE, READ_RAW , and READ_TEXT functions |
To use the UTL_HTTP.END_OF_BODY
exception, first you need to run the utl_http_public.sql
file from the contrib/utl_http
directory of your installation directory.
Various public constants are available with UTL_HTTP
. These are listed in the following tables.
The following table contains UTL_HTTP
public constants defining HTTP versions and port assignments.
HTTP versions | |
---|---|
HTTP_VERSION_1_0 | CONSTANT VARCHAR2(64) := 'HTTP/1.0'; |
HTTP_VERSION_1_1 | CONSTANT VARCHAR2(64) := 'HTTP/1.1'; |
Standard port assignments | |
DEFAULT_HTTP_PORT | CONSTANT INTEGER := 80; |
DEFAULT_HTTPS_PORT | CONSTANT INTEGER := 443; |
The following table contains UTL_HTTP
public status code constants.
1XX Informational | |
---|---|
HTTP_CONTINUE | CONSTANT INTEGER := 100; |
HTTP_SWITCHING_PROTOCOLS | CONSTANT INTEGER := 101; |
HTTP_PROCESSING | CONSTANT INTEGER := 102; |
2XX success | |
HTTP_OK | CONSTANT INTEGER := 200; |
HTTP_CREATED | CONSTANT INTEGER := 201; |
HTTP_ACCEPTED | CONSTANT INTEGER := 202; |
HTTP_NON_AUTHORITATIVE_INFO | CONSTANT INTEGER := 203; |
HTTP_NO_CONTENT | CONSTANT INTEGER := 204; |
HTTP_RESET_CONTENT | CONSTANT INTEGER := 205; |
HTTP_PARTIAL_CONTENT | CONSTANT INTEGER := 206; |
HTTP_MULTI_STATUS | CONSTANT INTEGER := 207; |
HTTP_ALREADY_REPORTED | CONSTANT INTEGER := 208; |
HTTP_IM_USED | CONSTANT INTEGER := 226; |
3XX redirection | |
HTTP_MULTIPLE_CHOICES | CONSTANT INTEGER := 300; |
HTTP_MOVED_PERMANENTLY | CONSTANT INTEGER := 301; |
HTTP_FOUND | CONSTANT INTEGER := 302; |
HTTP_SEE_OTHER | CONSTANT INTEGER := 303; |
HTTP_NOT_MODIFIED | CONSTANT INTEGER := 304; |
HTTP_USE_PROXY | CONSTANT INTEGER := 305; |
HTTP_SWITCH_PROXY | CONSTANT INTEGER := 306; |
HTTP_TEMPORARY_REDIRECT | CONSTANT INTEGER := 307; |
HTTP_PERMANENT_REDIRECT | CONSTANT INTEGER := 308; |
4XX client error | |
---|---|
HTTP_BAD_REQUEST | CONSTANT INTEGER := 400; |
HTTP_UNAUTHORIZED | CONSTANT INTEGER := 401; |
HTTP_PAYMENT_REQUIRED | CONSTANT INTEGER := 402; |
HTTP_FORBIDDEN | CONSTANT INTEGER := 403; |
HTTP_NOT_FOUND | CONSTANT INTEGER := 404; |
HTTP_METHOD_NOT_ALLOWED | CONSTANT INTEGER := 405; |
HTTP_NOT_ACCEPTABLE | CONSTANT INTEGER := 406; |
HTTP_PROXY_AUTH_REQUIRED | CONSTANT INTEGER := 407; |
HTTP_REQUEST_TIME_OUT | CONSTANT INTEGER := 408; |
HTTP_CONFLICT | CONSTANT INTEGER := 409; |
HTTP_GONE | CONSTANT INTEGER := 410; |
HTTP_LENGTH_REQUIRED | CONSTANT INTEGER := 411; |
HTTP_PRECONDITION_FAILED | CONSTANT INTEGER := 412; |
HTTP_REQUEST_ENTITY_TOO_LARGE | CONSTANT INTEGER := 413; |
HTTP_REQUEST_URI_TOO_LARGE | CONSTANT INTEGER := 414; |
HTTP_UNSUPPORTED_MEDIA_TYPE | CONSTANT INTEGER := 415; |
HTTP_REQ_RANGE_NOT_SATISFIABLE | CONSTANT INTEGER := 416; |
HTTP_EXPECTATION_FAILED | CONSTANT INTEGER := 417; |
HTTP_I_AM_A_TEAPOT | CONSTANT INTEGER := 418; |
HTTP_AUTHENTICATION_TIME_OUT | CONSTANT INTEGER := 419; |
HTTP_ENHANCE_YOUR_CALM | CONSTANT INTEGER := 420; |
HTTP_UNPROCESSABLE_ENTITY | CONSTANT INTEGER := 422; |
HTTP_LOCKED | CONSTANT INTEGER := 423; |
HTTP_FAILED_DEPENDENCY | CONSTANT INTEGER := 424; |
HTTP_UNORDERED_COLLECTION | CONSTANT INTEGER := 425; |
HTTP_UPGRADE_REQUIRED | CONSTANT INTEGER := 426; |
HTTP_PRECONDITION_REQUIRED | CONSTANT INTEGER := 428; |
HTTP_TOO_MANY_REQUESTS | CONSTANT INTEGER := 429; |
HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE | CONSTANT INTEGER := 431; |
HTTP_NO_RESPONSE | CONSTANT INTEGER := 444; |
HTTP_RETRY_WITH | CONSTANT INTEGER := 449; |
HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS | CONSTANT INTEGER := 450; |
HTTP_REDIRECT | CONSTANT INTEGER := 451; |
HTTP_REQUEST_HEADER_TOO_LARGE | CONSTANT INTEGER := 494; |
HTTP_CERT_ERROR | CONSTANT INTEGER := 495; |
HTTP_NO_CERT | CONSTANT INTEGER := 496; |
HTTP_HTTP_TO_HTTPS | CONSTANT INTEGER := 497; |
HTTP_CLIENT_CLOSED_REQUEST | CONSTANT INTEGER := 499; |
5XX server error | |
---|---|
HTTP_INTERNAL_SERVER_ERROR | CONSTANT INTEGER := 500; |
HTTP_NOT_IMPLEMENTED | CONSTANT INTEGER := 501; |
HTTP_BAD_GATEWAY | CONSTANT INTEGER := 502; |
HTTP_SERVICE_UNAVAILABLE | CONSTANT INTEGER := 503; |
HTTP_GATEWAY_TIME_OUT | CONSTANT INTEGER := 504; |
HTTP_VERSION_NOT_SUPPORTED | CONSTANT INTEGER := 505; |
HTTP_VARIANT_ALSO_NEGOTIATES | CONSTANT INTEGER := 506; |
HTTP_INSUFFICIENT_STORAGE | CONSTANT INTEGER := 507; |
HTTP_LOOP_DETECTED | CONSTANT INTEGER := 508; |
HTTP_BANDWIDTH_LIMIT_EXCEEDED | CONSTANT INTEGER := 509; |
HTTP_NOT_EXTENDED | CONSTANT INTEGER := 510; |
HTTP_NETWORK_AUTHENTICATION_REQUIRED | CONSTANT INTEGER := 511; |
HTTP_NETWORK_READ_TIME_OUT_ERROR | CONSTANT INTEGER := 598; |
HTTP_NETWORK_CONNECT_TIME_OUT_ERROR | CONSTANT INTEGER := 599; |
HTML_PIECES
The UTL_HTTP
package declares a type named HTML_PIECES
, which is a table of type VARCHAR2 (2000)
indexed by BINARY INTEGER
. A value of this type is returned by the REQUEST_PIECES
function.
REQ
The REQ
record type holds information about each HTTP request.
RESP
The RESP
record type holds information about the response from each HTTP request.
BEGIN_REQUEST
The BEGIN_REQUEST
function initiates a new HTTP request. A network connection is established to the web server with the specified URL. The signature is:
The BEGIN_REQUEST
function returns a record of type UTL_HTTP.REQ
.
Parameters
url
url
is the Uniform Resource Locator from which UTL_HTTP
returns content.
method
method
is the HTTP method to use. The default is GET
.
http_version
http_version
is the HTTP protocol version sending the request. Specify either HTTP/1.0
or HTTP/1.1
. The default is null. In that case, the latest HTTP protocol version supported by the UTL_HTTP
package is used, which is 1.1.
END_REQUEST
The END_REQUEST
procedure terminates an HTTP request. Use the END_REQUEST
procedure to terminate an HTTP request without completing it and waiting for the response. The normal process is to begin the request, get the response, and then close the response. The signature is:
Parameters
r
r
is the HTTP request record.
END_RESPONSE
The END_RESPONSE
procedure terminates the HTTP response. The END_RESPONSE
procedure completes the HTTP request and response. This is the normal method to end the request and response process. The signature is:
Parameters
r
r
is the HTTP
response record.
GET_BODY_CHARSET
The GET_BODY_CHARSET
program is available in the form of both a procedure and a function. A call to GET_BODY_CHARSET
returns the default character set of the body of future HTTP requests.
The procedure signature is:
The function signature is:
This function returns a VARCHAR2
value.
Parameters
charset
charset
is the character set of the body.
Examples
This example shows the use of the GET_BODY_CHARSET
function.
GET_FOLLOW_REDIRECT
The GET_FOLLOW_REDIRECT
procedure returns the current setting for the maximum number of redirections allowed. The signature is:
Parameters
max_redirects
max_redirects
is the maximum number of redirections allowed.
GET_HEADER
The GET_HEADER
procedure returns the nth
header of the HTTP response. The signature is:
Parameters
r
r
is the HTTP response record.
n
n
is the nth
header of the HTTP response record to retrieve.
name
name
is the name of the response header.
value
value
is the value of the response header.
Examples
This example retrieves the header count and then the headers.
The following is the output from the example.
GET_HEADER_BY_NAME
The GET_HEADER_BY_NAME
procedure returns the header of the HTTP response according to the specified name. The signature is:
Parameters
r
r
is the HTTP response record.
name
name
is the name of the response header to retrieve.
value
value
is the value of the response header.
n
n
is the nth
header of the HTTP response record to retrieve according to the values specified by name
. The default is 1
.
Examples
The following example retrieves the header for Content-Type.
GET_HEADER_COUNT
The GET_HEADER_COUNT
function returns the number of HTTP response headers. The signature is:
This function returns an INTEGER
value.
Parameters
r
r
is the HTTP response record.
GET_RESPONSE
The GET_RESPONSE
function sends the network request and returns any HTTP response. The signature is:
This function returns a UTL_HTTP.RESP
record.
Parameters
r
r
is the HTTP request record.
GET_RESPONSE_ERROR_CHECK
The GET_RESPONSE_ERROR_CHECK
procedure returns whether response error check is set. The signature is:
Parameters
enable
enable
returns TRUE
if response error check is set. Otherwise it returns FALSE
.
GET_TRANSFER_TIMEOUT
The GET_TRANSFER_TIMEOUT
procedure returns the current default transfer timeout setting for HTTP requests. The signature is:
Parameters
timeout
timeout
is the transfer timeout setting in seconds.
READ_LINE
The READ_LINE
procedure returns the data from the HTTP response body in text form until the end of line is reached. A CR
character, a LF
character, a CR LF
sequence, or the end of the response body constitutes the end of line. The signature is:
Parameters
r
r
is the HTTP response record.
data
data
is the response body in text form.
remove_crlf
Set remove_crlf
to TRUE
to remove new line characters. The default is FALSE
.
Examples
This example retrieves and displays the body of the specified website.
The following is the output.
READ_RAW
The READ_RAW
procedure returns the data from the HTTP response body in binary form. The number of bytes returned is specified by the len
parameter. The signature is:
Parameters
r
r
is the HTTP response record.
data
data
is the response body in binary form.
len
Set len
to the number of bytes of data to return.
Examples
This example retrieves and displays the first 150 bytes in binary form.
The following is the output from the example.
READ_TEXT
The READ_TEXT
procedure returns the data from the HTTP response body in text form. The maximum number of characters returned is specified by the len
parameter. The signature is:
Parameters
r
r
is the HTTP response record.
data
data
is the response body in text form.
len
Set len
to the maximum number of characters to return.
Examples
This example retrieves the first 150 characters:
The following is the output:
REQUEST
The REQUEST
function returns the first 2000 bytes retrieved from a URL. The signature is:
If the data found at the URL is longer than 2000 bytes, the remainder is discarded. If the data found at the given URL is shorter than 2000 bytes, the result is shorter than 2000 bytes.
Parameters
url
url
is the Uniform Resource Locator from which UTL_HTTP
returns content.
Example
This command returns the first 2000 bytes retrieved from the EDB website:
REQUEST_PIECES
The REQUEST_PIECES
function returns a table of 2000-byte segments retrieved from a URL. The signature is:
Parameters
url
url
is the Uniform Resource Locator from which UTL_HTTP
returns content.
max_pieces
max_pieces
specifies the maximum number of 2000-byte segments that the REQUEST_PIECES
function returns. If max_pieces
specifies more units than are available at the specified URL, the final unit contains fewer bytes.
Example
This example returns the first four 2000-byte segments retrieved from the EDB website:
SET_BODY_CHARSET
The SET_BODY_CHARSET
procedure sets the default character set of the body of future HTTP requests. The signature is:
Parameters
charset
charset
is the character set of the body of future requests. The default is null, meaning the database character set is assumed.
SET_FOLLOW_REDIRECT
The SET_FOLLOW_REDIRECT
procedure sets the maximum number of times to follow the HTTP redirect instruction in the response to this request or future requests. This procedures has two signatures:
and
Use the second form to change the maximum number of redirections for an individual request that a request inherits from the session default settings.
Parameters
r
r
is the HTTP request record.
max_redirects
max_redirects
is the maximum number of redirections allowed. Set to 0
to disable redirections. The default is 3
.
SET_HEADER
The SET_HEADER
procedure sets the HTTP request header. The signature is:
Parameters
r
r
is the HTTP request record.
name
name
is the name of the request header.
value
value
is the value of the request header. The default is null.
SET_RESPONSE_ERROR_CHECK
The SET_RESPONSE_ERROR_CHECK
procedure determines whether to interpret HTTP 4xx and 5xx status codes returned by the GET_RESPONSE
function as errors. The signature is:
Parameters
enable
Set enable
to TRUE
if you want to treat HTTP 4xx and 5xx status codes as errors. The default is FALSE
.
SET_TRANSFER_TIMEOUT
The SET_TRANSFER_TIMEOUT
procedure sets the default transfer timeout setting for waiting for a response from an HTTP request. This procedure has two signatures:
and
Use the second form to change the transfer timeout setting for an individual request that a request inherits from the session default settings.
Parameters
r
r
is the HTTP request record.
timeout
timeout
is the transfer timeout setting in seconds for HTTP requests. The default is 60 seconds.
WRITE_LINE
The WRITE_LINE
procedure writes data to the HTTP request body in text form. The text is terminated with a CRLF character pair. The signature is:
Parameters
r
r
is the HTTP request record.
data
data
is the request body in TEXT
form.
Example
This example writes data (Account balance $500.00
) in text form to the request body to send using the HTTP POST
method. The data is sent to a web application that accepts and processes data (post.php
).
Assuming the web application successfully processed the POST
method, the following output is displayed:
WRITE_RAW
The WRITE_RAW
procedure writes data to the HTTP request body in binary form. The signature is:
Parameters
r
r
is the HTTP request record.
data
data
is the request body in binary form.
Example
This example writes data in binary form to the request body to send using the HTTP POST
method to a web application that accepts and processes such data.
The text string shown in the HEXTORAW
function is the hexadecimal translation of the text Testing POST method in HTTP request
.
When the web application successfully processes the POST
method, the following output is displayed:
WRITE_TEXT
The WRITE_TEXT
procedure writes data to the HTTP request body in text form. The signature is:
Parameters
r
r
is the HTTP request record.
data
data
is the request body in text form.
Example
This example writes data (Account balance $500.00
) in text form to the request body to send using the HTTP POST
method. The data is sent to a web application that accepts and processes data (post.php
).
When the web application successfully processes the POST
method, the following output is displayed:
END_OF_BODY
The END_OF_BODY
exception is raised when it reaches the end of the HTTP response body.
Example
This example handles the exception and writes Exception caught
in text form to the request body to send using the HTTP POST
method. The data is sent to a web application that accepts and processes data (post.php
).
When the web application successfully processes the POST
method, the following output is displayed:
- On this page
- UTL_HTTP exception codes
- HTML_PIECES
- REQ
- RESP
- BEGIN_REQUEST
- END_REQUEST
- END_RESPONSE
- GET_BODY_CHARSET
- GET_FOLLOW_REDIRECT
- GET_HEADER
- GET_HEADER_BY_NAME
- GET_HEADER_COUNT
- GET_RESPONSE
- GET_RESPONSE_ERROR_CHECK
- GET_TRANSFER_TIMEOUT
- READ_LINE
- READ_RAW
- READ_TEXT
- REQUEST
- REQUEST_PIECES
- SET_BODY_CHARSET
- SET_FOLLOW_REDIRECT
- SET_HEADER
- SET_RESPONSE_ERROR_CHECK
- SET_TRANSFER_TIMEOUT
- WRITE_LINE
- WRITE_RAW
- WRITE_TEXT
- END_OF_BODY