创建向 HTTP 服务器发出 HTTP 或 SOAP 请求的用户定义的 Web 客户端过程。
CREATE [ OR REPLACE ] PROCEDURE [ owner.]procedure-name ( [ parameter, ... ] ) [ RESULT ( attribute-column-name datatype, value-column-name datatype ) ] URL url-string [ TYPE { http-type-spec-string | soap-type-spec-string } ] [ HEADER header-string ] [ CERTIFICATE certificate-string ] [ CLIENTPORT clientport-string ] [ PROXY proxy-string ] [ SET protocol-option-string ] [ SOAPHEADER soap-header-string ] [ NAMESPACE namespace-string ]
http-type-spec-string : HTTP[: { GET | POST[:MIME-type ] | PUT[:MIME-type ] | DELETE | HEAD } ]
soap-type-spec-string : SOAP[:{ RPC | DOC }
parameter :
parameter-mode parameter-name data-type [ DEFAULT expression ]
parameter-mode : IN | OUT | INOUT
url-string : { HTTP | HTTPS | HTTPS_FIPS }://[user:password@]hostname[:port][/path]
protocol-option-string
[ http-option-list]
[, soap-option-list ]
http-option-list : HTTP( [ CH[UNK]={ ON | OFF | AUTO } ] [; VER[SION]={ 1.0 | 1.1 } ] )
soap-option-list : SOAP(OP[ERATION]=soap-operation-name)
您可创建或替换 Web 服务客户端过程。可使用 PROC 作为 PROCEDURE 的同义词。
对于 SOAP 请求,缺省情况下,将过程名用作 SOAP 操作名。有关详细信息,请参见 SET 子句。
您无法创建 TEMPORARY Web 服务过程。
OR REPLACE 子句 指定 OR REPLACE 将创建一个新过程或替换同名的现有过程。此子句将更改过程的定义,但保留现有权限。如果尝试替换已使用的过程,则将返回错误。
参数 参数名必须符合其它数据库标识符(如列名)的规则。它们必须是有效的 SQL 数据类型。
仅 SOAP 请求支持传输划分了类型的数据,如 FLOAT、INT 等等。HTTP 请求仅支持传输字符串,因此您只能使用 CHAR 类型。
使用 CALL 语句执行过程时,不需要指定所有参数。如果在 CREATE PROCEDURE 语句中提供了缺省值,缺少的参数会被分配缺省值。如果 CALL 语句中既未提供参数也未设置缺省值,则会给出错误。
参数可以使用关键字 IN、OUT 或 INOUT 作为前缀。如果未指定上述任何值,则缺省情况下将使用 INOUT 参数。这些关键字具有以下含义:
IN 此参数是一个为过程提供值的表达式。
OUT 此参数是一个可由过程赋值的变量。
INOUT 此参数是一个为过程提供值的变量,并且可由过程赋值。
RESULT 子句 必须提供 RESULT 子句才能使用 SELECT 语句中的过程。RESULT 子句必须返回两列。第一列包含 HTTP 响应标头、状态和响应主体属性,而第二列包含这些属性的值。RESULT 子句必须指定双字符数据类型。例如,VARCHAR 或 LONG VARCHAR。如果未指定 RESULT 子句,缺省列名将为 Attribute 和 Value,其数据类型为 LONG VARCHAR。
URL 子句 指定 Web 服务的 URI。其中的用户名和口令参数是可选的,它们提供了一种用于提供 HTTP 基本验证所需的证书的方法。HTTP 基本验证对用户和口令信息进行基于 64 位的编码,并在 HTTP 请求的验证标头中传递它。当以这种方式进行指定时,会以未加密形式将用户名和口令作为 URL 的一部分进行传递。
对于 HTTP:GET 类型的过程,查询函数除了从传递到某个过程的参数自动生成以外,还可以在 URL 子句中指定。
URL 'http://localhost/service?parm=1 |
TYPE 子句 指定创建 Web 服务请求时使用的格式。指定 SOAP 时或不包括任何 TYPE 子句时使用 SOAP:RPC。指定 HTTP 时使用 HTTP:POST。
TYPE 子句允许 HTTP:GET、HTTP:POST 和 HTTP:PUT 类型的 MIME 类型说明。MIME 类型说明用于设置 Content-Type 请求标头并设置操作模式以只允许单个调用参数填充请求的主体。处理完参数替换后进行 Web 服务存储过程调用时,只能保留零个或一个参数。调用具有 NULL 值或无参数的 Web 服务过程(替代后)将导致无主体的请求和内容长度为零。参数名和值(允许多个参数)在 HTTP 请求的主体内进行 URL 编码。
一些典型 MIME 类型包括:
TYPE 子句的关键字具有以下含义:
'HTTP:GET' 缺省情况下,此类型使用 application/x-www-form-urlencoded MIME 类型编码 URL 中指定的参数。
例如,客户端提交来自 URL http://localhost/WebServiceName?arg1=param1&arg2=param2
的请求时,产生如下请求:
GET /WebServiceName?arg1=param1&arg2=param2 HTTP/1.1 // <End of Request - NO BODY> |
'HTTP:POST' 缺省情况下,此类型使用 application/x-www-form-urlencoded MIME 类型编码 POST 请求主体中指定的参数。URL 参数存储在请求的主体中。
例如,客户端提交来自 URL http://localhost/WebServiceName?arg1=param1&arg2=param2
的请求时,产生如下请求:
POST /WebServiceName HTTP/1.1 Content-Type: application/x-www-form-urlencoded Content-Length: 19 arg1=param1&arg2=param2 // <End of Request> |
HTTP:PUT HTTP:PUT 与 HTTP:POST 类似,但 HTTP:PUT 类型没有缺省的媒体类型。
以下示例演示了如何配置通用客户端过程,该过程将数据上载到运行 %SQLANYSAMP12%\SQLAnywhere\HTTP\put_data.sql 示例的 SQL Anywhere 服务器:
ALTER PROCEDURE CPUT("data" LONG VARCHAR, resnm LONG VARCHAR, mediatype LONG VARCHAR) URL 'http://localhost/resource/!resnm' TYPE 'HTTP:PUT:!mediatype'; CALL CPUT('hello world', 'hello', 'text/plain' ); |
HTTP:DELETE 可配置 Web 服务客户端过程为删除位于服务器上的资源。将媒体类型指定为可选的。
以下示例演示了如何配置通用客户端过程,该过程从运行 put_data.sql 示例的 SQL Anywhere 服务器删除资源:
ALTER PROCEDURE CDEL(resnm LONG VARCHAR, mediatype LONG VARCHAR) URL 'http://localhost/resource/!resnm' TYPE 'HTTP:DELETE:!mediatype'; CALL CDEL('hello', 'text/plain' ); |
HTTP:HEAD 该 Head 方法与 GET 方法完全相同,不过服务器不会返回主体。可指定媒体类型。
ALTER PROCEDURE CHEAD(resnm LONG VARCHAR) URL 'http://localhost/resource/!resnm' TYPE 'HTTP:HEAD'; CALL CHEAD( 'hello' ); |
'SOAP:RPC' 此类型将 Content-Type 标头设置为 'text/xml'。SOAP 操作和参数封装在 SOAP 包络 XML 文档中。
'SOAP:DOC' 此类型将 Content-Type 标头设置为 'text/xml'。它类似于 SOAP:RPC 类型,但允许发送更丰富的数据类型。SOAP 操作和参数封装在 SOAP 包络 XML 文档中。
指定 TYPE 子句的 MIME 类型会自动设置该 MIME 类型的 Content-Type 标头。
HEADER 子句 创建 HTTP Web 服务客户端过程时,此子句用于添加、修改或删除 HTTP 请求标头条目。标头说明与 RFC2616 超文本传输协议—HTTP/1.1 中指定的格式,以及用于 ARPA Internet 文本消息的 RFC822 标准极其相似,其中包括只能为 HTTP 标头指定可打印的 ASCII 字符,且这些字符不区分大小写这一事实。
标头可定义为 header-name:value-name 对。由于标头与标头值之间必须用冒号 (:) 分隔,因此标头中不能包含冒号。通过使用 \n、\x0d\n、<LF>(换行符)或 <CR><LF>(回车符后跟换行符)分隔每个对,可以定义多个标头。
标头内的多个连续空格会转换为一个空格。
CERTIFICATE 子句 要创建安全 (HTTPS) 请求,客户端必须有权访问 HTTPS 服务器所用的证书。必要的信息在一个用分号分隔的键/值对字符串中指定。可以使用 file 键指定证书的文件名称,也可以使用 certificate 键在字符串中指定服务器证书。不能同时指定 file 和 certificate 键。可以使用以下键:
按键 | 缩写 | 说明 |
---|---|---|
file | 证书的文件名。 | |
certificate | cert | 证书本身。 |
company | co | 证书中指定的公司。 |
unit | 证书中指定的公司单位。 | |
name | 证书中指定的公用名。 |
只有被定向到 HTTPS 服务器的请求或可从非安全服务器重定向到安全服务器的请求才需要证书。仅支持 PEM 格式的证书。
CLIENTPORT 子句 标识 HTTP 客户端过程使用 TCP/IP 进行通信的端口号。该子句是为通过防火墙的连接提供的,并建议只用于此类连接,因为防火墙过滤 "外发" TCP/IP 连接。您可以指定单个端口号、端口号范围或是两者的组合;例如 CLIENTPORT '85,90-97'。
PROXY 子句 指定代理服务器的 URI。在客户端必须通过代理访问网络时使用。指示过程将要连接到代理服务器,并通过它将请求发送到 Web 服务。
SET 子句 指定 HTTP 和 SOAP 的协议特定行为选项。以下列表介绍了受支持的 SET 选项。CHUNK 和 VERSION 适用于 HTTP 协议,而 OPERATION 适用于 SOAP 协议。
'HTTP(CH[UNK]=option)' (HTTP 或 SOAP)此选项可用于指定是否使用分块。分块可将 HTTP 消息拆分为几个部分。可能的值是 ON(始终分块)、OFF(从不分块) 和 AUTO(仅在内容超过 8196 字节时分块,自动生成的标记除外)。例如,以下 SET 子句可启用分块:
SET 'HTTP(CHUNK=ON)' |
如果未指定 CHUNK 选项,缺省行为是 AUTO。如果分块请求在 AUTO 模式中失败,状态为 505(HTTP 版本不受支持
)、501(未实现
)或 411(必需的长度
),则客户端将重试该请求但不使用分块传输编码。
如果 HTTP 服务器不支持分块传输编码请求,将 CHUNK 选项设置为 OFF(从不分块)。
由于 CHUNK 模式从 HTTP 1.1 版开始支持传输编码,将 CHUNK 设置为 ON 需要将版本 (VER) 设置为 1.1,或根本不设置,在后一种情况下,1.1 将作为缺省版本使用。
' HTTP(VER[SION]=ver)' (HTTP 或 SOAP)此选项可指定用于 HTTP 消息格式的 HTTP 协议的版本。例如,以下 SET 子句将 HTTP 版本设置为 1.1:
SET 'HTTP(VERSION=1.1)' |
可能的值是 1.0 和 1.1。如果未指定 VERSION:
如果将 CHUNK 设置为 ON,1.1 将作为 HTTP 版本使用
如果将 CHUNK 设置为 OFF,1.0 将作为 HTTP 版本使用
如果将 CHUNK 设置为 AUTO,会使用 1.0 或 1.1,这取决于客户端是否在 CHUNK 模式下发送
'REDIR(COUNT=count, STATUS=status-list)' (HTTP 或 SOAP)HTTP 响应状态代码(例如 302 Found 和 303 See Other)用来将 Web 应用程序重定向到新的 URI,尤其是在执行 HTTP POST 后。例如,客户端请求可以是:
GET /people/alice HTTP/1.1 Host: www.example.com Accept: text/html, application/xhtml+xml Accept-Language: en, de |
Web 服务器响应可以是:
HTTP/1.1 302 Found Location: http://www.example.com/people/alice.en.html |
作为响应,客户端会发送另一个 HTTP 请求给新 URI。REDIR 选项允许您控制允许的最大重定向数以及要自动重定向哪种 HTTP 响应状态代码。
例如,SET 'REDIR(count=3, status=301,307)'
最多允许 3 个重定向并允许 301 和 307 状态的重定向。如果接收到其它重定向状态代码之一(例如 302 或 303),会发出一条错误消息 (SQLCODE -983)。
缺省重定向限制 count 为 5。缺省情况下,HTTP 客户端过程会自动重定向所有 HTTP 状态代码 (301、302、303、307)。要禁止重定向状态代码,请使用 SET REDIR(COUNT=0)
。在此模式下,重定向响应不会导致错误 (SQLCODE -983)。相反,结果集会与 HTTP 状态和响应标头一同被返回。这允许调用程序根据包含在 Location 标头中的 URI 按条件重新发出请求。
指定 POST HTTP 方法(此方法将接收 303 See Other 状态)的 Web 服务过程会使用 GET HTTP 方法发出重定向请求。
Location 标头可以包含绝对路径或相对路径。HTTP 客户端过程会处理这二者。标头也可以包括查询参数,这些参数会被转发到重定向的位置。例如,如果标头包含如下所示的参数,则后续 GET 或 POST 也会包括这些参数。
Location: alternate_service?a=1&b=2 |
在上面的示例中,查询参数是 a=1&b=2
。
' SOAP(OP[ERATION]=soap-operation-name) (仅 SOAP)如果 SOAP 操作的名称与您正在创建的过程的名称不同,此选项可用于指定 SOAP 操作的名称。OPERATION 的值类似于远程过程调用的名称。例如,如果想要创建过程 accounts_login,此过程调用名为 login 的 SOAP 操作,则您需要按如下方式指定一些东西:
CREATE PROCEDURE accounts_login( name LONG VARCHAR, pwd LONG VARCHAR ) SET 'SOAP(OPERATION=login)' |
如果未指定 OPERATION 选项,SOAP 操作的名称必须与正在创建的过程的名称匹配。
以下语句显示了几个 protocol-option 设置在同一 SET 子句中是如何组合的:
CREATE PROCEDURE accounts_login( name LONG VARCHAR, pwd LONG VARCHAR ) SET 'HTTP ( CHUNK=ON; VERSION=1.1 ), SOAP( OPERATION=login )' ... |
SOAPHEADER 子句 (仅 SOAP 格式)当将 SOAP Web 服务声明为过程时,此子句用于指定一个或多个 SOAP 请求标头条目。SOAP 标头可声明为静态常量,也可使用参数替代机制动态设置(为参数 hd1、hd2 等声明 IN、OUT 或 INOUT 参数)。Web 服务过程可定义一个或多个 IN 模式替代参数,以及单个 INOUT 或 OUT 替代参数。
以下示例说明了客户端如何能够使用参数替换指定发送多个标头条目,以及如何接收响应 SOAP 标头数据:
CREATE PROCEDURE soap_client (INOUT hd1 LONG VARCHAR, IN hd2 LONG VARCHAR, IN hd3 LONG VARCHAR) URL 'localhost/some_endpoint' SOAPHEADER '!hd1!hd2!hd3'; |
NAMESPACE 子句 (仅 SOAP 格式)此子句标识 SOAP:RPC 和 SOAP:DOC 请求通常都需要的方法命名空间。处理请求的 SOAP 服务器使用此命名空间来解释 SOAP 请求消息主体中的实体名称。可以通过 Web 服务服务器,从 SOAP 服务的 WSDL(Web Services Description Language,Web 服务描述语言)中获取命名空间。缺省值是过程的 URL,但是不包括可选的路径组件。
参数值将作为请求的一部分进行传递。使用的语法取决于请求的类型。对于 HTTP:GET,参数将作为 URL 的一部分进行传递;对于 HTTP:POST 请求,则将值放在请求主体中。SOAP 请求的参数总是被绑定在请求主体中。
必须具有 RESOURCE 特权。
必须有 DBA 特权才能为其他用户创建过程。
自动提交。
SQL/2008 服务商扩充。
Transact-SQL 不受 Adaptive Server Enterprise 支持。
以下示例创建一个名为 FtoC 的 Web 服务客户端过程。
CREATE PROCEDURE FtoC( IN temperature FLOAT, INOUT inoutheader LONG VARCHAR, IN inheader LONG VARCHAR ) URL 'http://localhost:8082/FtoCService' TYPE 'SOAP:DOC' SOAPHEADER '!inoutheader!inheader'; |
![]() |
使用DocCommentXchange讨论此页。
|
版权 © 2012, iAnywhere Solutions, Inc. - SQL Anywhere 12.0.1 |