创建发出 HTTP 或 SOAP over HTTP 请求的 Web 客户端过程。要创建用户定义的 SQL 过程,请参见CREATE PROCEDURE 语句。
CREATE [ OR REPLACE ] PROCEDURE [ owner.]procedure-name ( [ parameter, ... ] ) 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)
CREATE PROCEDURE 您可创建或替换 Web 服务客户端过程。可使用 PROC 作为 PROCEDURE 的同义词。
对于 SOAP 请求,缺省情况下,将过程名用作 SOAP 操作名。有关详细信息,请参见下面的 SET 子句。
参数名必须符合其它数据库标识符(如列名)的规则。它们必须是有效的 SQL 数据类型。有关有效数据类型的列表,请参见SQL 数据类型。
仅 SOAP 请求支持传输划分了类型的数据,如 FLOAT、INT 等等。HTTP 请求仅支持传输字符串,因此您只能使用 CHAR 类型。有关支持的 SOAP 类型的详细信息,请参见使用数据类型(仅用于 SOAP)和使用结构化数据类型(仅用于 SOAP)。
参数可以使用关键字 IN、OUT 或 INOUT 作为前缀。如果未指定上述任何值,则缺省情况下将使用 INOUT 参数。这些关键字具有以下含义:
IN 此参数是一个为过程提供值的表达式。
OUT 此参数是一个可由过程赋值的变量。
INOUT 此参数是一个为过程提供值的变量,并且可由过程赋值。
使用 CALL 语句执行过程时,不需要指定所有参数。如果在 CREATE PROCEDURE 语句中提供了缺省值,缺少的参数会被分配缺省值。如果 CALL 语句中既未提供参数也未设置缺省值,则会给出错误。
指定 OR REPLACE (CREATE OR REPLACE PROCEDURE) 将创建一个新过程或替换同名的现有过程。此子句将更改过程的定义,但保留现有权限。如果尝试替换已使用的过程,则将返回错误。
您无法创建 TEMPORARY Web 服务过程。
URL 子句 指定 Web 服务的 URI。其中的用户名和口令参数是可选的,它们提供了一种用于提供 HTTP 基本验证所需的证书的方法。HTTP 基本验证对用户和口令信息进行基于 64 位的编码,并在 HTTP 请求的验证标头中传递它。当以这种方式进行指定时,会以未加密形式将用户名和口令作为 URL 的一部分进行传递。
TYPE 子句 指定创建 Web 服务请求时使用的格式。指定 SOAP 时或不包括任何类型子句时使用 SOAP:RPC。指定 HTTP 时使用 HTTP:POST。请参见开发 Web 客户端应用程序。
TYPE 子句允许 HTTP:GET、HTTP:POST 和 HTTP:PUT 类型的 MIME 类型说明。MIME 类型说明用于设置 Content-Type 请求标头并设置操作模式以只允许单个调用参数填充请求的主体。处理完参数替换后进行 Web 服务存储过程调用时,只能保留零个或一个参数。调用参数为空或无参数的 Web 服务过程(替换后)将导致无主体的请求和内容长度为零。如果未指定 MIME 类型,将不更改该行为。参数名和值(允许多个参数)在 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 请求方法。HTTP:PUT 类型没有缺省的媒体类型。
以下示例演示了如何配置通用客户端过程,该过程将数据上载到运行 samples-dir\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 标头。有关 MIME 类型用法的示例,请参见向 Web 服务提供变量和教程:在 RAW 服务中使用 MIME 类型。
HEADER 子句 创建 HTTP Web 服务客户端过程时,此子句用于添加、修改或删除 HTTP 请求标头条目。标头说明与 RFC2616 超文本传输协议—HTTP/1.1 中指定的格式,以及用于 ARPA Internet 文本消息的 RFC822 标准极其相似,其中包括只能为 HTTP 标头指定可打印的 ASCII 字符,且这些字符不区分大小写这一事实。
标头可定义为 header-name:value-name 对。由于标头与标头值之间必须用冒号 (:) 分隔,因此标头中不能包含冒号。通过使用 \n、\x0d\n、<LF>(换行符)或 <CR><LF>(回车符后跟换行符)分隔每个对,可以定义多个标头。
标头内的多个连续空格会转换为一个空格。
有关使用 HTTP 标头的详细信息,请参见HTTP 请求标头管理。
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'。请参见ClientPort (CPORT) 协议选项。
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 模式下发送
' 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'; |
有关如何使用 SOAP 标头的详细信息,请参见教程:使用 SQL Anywhere 访问 SOAP/DISH 服务。
有关替代参数的详细信息,请参见HTTP 和 SOAP 请求结构。
NAMESPACE 子句 (仅 SOAP 格式)此子句标识 SOAP:RPC 和 SOAP:DOC 请求通常都需要的方法命名空间。处理请求的 SOAP 服务器使用此命名空间来解释 SOAP 请求消息主体中的实体名称。可以通过 Web 服务服务器,从 SOAP 服务的 WSDL(Web Services Description Language,Web 服务描述语言)中获取命名空间。缺省值是过程的 URL,但是不包括可选的路径组件。有关如何使用 SOAP 命名空间的详细信息,请参见使用结构化数据类型(仅用于 SOAP)。
有关如何创建 Web 服务的详细信息,包括示例,请参见将 SQL Anywhere 用作 HTTP Web 服务器。
参数值将作为请求的一部分进行传递。使用的语法取决于请求的类型。对于 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 讨论此页。
|
版权 © 2010, iAnywhere Solutions, Inc. - SQL Anywhere 12.0.0 |