UTL_HTTP

工作流程

使用UTL_HTTP发起一个完整的HTTP请求通常遵循以下状态化步骤：

1. 开始请求：使用UTL_HTTP.BEGIN_REQUEST函数初始化一个请求，并获取一个请求句柄（req类型）。

2. 设置请求头：调用UTL_HTTP.SET_HEADER为请求添加必要的HTTP头部信息，如Content-Type。

3. （可选）写入请求体：对于POST或PUT等请求，使用UTL_HTTP.WRITE_TEXT或UTL_HTTP.WRITE_RAW写入请求体数据。

4. 获取响应：使用UTL_HTTP.GET_RESPONSE函数发送请求并获取一个响应句柄（resp类型）。

5. 读取响应体：循环调用UTL_HTTP.READ_TEXT或UTL_HTTP.READ_LINE从响应句柄中读取返回的数据。

6. 结束响应：调用UTL_HTTP.END_RESPONSE关闭响应句柄。

核心组件

UTL_HTTP包主要由以下几部分组成，共同支撑HTTP通信：

• 请求与响应记录：

  • UTL_HTTP.REQ：代表一个HTTP请求的句柄，包含了URL、方法等信息。

  • UTL_HTTP.RESP：代表一个HTTP响应的句柄，包含了状态码、原因短语等信息。

• 核心函数与过程：用于构建请求、处理响应和配置会话行为，如BEGIN_REQUEST、SET_HEADER、GET_RESPONSE、READ_TEXT等。

• 常量：预定义了大量的HTTP协议常量，如协议版本（HTTP_VERSION_1_1）和状态码（HTTP_OK、HTTP_NOT_FOUND等），使代码更具可读性。

• 异常：定义了一套完整的异常体系，用于捕获和处理网络错误、协议错误或超时等问题，如REQUEST_FAILED、TRANSFER_TIMEOUT等。

req记录类型

表示一个HTTP请求的句柄（handle）。它在调用BEGIN_REQUEST时被创建，并作为后续请求相关过程（如SET_HEADER、WRITE_TEXT）的输入参数。

TYPE req IS RECORD (
    url          VARCHAR2(32767),
    method       VARCHAR2(64),
    http_version VARCHAR2(64),
    private_hndl INTEGER
);

字段说明

• url：请求的目标URL。

• method：请求使用的HTTP方法（如GET、POST）。

• http_version：请求使用的HTTP协议版本。

• private_hndl：供包内部使用的句柄标识，请忽略。

resp记录类型

表示一个HTTP响应的句柄。它在调用GET_RESPONSE后返回，并作为后续响应相关过程（如READ_TEXT）的输入参数。

TYPE resp IS RECORD (
    status_code   INTEGER,
    reason_phrase VARCHAR2(256),
    http_version  VARCHAR2(64),
    private_hndl  INTEGER
);

字段说明

• status_code：HTTP响应的状态码，例如200或404。

• reason_phrase：对状态码的文本描述，例如OK或Not Found。

• http_version：HTTP响应中返回的协议版本。

• private_hndl：供包内部使用的句柄标识，请忽略。

cookie记录类型

用于表示和管理一个HTTP Cookie的详细信息。

TYPE cookie IS RECORD (
    name     VARCHAR2(4096),
    value    VARCHAR2(4096),
    domain   VARCHAR2(256),
    expire   TIMESTAMP WITH TIME ZONE,
    path     VARCHAR2(1024),
    secure   BOOLEAN,
    version  INTEGER,
    comment  VARCHAR2(1024)
);

字段说明

• name：Cookie的名称。

• value：Cookie的值。

• domain：该Cookie适用的域名。

• expire：Cookie的过期时间。

• path：该Cookie适用的路径。

• secure：如果为TRUE，表示该Cookie仅通过安全的HTTPS连接发送。

• version：Cookie规范的版本。

• comment：与Cookie相关的注释信息。

其他数据类型

• html_pieces：VARCHAR2表类型，用于返回HTML片段。

• cookie_table：Cookie表类型。

• connection：表示一个持久化连接类型。

• connection_table：用于管理持久连接表类型。

• request_context_key：用于标识请求上下文。

示例1：发送简单的GET请求

这是最基础的用法，用于从一个公开的API获取数据。

DECLARE
    l_req    UTL_HTTP.req;
    l_resp   UTL_HTTP.resp;
    l_url    VARCHAR2(256) := 'https://xxx.com/get';
    l_buffer VARCHAR2(32767);
BEGIN
    -- 开始GET请求
    l_req := UTL_HTTP.begin_request(l_url, 'GET', UTL_HTTP.HTTP_VERSION_1_1);
    
    -- 获取响应
    l_resp := UTL_HTTP.get_response(l_req);
    
    -- 循环读取响应体内容
    DBMS_OUTPUT.put_line('Response Status: ' || l_resp.status_code);
    LOOP
        UTL_HTTP.read_text(l_resp, l_buffer, 32767);
        DBMS_OUTPUT.put_line(l_buffer);
    END LOOP;

EXCEPTION
    WHEN UTL_HTTP.END_OF_BODY THEN
        -- 读取完成，关闭响应
        UTL_HTTP.end_response(l_resp);
    WHEN OTHERS THEN
        DBMS_OUTPUT.put_line('Request Failed: ' || SQLERRM);
        -- 确保在异常时也关闭响应
        IF l_resp.private_hndl IS NOT NULL THEN
            UTL_HTTP.end_response(l_resp);
        END IF;
END;
/

示例2：发送带JSON体的POST请求

此示例演示如何向一个测试API发送POST请求，并在请求体中包含JSON数据。

DECLARE
    l_req      UTL_HTTP.req;
    l_resp     UTL_HTTP.resp;
    l_url      VARCHAR2(256) := 'https://xxx.com/post';
    l_body     VARCHAR2(100) := '{"name":"test", "value":123}';
    l_buffer   VARCHAR2(32767);
BEGIN
    l_req := UTL_HTTP.begin_request(l_url, 'POST', UTL_HTTP.HTTP_VERSION_1_1);

    -- 设置请求头
    UTL_HTTP.set_header(l_req, 'Content-Type', 'application/json; charset=utf-8');
    UTL_HTTP.set_header(l_req, 'Content-Length', LENGTH(l_body));

    -- 写入请求体
    UTL_HTTP.write_text(l_req, l_body);

    -- 获取并处理响应
    l_resp := UTL_HTTP.get_response(l_req);
    DBMS_OUTPUT.put_line('Response Status: ' || l_resp.status_code);
    
    LOOP
        UTL_HTTP.read_text(l_resp, l_buffer, 32767);
        DBMS_OUTPUT.put_line(l_buffer);
    END LOOP;

EXCEPTION
    WHEN UTL_HTTP.END_OF_BODY THEN
        UTL_HTTP.end_response(l_resp);
    WHEN OTHERS THEN
        DBMS_OUTPUT.put_line('Request Failed: ' || UTL_HTTP.get_detailed_sqlerrm);
        IF l_resp.private_hndl IS NOT NULL THEN
            UTL_HTTP.end_response(l_resp);
        END IF;
END;
/

常量

异常