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 ]

url-string :
' { HTTP | HTTPS | HTTPS_FIPS }://[user:password@]hostname[:port][/path]'

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

CREATE FUNCTION 参数名必须符合数据库标识符规则。它们必须是有效的 SQL 数据类型，且必须以关键字 IN 作为前缀，以表明参数是为函数提供值的表达式。
执行函数时，不必指定所有参数。如果在 CREATE FUNCTION 语句中提供了缺省值，则会为缺少的参数指派缺省值。如果调用程序既未提供参数又未设置缺省值，则会给出错误。

指定 OR REPLACE (CREATE OR REPLACE FUNCTION) 将创建一个新函数或替换同名的现有函数。此子句将更改函数的定义，但保留现有权限。不能将 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 服务客户端函数。指定 Web 服务的 URL。其中的用户名和口令参数是可选的，它们提供了一种用于提供 HTTP 基本验证所需的证书的方法。HTTP 基本验证对用户和口令信息进行基于 64 位的编码，并在 HTTP 请求的验证标头中传递它。
指定 HTTPS_FIPS 会强制系统使用 FIPS 库。如果指定了 HTTPS_FIPS，但不存在 FIPS 库，则会改为使用非 FIPS 库。
HEADER 子句 创建 HTTP Web 服务客户端函数时，此子句用于添加或修改 HTTP 请求标头条目。仅可为 HTTP 标头指定可打印 ASCII 字符，且这些字符不区分大小写。有关如何使用此子句的详细信息，请参见CREATE PROCEDURE 语句（Web 客户端）中的 HEADER 子句。
有关使用 HTTP 标头的详细信息，请参见HTTP 请求标头管理。
SOAPHEADER 子句 当将 SOAP Web 服务声明为函数时，此子句用于指定一个或多个 SOAP 请求标头条目。SOAP 标头可声明为静态常量，也可使用参数替代机制动态设置（为参数 hd1、hd2 等声明 IN、OUT 或 INOUT 参数）。Web 服务函数可定义一个或多个 IN 模式替代参数，但无法定义 INOUT 或 OUT 替代参数。有关如何使用此子句的详细信息，请参见CREATE PROCEDURE 语句（Web 客户端）中的 SOAPHEADER 子句。
有关如何使用 SOAP 标头的详细信息，请参见教程：使用 SQL Anywhere 访问 SOAP/DISH 服务。

有关替代参数的详细信息，请参见HTTP 和 SOAP 请求结构。

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

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 请求方法。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 标头。有关 MIME 类型用法的示例，请参见向 Web 服务提供变量和教程：在 RAW 服务中使用 MIME 类型。

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	证书本身。
company	co	证书中指定的公司。
unit		证书中指定的公司单位。
name		证书中指定的公用名。

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

CLIENTPORT 子句 标识 HTTP 客户端函数使用 TCP/IP 进行通信的端口号。该子句是为通过防火墙的连接提供的，并建议只用于此类连接，因为防火墙按照 TCP/UDP 端口进行过滤。您可以指定单个端口号、端口号范围或是两者的组合；例如 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 FUNCTION accounts_login( name LONG VARCHAR, pwd LONG VARCHAR ) SET 'SOAP(OPERATION=login)';

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

以下语句显示了几个 protocol-option 设置在同一 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 请求的参数总是被绑定在请求主体中。

RESOURCE 特权。

用于外部函数（包括 Java 函数）的 DBA 特权。

自动提交。

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 作为输入参数传递。SET 子句用于关闭 CHUNK 模式传输编码。

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

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

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

CREATE FUNCTION 语句（Web 客户端）

语法

参数

注释

权限

副作用

另请参见

标准和兼容性

示例