CREATE SERVICE 语句

使用此语句，允许数据库服务器充当 Web 服务器。

语法 1 - DISH 服务

CREATE SERVICE service-name
TYPE 'DISH'
[ GROUP { group-name | NULL } ]
[ FORMAT { 'DNET' | 'CONCRETE' [ EXPLICIT { ON | OFF } ] | 'XML' | NULL } ]
[ common-attributes ]

语法 2 - SOAP 服务

CREATE SERVICE service-name
TYPE 'SOAP'
[ DATATYPE { ON | OFF | IN | OUT } ]
[ FORMAT { 'DNET' | 'CONCRETE' [ EXPLICIT { ON | OFF } ] | 'XML' | NULL } ]
[ common-attributes ]
AS statement

语法 3 - 杂项服务

CREATE SERVICE service-name
TYPE { 'RAW' | 'HTML' | 'JSON' | 'XML' }
[ URL [ PATH ] { ON | OFF | ELEMENTS } ]
[ common-attributes ]
[ AS { statement | NULL } ]

common-attributes:
[ AUTHORIZATION { ON | OFF } ]
[ ENABLE | DISABLE ]
[ METHODS 'method,...' ]
[ SECURE { ON | OFF } ]
[ USER { user-name | NULL } ]

method:
DEFAULT
| POST
| GET
| HEAD
| PUT
| DELETE
| NONE
| *

参数

service-name Web 服务名可以是由字母数字字符，或 /、-、_、.、!、~、*、'、( 或 ) 组成的任意序列，但第一个字符不得以斜杠 (/) 开头，并且名称中不得包含两个或两个以上连续的斜杠字符。
与其它服务不同，您不能在 DISH 服务名称中指定正斜线 (/)。
TYPE 子句 通过返回的结果集标识服务类型。该类型必须是列出的服务类型之一。无缺省值。
- 'SOAP' 结果集作为 SOAP 响应返回。数据的格式由 FORMAT 子句确定。对 SOAP 服务的请求必须是有效 SOAP 请求，而不仅是简单的 HTTP 请求。有关 SOAP 标准的详细信息，请参见 http://www.w3.org/TR/2000/NOTE-SOAP-20000508/。
- 'DISH' DISH 服务 (Determine SOAP Handler) 充当 GROUP 子句标识的 SOAP 服务的代理，根据请求，为其中各 SOAP 服务生成 WSDL（Web 服务描述语言）。
- 'RAW' 不对结果集另外进行任何格式设置就将其发送到客户端。可以通过在过程中显式生成所需的标记来生成格式化文档。如果使用 TYPE 'RAW' 创建服务，应使用 sa_set_http_header 设置 HTTP 标头 Content-Type。否则，有些浏览器会将内容显示为纯文本。请参见使用提供 HTML 文档的过程和sa_set_http_header 系统过程。
- 'HTML' 将语句或过程的结果集自动设置为包含表的 HTML 文档格式。
- 'JSON' 结果集以 JavaScript Object Notation (JSON) 格式返回。JSON Web 服务与 XML Web 服务相似，它们都接受 "通用" HTTP 请求（即请求不必包含特殊格式的主体，如 SOAP Web 服务）。有关 JSON 的详细信息，请访问 http://www.json.org。
- 'XML' 结果集以 XML 格式返回。如果结果集已是 XML 格式，则不应用其它任何格式设置。如果它还不是 XML 格式，则将其格式自动设置为 XML。其作用与在 SELECT 语句中使用 FOR XML RAW 子句的作用类似。
GROUP 子句 仅适用于 DISH 服务。指定一个用于控制 DISH 服务公开哪些 SOAP 服务的公用前缀。例如，指定 GROUP xyz 则仅公开 SOAP 服务 xyz/aaaa、xyz/bbbb 或 xyz/cccc，而不公开 abc/aaaa 或 xyzaaaa。如果没有指定组名，则 DISH 服务公开数据库中的所有 SOAP 服务。SOAP 服务可由多个 DISH 服务公开。组名和服务名中允许使用相同的字符。
创建服务时，GROUP NULL 与不指定 GROUP 子句效果相同。但是，如果在 ALTER SERVICE 语句中使用 GROUP NULL，GROUP NULL 将删除任何现有分组，而如果不使用 GROUP 子句则不会出现这种情况。
DATATYPE 子句 仅适用于 SOAP 服务。控制是否对于所有 SOAP 服务格式都支持参数输入和/或结果集输出（响应）的数据类型设置。如果支持，则数据类型设置允许 SOAP 工具箱分析数据并将其归到相应类型。参数数据类型在 DISH 服务生成的 WSDL 的模式部分中公开。输出数据类型则表示为每列数据的 XML 模式类型属性。
DATATYPE 子句允许使用以下值：
- ON 为输入参数和结果集响应生成数据类型设置。
- OFF 不生成输入参数和结果集响应的数据类型设置（缺省值）。
- IN 仅生成输入参数的数据类型设置。
- OUT 仅生成结果集响应的数据类型设置。
有关 SOAP 服务的详细信息，请参见使用 SOAP 服务。

有关将 XMLSchema 类型映射为 SQL 数据类型的详细信息，请参见使用数据类型。
URL 子句 确定是否接受 URL 路径以及在接受的情况下如何处理 URL 路径。
- OFF OFF 表示 URL 请求中的服务名后不能跟有任何内容。如果不允许使用 URL 路径的剩余部分，或者如果服务名称以正斜线 (/) 结尾，则指定 OFF。例如，如果选择 OFF 并且有 URL 路径 http://<主机名>/<服务名>/aaa/bbb/ccc，则只允许使用 http://<主机名>/<服务名>。不允许 URL 路径的其余部分 /<aaa/bbb/ccc。
- ON ON 表示 URL 的余下部分将解释为变量 URL 的值。如果允许 URL 路径的其余部分并将其设置为单个参数，则指定 ON。例如，在 URL 路径 http://<主机名>/<服务名>/aaa/bbb/ccc 中，参数值为 aaa/bbb/ccc。
- ELEMENTS ELEMENTS 表示按照斜线字符将 URL 路径的余下部分拆分为数量最多为 10 个的一组元素，将其设为多个参数。例如，在 URL 路径 http://<主机名>/<服务名>/aaa/bbb/ccc 中，路径的每个元素都按单独的参数处理。例如 url1=aaa、url2=bbb、url3=ccc 等等。将这些值指派给名称由 url 加上一个 1 到 10 之间的数字作后缀组成的变量。如果提供的值少于 10 个，则将其余变量均设置为 NULL。
如果服务名以正斜线字符 / 结尾，则必须将 url 设置为 OFF。缺省值为 OFF。

有关 URL 的详细信息，请参见了解如何解释 URL和处理变量。
FORMAT 子句 仅适用于 DISH 和 SOAP 服务。生成与各种类型 SOAP 客户端（例如 .NET 或 Java JAX-RPC）兼容的输出格式。如果未指定 SOAP 服务的格式，则从该服务的 DISH 服务声明继承格式。如果 DISH 服务也没有声明格式，则格式缺省设置为与 .NET 客户端兼容的 DNET。可以通过定义多个 DISH 服务（每个都使用一个不同的 FORMAT 类型）将没有声明格式的 SOAP 服务与不同类型的 SOAP 客户端同用。
支持以下格式：
- 'DNET' 适于和 .NET SOAP 客户端一同使用的 Microsoft 数据集格式。DNET 是缺省的 FORMAT 值，并且是 SQL Anywhere 9.0.2 版之前唯一可用的格式。
- 'CONCRETE' 一种与平台无关的数据集格式，适于和 JAX-WS 之类的客户端，或根据返回数据结构的格式自动生成接口的客户端一同使用。指定此格式类型会在 WSDL 中提供显式 dataset 元素或 SimpleDataset 元素。
  指定 EXPLICIT ON 后（缺省值），当满足以下条件时，WSDL 描述显式 DataSet 元素：
  - CREATE SERVICE 语句调用存储过程
  - 在存储过程中指定 RESULT 语句
  如果服务语句或存储过程未正确定义，则由 DISH 服务生成的结果集映射将恢复为 SimpleDataset 元素。
  
  指定 EXPLICIT OFF 后，WSDL 描述 SimpleDataset 元素。SimpleDataset 元素将结果集描述为由一组行（其中每个行都包含一组列元素）组成的行集的包容层次。显式 dataset 元素通过包含各列的实际名称和类型，对其进行扩展。
- 'XML' 一种简单的 XML 字符串格式。将数据集作为可以传递到 XML 分析程序的字符串返回。此格式是 SOAP 客户端之间最便于移植的格式。
- NULL SOAP 服务的格式将从 DISH 服务格式（如果存在）继承或缺省设置为 DNET。DISH 服务的格式将缺省设置为 DNET。创建新服务时，指定 FORMAT NULL 与不指定任何格式效果相同。但是，如果在 ALTER SERVICE 语句中使用 FORMAT NULL，FORMAT NULL 将替换任何原有格式，而如果不使用 FORMAT 子句则不替换原有格式。
语句如果语句为 NULL，则 URL 必须指定要执行的语句。否则，指定的 SQL 语句是唯一可通过该服务执行的语句。SOAP 服务必须含有语句；而 DISH 服务不能含有语句。缺省值为 NULL。
强烈建议在生产系统中使用的所有服务都定义一个语句。只有在启用了授权的情况下，该语句才能为 NULL。
AUTHORIZATION 子句 确定在连接服务时用户是否必须通过基本 HTTP 授权指定用户名和口令。缺省值为 ON。如果 AUTHORIZATION 为 OFF，则需要使用 AS 子句，并且必须用 USER 子句标识单个用户。所有请求都使用该用户的帐户和权限运行。如果 AUTHORIZATION 为 ON，则所有用户都必须提供用户名和口令。也可通过使用 USER 子句提供用户名或用户组名来限定允许使用服务的用户。如果用户名为 NULL，则所有已知用户都可以访问该服务。建议在启用授权的情况下运行生产系统，并通过向组中添加用户来授予使用该服务的权限。
当授权的值为 ON 时，与 Web 服务相连的 HTTP 客户端使用通过 64 位编码模糊处理用户和口令信息的基本授权 (RFC 2617)。建议使用 HTTPS 协议以提高安全性。
ENABLE 和 DISABLE 子句 确定是否该服务是否可用。缺省情况下，创建服务时，即启用该服务。创建或变更服务时，可以包含 ENABLE 或 DISABLE 子句。禁用服务可以使该服务离线。之后可以使用 ALTER SERVICE 及 ENABLE 子句启用该服务。

METHODS 子句 指示服务支持哪类请求。有效的请求类型有 DEFAULT、POST、GET、HEAD、PUT、DELETE 和 NONE。可将星号 (*) 用作简写形式，以表示 POST、GET 和 HEAD 属性，这些属性是 RAW、HTML 和 XML 服务类型的缺省请求类型。SOAP 服务的缺省请求类型是 POST 和 HEAD。DISH 服务的缺省请求类型是 GET 和 HEAD。并非所有的请求类型都对所有服务类型有效。下表总结了每种服务类型的有效请求类型。

请求类型	适用的服务	说明
DEFAULT	所有服务	DEFAULT 用于将请求类型设置重置为给定服务类型的缺省设置。该请求类型不能包含在具有其它请求类型的列表中。
POST	SOAP、DISH、RAW、HTML、XML	SOAP、RAW、HTML 和 XML 缺省情况下启用此请求类型。
GET	DISH、RAW、HTML、XML	DISH、RAW、HTML 和 XML 缺省情况下启用此请求类型。
HEAD	SOAP、DISH、RAW、HTML、XML	SOAP、DISH、RAW、HTML 和 XML 缺省情况下启用此请求类型。
PUT	RAW、HTML、XML	缺省情况下不启用。
DELETE	RAW、HTML、XML	缺省情况下不启用。
NONE	所有服务	使用 NONE 来禁止对服务的访问。如果应用于 SOAP 服务，则 SOAP 请求无法直接访问该服务。始终将 DISH 服务作为 SOAP 端点用于一个或多个 SOAP 服务。要强行通过 DISH 服务端点独占访问 SOAP 操作，请为每个 SOAP 服务指定 NONE。
*	RAW、HTML、XML	与指定 'POST,GET,HEAD' 效果相同。

例如，要为 RAW 服务类型指定请求类型的完整列表，可以使用以下任意一个子句：

METHODS '*,PUT,DELETE'
METHODS 'POST,GET,HEAD,PUT,DELETE'

要将任意服务类型的请求类型列表重置为缺省值，可以使用下列子句：

METHODS 'DEFAULT'

SECURE 子句 指明是否接受不安全的连接。ON 表示只接受 HTTPS 连接。HTTP 端口上接收的服务请求将自动重定向到 HTTPS 端口。如果设置为 OFF，则 HTTP 和 HTTPS 两种连接都接受。缺省值为 OFF。
USER 子句 如果禁用授权，则此参数变为必需参数，并指定用于执行所有服务请求的用户 ID。如果启用授权（缺省设置），则此可选子句标识允许访问该服务的用户或用户组。缺省值为 NULL，即向所有用户授予访问权限。

注释

CREATE SERVICE 语句将使数据库服务器充当 Web 服务器。在 ISYSWEBSERVICE 系统表中创建一个新条目。

权限

必须具有 DBA 权限。

副作用

无。

另请参见

标准和兼容性

SQL/2003 服务商扩充。

示例

若要快速设置 Web 服务器，则使用 -xs 选项（例如 -xs http）启动数据库服务器，然后执行下面的语句：

CREATE SERVICE tables TYPE 'HTML'
   AUTHORIZATION OFF
   USER DBA
   AS SELECT *
      FROM SYS.SYSTAB;

执行完此语句之后，使用任意 Web 浏览器打开 URL http://localhost/tables。

以下示例演示了如何编写一个 Hello World 程序。

CREATE PROCEDURE hello_world_proc( )
RESULT (html_doc long varchar)
BEGIN
   CALL dbo.sa_set_http_header( 'Content-Type', 'text/html' );
   SELECT '<html>\n'
       || '<head><title>Hello World</title></head>\n'
       || '<body>\n'
       || '<h1>Hello World!</h1>\n'
       || '</body>\n'
       || '</html>\n';
END;

CREATE SERVICE hello_world TYPE 'RAW'
AUTHORIZATION OFF
USER DBA
AS CALL hello_world_proc;

执行完此语句之后，使用任意 Web 浏览器打开 URL http://localhost/hello_world。

以下示例演示了如何创建 JSON 服务。

CREATE PROCEDURE ListEmployees()
RESULT (
 EmployeeID            integer,
 Surname               person_name_t,
 GivenName             person_name_t,
 StartDate             date,
 TerminationDate       date )
BEGIN
  SELECT EmployeeID, Surname, GivenName, 
         StartDate, TerminationDate 
  FROM Employees 
END;

CREATE SERVICE "JSON/EmployeeList"
TYPE 'JSON'
AUTHORIZATION OFF
SECURE OFF
USER DBA
AS CALL ListEmployees();

执行完此语句之后，使用任意 Web 浏览器打开 URL http://localhost/JSON/EmployeeList，并将 JSON 响应保存到一个文件中，这样就可以使用文本编辑器浏览该服务。