CREATE FUNCTION 语句 [Web 服务]

CREATE [ OR REPLACE ] FUNCTION [ owner.]function-name ( [ parameter, ... ] )
RETURNS data-type
URL url-string
[ HEADER header-string ]
[ SOAPHEADER soap-header-string ]
[ TYPE { 
  'HTTP[ :{ GET | POST[:MIME-type ] | PUT[:MIME-type ] | DELETE | HEAD } ]' | 
  'SOAP[:{ RPC | DOC } ]' } ]
[ NAMESPACE namespace-string ]
[ CERTIFICATE certificate-string ]
[ CLIENTPORT clientport-string ]
[ PROXY proxy-string ]
[ SET protocol-option-string ]

parameter :
   [ IN ] parameter-name data-type [ DEFAULT expression ]

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 };kto=number-of-seconds ]
[REDIR(COUNT=count, STATUS=status-list)
)

 soap-option-list : 
SOAP(OP[ERATION]=soap-operation-name)

参数名必须符合数据库标识符规则。它们必须是有效的 SQL 数据类型，且必须以关键字 IN 作为前缀，以表明参数是为函数提供值的表达式。但在缺省情况下，函数参数是 IN。

执行函数时，不必指定所有参数。如果在 CREATE FUNCTION 语句中提供 DEFAULT 值，则会为缺少的参数指派缺省值。如果调用程序既未提供参数又未设置缺省值，则会给出错误。

OR REPLACE 子句 指定 OR REPLACE 将创建一个新函数或替换同名的现有函数。此子句将更改函数的定义，但保留现有特权。不能将 OR REPLACE 子句与临时函数一起使用。
RETURNS 子句 指定以下一项内容以定义 SOAP 或 HTTP 函数的返回类型：
- CHAR
- VARCHAR
- LONG VARCHAR
- TEXT
- NCHAR
- NVARCHAR
- LONG NVARCHAR
- NTEXT
- XML
- BINARY
- VARBINARY
- LONG BINARY
返回值是 HTTP 响应的主体。其中不包括 HTTP 标头信息。如果需要详细信息（例如状态信息），请使用过程而非函数。

数据类型不影响如何处理 HTTP 响应。
URL 子句 定义 HTTP 或 SOAP Web 服务客户端函数时只使用 URL 子句。URL 子句指定 Web 服务的 URI。其中的用户名和口令参数是可选的，它们提供了一种用于提供 HTTP 基本验证所需的证书的方法。HTTP 基本验证对用户和口令信息进行基于 64 位的编码，并在 HTTP 请求的验证标头中传递它。
指定 HTTPS_FIPS 会强制系统使用经 FIPS 认证的库。如果指定 HTTPS_FIPS，但不存在经 FIPS 认证的库，则会改为使用未经 FIPS 认证的库。

对于 HTTP:GET 类型的函数，查询函数除了从传递到某个过程的参数自动生成以外，还可以在 URL 子句中指定。
URL 'http://localhost/service?parm=1
HEADER 子句 创建 HTTP Web 服务客户端函数时，此子句用于添加或修改 HTTP 请求标头条目。仅可为 HTTP 标头指定可打印 ASCII 字符，且这些字符不区分大小写。
SOAPHEADER 子句 当将 SOAP Web 服务声明为函数时，此子句用于指定一个或多个 SOAP 请求标头条目。SOAP 标头可声明为静态常量，也可使用参数替代机制动态设置（为参数 hd1、hd2 等声明 IN、OUT 或 INOUT 参数）。Web 服务函数可定义一个或多个 IN 模式替代参数，但无法定义 INOUT 或 OUT 替代参数。

TYPE 子句 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 类型包括：

text/plain
text/html
text/xml

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 类型没有缺省的媒体类型。

以下示例演示了如何配置通用客户端过程，该过程将数据上载到运行 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 标头。

NAMESPACE 子句 仅适用于 SOAP 客户端函数。此子句标识 SOAP:RPC 和 SOAP:DOC 请求通常都需要的方法命名空间。处理请求的 SOAP 服务器使用此命名空间来解释 SOAP 请求消息主体中的实体名称。可以通过 Web 服务服务器，从 SOAP 服务的 WSDL（Web Services Description Language，Web 服务描述语言）中获取命名空间。缺省值是函数的 URL，直到（但不包括）可选的路径组成部分。

CERTIFICATE 子句 要创建安全 (HTTPS) 请求，客户端必须有权访问 HTTPS 服务器所用的证书。必要的信息在一个用分号分隔的键/值对字符串中指定。可以使用 file 键指定证书的文件名称，也可以使用 certificate 键在字符串中指定服务器证书。不能同时指定 file 和 certificate 键。可以使用以下键：

按键	缩写	说明
file		证书的文件名。
certificate	cert	证书本身。
certificate_name	cert_name	存储在数据库中的证书的名称。
company	co	证书中指定的公司。
unit		证书中指定的公司单位。
name		证书中指定的公用名。

只有被定向到 HTTPS 服务器的请求或可从非安全服务器重定向到安全服务器的请求才需要证书。仅支持 PEM 格式的证书。

CLIENTPORT 子句 标识 HTTP 客户端函数使用 TCP/IP 进行通信的端口号。该子句是为通过防火墙的连接提供的，并建议只用于此类连接，因为防火墙按照 TCP/UDP 端口进行过滤。您可以指定单个端口号、端口号范围或是两者的组合；例如 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;kto=number-of-seconds )' （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 模式下发送

kto=number-of-seconds 指定保持活动状态的超时条件 (kto)，从而允许 Web 客户端过程在一段时间内对保持活动状态的 HTTP/HTTPS 连接进行实例化和高速缓存。要高速缓存 HTTP 保持活动状态的连接，必须将 HTTP 版本设置为 1.1，并将 kto 设置为非零值。如果注意到 HTTP 连接与 HTTPS 连接之间显著的性能差异，就会发现 kto 非常有用，尤其是对于 HTTP 连接。数据库连接只能高速缓存一个保持活动状态的 HTTP 连接。使用相同 URI 对 Web 客户端过程进行的后续调用将重复使用该保持活动状态的连接。因此，执行中的 Web 客户端调用所拥有的 URI 必须与高速缓存 URI 的模式、目标主机和端口相匹配，且 HEADER 子句不得指定 Connection：Close。当 kto 未指定或设为零时，不会对 HTTP/HTTPS 连接进行高速缓存。

'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 参见其它内容] 状态）的 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 FUNCTION accounts_login( name LONG VARCHAR, pwd LONG VARCHAR ); SET 'SOAP(OPERATION=login)';

如果未指定 OPERATION 选项，SOAP 操作的名称必须与正在创建的过程的名称匹配。

以下语句显示了几个 protocol-option-string 设置在同一 SET 子句中是如何组合的：

CREATE FUNCTION accounts_login( 
      name LONG VARCHAR, 
      pwd LONG VARCHAR );
   SET 'HTTP ( CHUNK=ON; VERSION=1.1 ), SOAP( OPERATION=login )' 
   ...

CREATE FUNCTION 语句在数据库中创建 Web 服务函数。通过指定所有者名称，可以为其他用户创建函数。

参数值将作为请求的一部分进行传递。使用的语法取决于请求的类型。对于 HTTP:GET，参数将作为 URL 的一部分进行传递；对于 HTTP:POST 请求，则将值放在请求主体中。SOAP 请求的参数总是被绑定在请求主体中。

必须具有 CREATE PROCEDURE 系统特权才能创建归您所有的函数。

必须具有 CREATE ANY PROCEDURE 或 CREATE ANY OBJECT 系统特权才能创建归其他人所有的函数。

必须具有 CREATE EXTERNAL REFERENCE 系统特权才能创建外部函数。

创建临时函数不需要任何特权。

自动提交。

SQL/2008 服务商扩充。
Transact-SQL 不受 Adaptive Server Enterprise 支持。

以下语句创建名为 cli_test1 的函数，该函数用于从 localhost 上运行的 get_picture 服务中返回图像：

CREATE FUNCTION cli_test1( image LONG VARCHAR )
RETURNS LONG BINARY
URL 'http://localhost/get_picture' 
TYPE 'HTTP:GET';

以下语句发出 URL 为 http://localhost/get_picture?image=widget 的 HTTP 请求：

SELECT cli_test1( 'widget' );

以下语句使用了替代参数，以允许将请求 URL 作为输入参数传递。安全 HTTPS 请求将使用数据库中所存储的证书。SET 子句用于关闭 CHUNK 模式传输编码。

CREATE CERTIFICATE client_cert 
FROM FILE 'C:\\Users\\Public\\Documents\\SQL Anywhere 16\\Samples\\Certificates\\rsaroot.crt';

CREATE FUNCTION cli_test2( image LONG VARCHAR, myurl LONG VARCHAR )
RETURNS LONG BINARY
URL '!myurl'
CERTIFICATE 'certificate_name=client_cert'
TYPE 'HTTPS:GET'
SET 'HTTP(CH=OFF)'
HEADER 'ASA-ID';

以下语句发出 URL 为 http://localhost/get_picture?image=widget 的 HTTP 请求：

CREATE VARIABLE a_binary LONG BINARY;
SET a_binary = cli_test2( 'widget', 'https://localhost/get_picture' );
SELECT a_binary;

CREATE FUNCTION 语句 [Web 服务]

语法

参数

注释

特权

副作用

另请参见

标准和兼容性

示例