UTL_HTTP 包

UTL_HTTP 包提供了通过 HTTP 协议获取网页内容的功能。

在发起 HTTP 请求和读取 HTTP 响应消息的过程中,各函数的调用顺序如下图所示。

UTL_HTTP 包中函数使用顺序图.jpg

图36.1 HTTP请求/响应消息相关函数使用顺序图

REQUEST 函数和 SET_TRANSFER_TIMEOUT 过程不参与上述使用顺序图。REQUEST 函数相当于上图中各函数的缺省配置,最终返回指定网页的前 2000 个字节。用户可在任意时刻调用 SET_TRANSFER_TIMEOUT 过程,以设置当前会话后续所有 HTTP 相关连接的超时时长。

另外,达梦支持基于 HTTP 1.1 协议的持久连接功能,与该功能相关的所有过程及函数也不参与上述使用顺序图,用户可在任意时刻调用相关过程或函数,以对当前会话的持久连接进行相应设置。

36.1 相关方法

下面对各个函数和过程进行详细说明。

  1. REQ

定义 REQ 为 RECORD 类型,用来存放请求消息。

语法如下:

TYPE REQ IS RECORD (
	URL           		VARCHAR2(32767),
	METHOD        		VARCHAR2(64),
	HTTP_VERSION  		VARCHAR2(64)
);

参数详解

  • url web 服务器的 url 地址。url 中可以包含用户名密码。
  • method 对指定 url 发起的操作命令。 常见的命令有 get、post,默认为 Get。
  • http_version
    http 协议版本号,UTL_HTTP 包提供 1.0 和 1.1 两个版本宏定义,若此参数设为 NULL,则默认使用最新的 http 协议版本。此参数默认为 NULL。
  1. RESP

定义 RESP 为 RECORD 类型,用来存放响应消息。

语法如下:

TYPE RESP IS RECORD (
	STATUS_CODE			PLS_INTEGER,
   	REASON_PHRASE  		VARCHAR2(256),
   	HTTP_VERSION   		VARCHAR2(64)
);

参数详解

  • STATUS_CODE web 服务器返回的状态码。
  • REASON_PHRASE 关于状态码的简单文本描述。
  • HTTP_VERSION http 协议版本号,UTL_HTTP 包提供 1.0 和 1.1 两个版本宏定义,若此参数设为 NULL,则默认使用最新的 http 协议版本。此参数默认为 NULL。
  1. CONNECTION

定义 CONNECTION 为 RECORD 类型,用来存放 HTTP 请求完成后的持久连接信息。

语法如下:

TYPE CONNECTION IS RECORD (
	HOST         		VARCHAR2(256), 
	PORT         		INTEGER, 
	PROXY_HOST  		VARCHAR2(256), 
    PROXY_PORT  		INTEGER,
    SSL           	BOOLEAN
);

参数详解

  • HOST WEB 服务器 IP 地址。
  • PORT WEB 服务器端口号。
  • PROXY_HOST WEB 服务器代理 IP 地址,保留参数。
  • PROXY_PORT WEB 服务器代理端口号,保留参数。
  • SSL 是否使用 SSL,保留参数。
  1. CONNECTION_TABLE

定义 CONNECTION_TABLE 为 CONNECTION 的索引表类型,用来存放所有持久连接相关信息。

语法如下:

TYPE CONNECTION_TABLE IS TABLE OF CONNECTION INDEX BY BINARY_INTEGER;
  1. BEGIN_REQUEST

用于发起一个新的 http 请求。单个会话若调用 BEGIN_REQUEST 后未调用 END_REQUEST 结束,则最多同时发起 5 个 http 请求。

语法如下:

FUNCTION 	BEGIN_REQUEST (
   	URL               	IN  		VARCHAR2,
  	METHOD            	IN  		VARCHAR2				DEFAULT 'GET',
   	HTTP_VERSION      	IN  		VARCHAR2				DEFAULT NULL,
   	REQUEST_CONTEXT   	IN  		REQUEST_CONTEXT_KEY		DEFAULT NULL
)RETURN REQ;

参数详解

  • url web 服务器的 url 地址。url 中可以包含用户名密码。
  • method 对指定 url 发起的操作命令。
  • http_version http 协议版本号,UTL_HTTP 包提供 1.0 和 1.1 两个版本宏定义,若此参数设为 NULL,则默认使用最新的 http 协议版本。此参数默认为 NULL。
  • request_context 目前达梦不支持此参数,仅用作兼容参数。

返回值

HTTP 请求消息。

  1. END_REQUEST

用于结束 http 请求。

语法如下:

PROCEDURE END_REQUEST (
	R		IN OUT		NOCOPY REQ
);

参数详解

  • R http 请求句柄。
  1. GET_RESPONSE

用于读取 http 响应消息。

语法如下:

FUNCTION GET_RESPONSE (

	R		IN OUT		NOCOPY REQ

) RETURN RESP;

参数详解

  • R http 请求消息。

返回值

HTTP 请求句柄。

  1. END_RESPONSE

用于结束 http 响应操作。

语法如下:

PROCEDURE END_RESPONSE (
	R  		IN OUT 		NOCOPY RESP
);

参数详解

  • R http 响应句柄。
  1. WRITE_TEXT

用于向 http 请求 body 中填写数据。

语法如下:

PROCEDURE WRITE_TEXT(
   	R     	IN OUT 		NOCOPY REQ,
	DATA  	IN          VARCHAR2 CHARACTER SET ANY_CS
);

参数详解

  • R http 请求消息。
  • DATA 准备向 body 写入的数据。
  1. READ_TEXT

用于读取 http 响应消息中 body 的内容并将内容输出到指定的缓冲区中。body 中的数据将自动转换成数据库所指定的字符集。

语法如下:

PROCEDURE READ_TEXT(
   	R     	IN OUT 		NOCOPY RESP,
	DATA  	OUT 		NOCOPY VARCHAR2 CHARACTER SET ANY_CS,
   	LEN   	IN 			PLS_INTEGER DEFAULT NULL
);

参数详解

  • R http 请求消息。
  • DATA 读取 body 中的数据。
  • LEN 请求读取的数据长度。
  1. READ_RAW

用于读取 http 响应消息中 body 的内容并将内容输出到指定的缓冲区中。不对 body 中的数据进行字符集转码操作。

语法如下:

PROCEDURE READ_RAW(
   	R     	IN OUT 		NOCOPY RESP,
	DATA  	OUT 		NOCOPY VARBINARY,
   	LEN   	IN 			PLS_INTEGER DEFAULT NULL
);

参数详解

  • R http 请求消息。
  • DATA 读取 body 中的数据。
  • LEN 请求读取的数据长度。
  1. READ_LINE

用于按行读取 http 响应消息中 body 的内容并将内容输出到指定的缓冲区中。body 中的数据将自动转换成数据库所指定的字符集。

语法如下:

PROCEDURE READ_LINE(
   	R			 	IN OUT 		NOCOPY RESP,
	DATA		 	OUT 		NOCOPY VARCHAR2,
   	REMOVE_CRLF	 	IN 			BOOLEAN DEFAULT FALSE
);

参数详解

  • R http 请求消息。
  • DATA 读取 body 中的数据。
  • REMOVE_CRLF 读取的数据是否去除换行标识,默认不去除。
  1. SET_HEADER

用于设置 http 请求的头信息。设置头信息的请求将被立即发送到 web 服务器。

语法如下:

PROCEDURE SET_HEADER (
   	R      		IN OUT 		NOCOPY REQ,
   	NAME   		IN 			VARCHAR2,
	VALUE  		IN 			VARCHAR2
);

参数详解

  • R http 请求消息。
  • NAME header 中请求设置的属性名。
  • VALUE header 中请求设置的属性值。
  1. GET_HEADER

用于获取 http 响应头信息。过程将响应头中的第 n 个属性名及属性值返回。

语法如下:

PROCEDURE GET_HEADER (
   	R      		IN OUT 		NOCOPY RESP,
   	N      		IN 			PLS_INTEGER,
   	NAME   		OUT 			NOCOPY VARCHAR2,
	VALUE  		OUT 			NOCOPY VARCHAR2
);

参数详解

  • R http 响应消息。
  • N header 中的第 n 个属性。
  • NAME 属性名。
  • VALUE 属性值。
  1. SET_BODY_CHARSET

用于设置 body 的字符集,至于是请求还是响应消息中的 body,则需要看上下文。

语法如下:

PROCEDURE SET_BODY_CHARSET (
	CHARSET  	IN 			VARCHAR2 DEFAULT NULL
);

或者

PROCEDURE SET_BODY_CHARSET(
   	R        		IN OUT 		NOCOPY REQ,
	CHARSET  		IN 			VARCHAR2 DEFAULT NULL
);

或者

PROCEDURE SET_BODY_CHARSET(
   	R        		IN OUT 		NOCOPY RESP,
	CHARSET  		IN 			VARCHAR2 DEFAULT NULL
);

参数详解

  • R http 请求(或响应)句柄。
  • CHARSET 字符集名称。
  1. SET_AUTHENTICATION

用于设置 http 请求消息中的权限。WEB 服务器需要这些权限信息用于授权访问。

语法如下:

PROCEDURE SET_AUTHENTICATION(
   	R         	IN OUT 		NOCOPY REQ,
	USERNAME  	IN 			VARCHAR2,
	PASSWORD  	IN 			VARCHAR2,
   	SCHEME    	IN 			VARCHAR2 DEFAULT 'BASIC',
  	FOR_PROXY 	IN 			BOOLEAN DEFAULT FALSE
);

参数详解

  • R http 请求消息。
  • USENAME web 服务器端所需的用户名。
  • PASSWORD web 服务器端所需的密码。
  • SCHEME 访问模式,仅支持"basic"。
  • FOR_PROXY 是否通过代理来访问 web,默认为 FALSE。
  1. GET_AUTHENTICATION

从 http 响应消息中获取 WEB 服务器所需要的授权信息。

语法如下:

PROCEDURE GET_AUTHENTICATION(
   	R          	IN OUT 		NOCOPY RESP,
   	SCHEME     	OUT 		VARCHAR2,
   	REALM      	OUT 		VARCHAR2,
   	FOR_PROXY  	IN 			BOOLEAN  DEFAULT FALSE
);

参数详解

  • R http 响应消息。
  • SCHEME web 服务器的授权模式。
  • REALM web 服务器需要授权的区域。
  • FOR_PROXY 是否返回访问代理所需的权限而不是 WEB 服务器的权限,默认 FALSE。
  1. REQUEST

返回网页的前 2000 个字节。该函数可以直接用在 SQL 查询中。

语法如下:

FUNCTION 	REQUEST (
   	URL			IN  			VARCHAR2   
)RETURN REQ;

参数详解

  • url web 服务器的 url 地址。url 中可以包含用户名密码。

返回值

返回网页的前 2000 个字节。

  1. SET_TRANSFER_TIMEOUT

设置当前会话后续所有 http 相关连接的超时时长。

语法如下:

PROCEDURE SET_TRANSFER_TIMEOUT(
   	TIMEOUT		IN 		INT 		DEFAULT 60
);

参数详解

  • TIMEOUT 超时时长,若 http 连接超过该时长未响应,则报错:传输超时。单位为秒,取值范围为 1~2147483647,缺省为 60。
  1. SET_PERSISTENT_CONN_SUPPORT

打开或关闭当前会话/当前请求的持久连接功能。

语法如下:

PROCEDURE SET_PERSISTENT_CONN_SUPPORT (
	ENABLE    	IN 			BOOLEAN,
  	MAX_CONNS 	IN 			INTEGER 			DEFAULT 0
);

或者

PROCEDURE SET_PERSISTENT_CONN_SUPPORT(
    R      		IN OUT 		NOCOPY 	REQ,
	ENABLE 		IN     		BOOLEAN 			DEFAULT FALSE
);

参数详解

  • ENABLE 是否打开持久连接功能。
  • MAX_CONNS 持久连接个数的最大值。
  • R HTTP 请求句柄。
  1. GET_PERSISTENT_CONN_SUPPORT

获取当前会话的持久连接设置信息。

语法如下:

PROCEDURE GET_PERSISTENT_CONN_SUPPORT(
  	ENABLED   	OUT 		BOOLEAN,
  	MAX_CONNS 	OUT 		INTEGER
);

参数详解

  • ENABLED 当前会话是否已打开持久连接功能。
  • MAX_CONNS 持久连接个数的最大值。
  1. GET_PERSISTANT_CONN_COUNT

获取当前会话的持久连接个数。

语法如下:

FUNCTION GET_PERSISTENT_CONN_COUNT() RETURN INTEGER;

返回值

当前会话的持久连接个数。

  1. GET_PSERSISTANT_CONN

获取当前会话所有持久连接的相关信息。

语法如下:

PROCEDURE GET_PERSISTENT_CONNS(
	CONNECTIONS 	IN OUT 		NOCOPY CONNECTION_TABLE
);

参数详解

  • CONNECTIONS 当前会话持久连接的索引表。
  1. CLOSE_PERSISTANT_CONN

关闭指定的持久连接。

语法如下:

PROCEDURE CLOSE_PERSISTENT_CONN(
   	CONN	IN		CONNECTION  
);

参数详解

  • CONN 持久连接句柄。
  1. CLOSE_PERSISTANT_CONNS

关闭指定的持久连接或所有持久连接。

语法如下:

PROCEDURE CLOSE_PERSISTENT_CONNS(
	HOST       	IN 		VARCHAR2    	DEFAULT NULL,
  	PORT       	IN 		INTEGER 		DEFAULT NULL,
  	PROXY_HOST 	IN 		VARCHAR2    	DEFAULT NULL,
  	PROXY_PORT 	IN 		INTEGER 		DEFAULT NULL,
  	SSL        	IN 		BOOLEAN     	DEFAULT NULL
);

参数详解

  • HOST 待关闭持久连接的 IP 地址。若为 NULL,则关闭当前会话的所有持久连接。
  • PORT 待关闭持久连接的端口号。若为 NULL,则关闭指定 HOST 的所有持久连接。
  • PROXY_HOST 待关闭持久连接的代理 IP 地址,保留参数,暂时忽略。
  • PROXY_PORT 待关闭持久连接的代理端口号,保留参数,暂时忽略。
  • SSL 待关闭持久连接是否使用 SSL,保留参数,暂时忽略。

36.2 举例说明

使用包内的过程和函数之前,如果还未创建过系统包,请先调用系统过程创建系统包。

zzSP_CREATE_SYSTEM_PACKAGES (1,'UTL_HTTP');
SP_CREATE_SYSTEM_PACKAGES (1,'DBMS_OUTPUT');
SET SERVEROUTPUT ON;  //DBMS_OUTPUT.PUT_LINE需要设置这条语句,才能打印出消息

举一个使用 UTL_HTTP 包获取网页信息的例子。

declare
req utl_http.REQ; 
resp utl_http.resp; 
data varchar2(32563); 
receiveDate varchar; 
begin
req := utl_http.begin_request('http://192.168.0.104/blog/2015_06_05/CSDN_public_1433381803730.html', 'POST'); 
data := ' '; 
utl_http.write_text(req, data); 
resp := utl_http.get_response(req); 
utl_http.set_body_charset(resp, 'utf-8');
utl_http.read_text(resp, receiveDate, 1024); 
dbms_output.put_line(receiveDate); 
utl_http.end_response(resp); 
end;

输出的网页内容为:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="www.w3.org/1999/xhtml">
 <head>
  <script type="text/javascript" src="c.csdnimg.cn/pubfooter/js/tracking.js" charset="utf-8"></script>
  <script type="text/javascript">
        var protocol = window.location.protocol;
        document.write('<script type="text/javascript" src="csdnimg.cn/pubfooter/js/repoAddr2.js?v=' + Math.random() + '"></' + 'script>');
    </script>
  <script id="allmobilize" charset="utf-8" src="a.yunshipei.com/46aae4d1e2371e4aa769798941cef698/allmobilize.min.js"></script>
  <meta http-equiv="Cache-Control" content="no-siteapp">
  <link rel="alternate" media="handheld" href="#">
  <title>使用UTL_HTTP包获取网页内容 - IndexMan的专栏
        - 博客频道 - CSDN.NET</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <meta name="description" content="UTL_HTTP 包提供了容易的方式通过HTTP协议获取网页内容"> 
微信扫码
分享文档
扫一扫
联系客服