HTTP_GET 和 HTTP_GET_BLOB

HTTP_GET 开始更改或 HTTP_GET_BLOB结束更改 标量函数通过 HTTP GET 请求从指定的 URL 获取基于文本的资源。

读取语法图跳过可视语法图HTTP_GETHTTP_GET_BLOB(url ,选项)
URL
返回内置字符串或图形字符串数据类型的表达式,用于指定所访问资源的 URL。
URL 中唯一支持的协议是 http://https://. HTTP URL 中不能指定 @ 形式的基本身份验证。 https://userid:password 相反,必须使用 basicAuth 选项来指定基本身份验证的用户名和密码。
选项
返回内置字符串或图形字符串数据类型的表达式。 此字符串必须格式化为包含请求的选项 (包括头) 的 JSON 对象。 有关选项列表,请参见 HTTP 选项
如果未提供任何选项,那么将使用缺省选项。

HTTP_GET 函数的结果是包含响应消息的 CLOB (2G) CCSID 1208。 开始更改HTTP_GET_BLOB 函数的结果是包含响应消息的 BLOB (2G)。结束更改

注意

有关使用 HTTP 功能的更多信息,请参阅 HTTP 功能概述

要返回 HTTP 请求的头信息,请使用 HTTP_GET_VERBOSE 开始更改或 HTTP_GET_BLOB_VERBOSE结束更改 表函数: HTTP_GET_VERBOSE 和 HTTP_GET_BLOB_VERBOSE

示例

  • 使用从 Java™ 证书库创建的证书库从 IBM® PSP Web 站点检索服务信息。 有关更多信息,请参阅 SSL 注意事项
    VALUES QSYS2.HTTP_GET(
                 'https://www.ibm.com/support/pages/sites/default/files/inline-files/xmldoc.xml',
                 '{"sslCertificateStoreFile":"/home/javaTrustStore/fromJava.KDB"}');
    

HTTP 选项

每个 HTTP 函数都有一个参数,用于传递在请求中使用的选项。 这些选项包括 HTTP 标头的设置。 此字符串必须是以下格式的 JSON 对象:
{"option1":"option-setting1","option2":"option-setting2"}
例如,使用选项字符串开始更改
{"headers":{"User-Agent":"IBM i HTTP function"}}
结束更改 将导致
"User-Agent": "IBM i HTTP function"
将包含在发送给服务器的 HTTP 标头中。

可以在 JSON 对象中设置以下选项:

表 1. HTTP 选项
选项 可能的设置 缺省设置 描述
basicAuth 用户标识,密码   设置用于 HTTP 基本身份验证的用户名和密码。

为防止暴露用户名和密码,只有在 URL 以 https: 开头时才允许使用该选项。

connectTimeout 0-2000000 不会发生超时。 设置连接超时值。 如果超时大于零,那么该值将用作等待连接完成的最大时间 (以秒计)。
页眉 headername 和 headervalue   使用指定的 headernameheadervalue 在 HTTP 请求中设置 HTTP 头信息。

可以多次指定此选项以设置多个头。

建议使用 headers 选项而不是 header 选项。

开始更改报头结束更改 开始更改{"header1": "value1" , "header2": "value2" , "header3": "value3"}结束更改 开始更改 结束更改 开始更改在 HTTP 请求中设置一个或多个 HTTP 标头。 此设置由具有表示头名称和相应头值的键值对的 JSON 对象组成。

可能需要的公共头是 Accept 头。 可以通过以下方式设置此头: {"headers":{"Accept":"*"}}

默认情况下,所有请求只设置 Host 和 User-Agent HTTP 标头。 使用 URL 中的主机信息设置主机。 User-Agent 标头默认为 curl/XX.YY ,其中 XX.YY 是一些版本号。 选择此值是为了在访问 Web Service 时提供匿名性。

如果 POST 或 PUT 操作未设置内容类型 HTTP 标头,则将使用默认内容类型:

Content-Type: text/xml; charset=UTF-8

要正确使用这些标头,请查阅有关使用 HTTP 请求标头的相应网络服务器和 RFC 文档。 RFC 的例子有 RFC2616RFC7231.

结束更改
ioTimeout 0-2000000 不会发生超时。 设置等待读请求完成的时间长度。 如果超时大于零,那么该值将用作等待读请求完成的最大时间 (以秒计)。
代理 主机,端口   设置 HTTP 代理信息。
proxyAuth 用户标识,密码   设置 HTTP 代理身份验证信息。

为了防止显示用户标识和密码,仅当 proxySsl 选项为 true 时,才允许使用此选项。

proxySsl
true
false
true 设置在连接到代理服务器时是否应使用安全 (SSL) 连接。 值为 true 表示传输将使用安全通道连接到代理服务器。 值 false 指示传输将使用不安全的通道连接到代理服务器。
重定向 0-2000000 0 指定将遵循的 HTTP 重定向次数。 如果数字大于零, HTTP 重定向将一直跟踪到指定的数字。 如果该值小于 1,则不会遵循 HTTP 重定向。
signalErrors
true
false
false 表示是否应将 HTTP 错误作为 SQLException 发送信号。 这将被视为 SQLSTATE 38501 , SQLCODE -443。
sslCertificateStoreFile 文件
/qibm/userdata/icss/
CERT/SERVER/DEFAULT.KDB
指定要用于安全会话或 SSL 环境的证书库文件的名称。 如果 sslApplicationID 选项设置为值,那么将忽略此参数。

如果要通过使用密钥库文件的路径来完成 SSL 通信,那么运行应用程序的用户概要文件必须对该文件具有权限。

  • 对正在读取的流文件之前的每个目录执行 (*X) 数据权限
  • 对流文件的读 (*R) 数据权限

该选项仅在 URL 以 https: 开头时使用。

sslCertificateStorePassword 密码   指定要用于安全会话或 SSL 环境的证书库文件的密码。 如果该选项未传递或设置为空字符串,那么只要用户对证书库文件具有权限并且在系统上使用了一次密码,就会使用与用于运行应用程序的用户概要文件相关联的内部隐藏文件。 如果 sslApplicationID 选项设置为值,那么将忽略此选项。

该选项仅在 URL 以 https: 开头时使用。

sslCertificateLabel 标签   指定与证书库中要用于安全会话或 SSL 环境的证书相关联的标签。 如果该选项未传递或设置为空字符串,那么指定的证书库文件中的缺省证书标签将用于 SSL 环境。 如果 sslApplicationID 选项设置为值,那么将忽略此选项。

该选项仅在 URL 以 https: 开头时使用。

sslTLS11
启用

启用或禁用 TLS V 1.1 密码。 值 NONE 将禁用密码; 任何其他值将启用密码。

该选项仅在 URL 以 https: 开头时使用。

sslTLS12
启用

ENABLE 启用或禁用 TLS V 1.2 密码。 值 NONE 将禁用密码; 任何其他值将启用密码。

该选项仅在 URL 以 https: 开头时使用。

sslTLS13
启用

ENABLE 启用或禁用 TLS V 1.3 密码。 值 NONE 将禁用密码; 任何其他值将启用密码。

该选项仅在 URL 以 https: 开头时使用。

sslTolerate
true
false
false 容许软验证错误 (已到期的证书或不在证书库中的证书)。 指定值 true 以容许软验证错误,或指定 false 以容许软验证错误。

警告: 启用此选项允许发生中间人攻击,建议不要这样做。

该选项仅在 URL 以 https: 开头时使用。

sslApplicationId 标识   要用于 SSL 环境的应用程序标识。

该选项仅在 URL 以 https: 开头时使用。

sslDomainName 名称 使用 https 中的主机名设置: URL 将用作 RFC 6066 定义的服务器名称指示 (SNI) 的标准域名。

该选项仅在 URL 以 https: 开头时使用。

sslSniCritical
true
false
false 值为 true 表示 SNI 请求是关键的,因此服务器必须支持 SNI 扩展。 否则,如果服务器未发送扩展,那么安全连接将失败。 值 false 指示服务器不需要支持 SNI 扩展。

该选项仅在 URL 以 https: 开头时使用。

开始更改verboseResponseHeaderFormat 结束更改 开始更改
json
开始更改jsonCookiesArray
jsonCookiesObject结束更改

jsonString
生的
结束更改
开始更改json结束更改 开始更改指定 HTTP_xxx_VERBOSE 函数的 RESPONSE_HTTP_HEADER 列所使用的格式。
json
如果头值是有效的 JSON 值,那么会将其直接用作 JSON 值。 如果它不是有效的 JSON 值,那么会将其转换为 JSON 字符串。 通过此设置,可以将作为 JSON 头返回的任何 JSON 对象作为构造的 RESPONSE_HTTP_HEADER JSON 对象中的 JSON 值进行访问。 类似地, JSON 数字和特殊值可作为数字和特殊值进行访问。 缺点是不保留头值周围的外引号,因为这将解释为 JSON 字符串。
Cookie 将随 Set-Cookie 键一起返回。 例如,包含名为 cookie1cookie2 的 cookie 的响应在 JSON 对象中类似于以下内容:
"Set-Cookie":"cookie1=cookie1value", 
"Set-Cookie":"cookie2=cookie2value" 
开始更改jsonCookiesArray结束更改
开始更改格式类似于 json 选项,但 cookie 作为 JSON 数组中的对象返回。 例如,包含名为 cookie1cookie2 的 cookie 的响应将类似于以下内容:
"Set-Cookies": [{"cookie":"cookie1", 
                 "value":"cookie1value"},
                {"cookie":"cookie2", 
                 "value":"cookie2value"}] 
结束更改
开始更改jsonCookiesObject结束更改
开始更改头值的格式类似于 json 选项,但在 JSON 对象中使用 Set-Cookies 键返回 cookie。 对象将 cookie 作为 JSON 键,并将 cookie 的值作为 JSON 值。 例如,包含名为 cookie1cookie2 的 cookie 的响应如下所示:
"Set-Cookies": {"cookie1":"cookie1value", 
                "cookie2":"cookie2value"}
结束更改
jsonString
头值始终转换为 JSON 字符串。 如果头值包含引号,那么将在 JSON 字符串中对它们进行转义。
原始
将返回无格式的响应消息和头。
结束更改
某些选项可以公开敏感信息,例如密码。 可以使用一些最佳实践来防止在 SQL 语句文本中显示敏感信息,这可能是使用 DBMON 可见的。 以下是保护密码的一些最佳实践示例。
  1. 使用全局变量并在执行 SQL 语句时并置全局值。
    CREATE VARIABLE MYLIB.HTTP_PW VARCHAR(30); 
    SET MYLIB.HTTP_PW = 'http_pwd';
    VALUES QSYS2.HTTP_GET( 'https://www.somesite.com/authorized_info.html', '{"basicAuth":"userid,' CONCAT MYLIB.HTTP_PW CONCAT '"}' );
    
  2. 对于支持参数标记的接口,请使用参数标记来设置密码。 以下是使用 jt400.jar中提供的 JDBC 客户机的 QSHELL 示例。
    java -jar /qibm/proddata/os400/jt400/lib/java6/jt400.jar jdbc:db2:localhost
    !PREPARE select QSYS2.HTTP_GET( 'https://www.somesite.com/authorized_info.html', 
                                    '{"basicAuth":"userid,' CONCAT ? CONCAT '"}' ) from sysibm.sysdummy1
    !setParm 1,http_pwd
    !executeQuery
    
  3. 将密码存储在表中,并使用列掩码进行保护。
    CREATE MYLIB.TABLE PASSWORDS (TYPE VARCHAR(20), PWD_VALUE VARCHAR(100) CCSID 37);
    
    CREATE MASK MYLIB.PASSWORD_MASK ON MYLIB.PASSWORDS
    FOR COLUMN PWD_VALUE RETURN
    CASE WHEN (VERIFY_GROUP_FOR_USER(SESSION_USER,'<my user id>') = 1)
    THEN PWD_VALUE
    ELSE 'Sorry' END
    ENABLE;
    
    ALTER TABLE MYLIB.PASSWORDS
    ACTIVATE COLUMN ACCESS CONTROL;
    
    INSERT INTO MYLIB.PASSWORDS VALUES ('HTTP', 'My secure password');
    
    VALUES QSYS2.HTTP_GET( 'https://www.somesite.com/authorized_info.html', 
                           '{"basicAuth":"userid,' CONCAT 
                           (SELECT PWD_VALUE FROM MYLIB.PASSWORDS WHERE TYPE = 'HTTP') CONCAT 
                           '"}' );