ALTER SERVICE 语句 [HTTP Web 服务]

ALTER 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 服务名称可以是由字母数字字符，或正斜线 (/)、连字符 (-)、下划线 (_)、句点 (.)、感叹号 (!)、代字号 (~)、星号 (*)、撇号 (')、左括号 (() 或右括号 ()) 组成的任意序列，但服务名称不得以正斜线 (/) 开头或结尾，并且不得包含两个或两个以上连续的正斜线（例如 //）。
您可以将服务命名为 root，但该名称具有特殊功能。
TYPE 子句 标识服务类型，其中每种服务定义一种特殊的响应格式。该类型必须是列出的服务类型之一。无缺省值。
- 'RAW' 不对结果集进行任何格式设置就将其发送到客户端。使用该服务需要显式提供所有内容标记。可以根据需要生成包含带标记的当前内容、JavaScript 和图像的复杂动态内容。通过使用 sa_set_http_header 过程设置 Content-Type 响应标头，可指定媒体类型。当生成 HTML 标记时，将 Content-Type 标头设置为 "text/html" 是很好的做法，以确保所有浏览器将标记作为 HTML 而不是 text/plain 显示。
- 'HTML' 结果集以 HTML 形式表示的表或视图格式返回。
- 'JSON' 结果集以 JavaScript Object Notation (JSON) 格式返回。JSON 服务不会自动处理 JSON 输入。它只会以 JSON 格式显示数据（在响应中）。JSON 接受支持 application/x-www-form-urlencoded 的 POST/PUT 方法。如果为 POST/PUT METHOD 指定 Content-Type: application/json，则应用程序可以使用 http_variable('body') 来检索 JSON（请求）内容。SQL Anywhere 不会自动分析 JSON 输入。应用程序负责解析 JSON 输入。有关 JSON 的详细信息，请参见 http://www.json.org/。
- 'XML' 结果集以 XML 格式返回。如果结果集已是 XML 格式，则不应用其它任何格式设置。否则，结果集将自动格式化为 XML。或者，在已经使用 sa_set_http_header 过程设置有效 Content-Type（例如 text/xml）的情况下，使用 FOR XML RAW 子句的 RAW 服务同样可以返回 select 结果。

URL 子句 确定是否接受 URL 路径以及在接受的情况下如何处理 URL 路径。指定 URL PATH 具有与 URL 相同的效果。

OFF 指示 URL 请求中的服务名称必须不跟路径。缺省设置为 OFF。例如，由于存在路径元素 /aaa/bbb/ccc，所以不允许以下形式。

http://host-name/service-name/aaa/bbb/ccc

假定在创建 Web 服务时指定了 CREATE SERVICE echo URL PATH OFF。类似于 http://localhost/echo?id=1 的 URL 产生以下值：

Function call	Result
HTTP_VARIABLE('id')	1
HTTP_HEADER('@HttpQueryString')	id=1

ON 指示 URL 请求中的服务名称可以跟有路径。路径值在查询名为 URL 的专用 HTTP 变量时被返回。可以将服务定义为显式提供 URL 参数，或者通过使用 HTTP_VARIABLE 函数检索该参数。例如，允许以下形式：

http://host-name/service-name/aaa/bbb/ccc

假定在创建 Web 服务时指定了 CREATE SERVICE echo URL PATH ON。类似于 http://localhost/echo/one/two?id=1 的 URL 产生以下值：

Function call	Result
HTTP_VARIABLE('id')	1
HTTP_VARIABLE('URL')	one/two
HTTP_HEADER('@HttpQueryString')	id=1

ELEMENTS 指示 URL 请求中的服务名称可能跟有路径。该路径通过指定单个参数关键字 URL1、URL2 等从参数中分别获取。也可以使用 HTTP_VARIABLE 或 NEXT_HTTP_VARIABLE 函数检索每个参数。这些迭代函数适用于可以提供可变数量路径元素的应用程序。例如，允许以下形式：

http://host-name/service-name/aaa/bbb/ccc

假定在创建 Web 服务时指定了 CREATE SERVICE echo URL PATH ELEMENTS。类似于 http://localhost/echo/one/two?id=1 的 URL 产生以下值：

Function call	Result
HTTP_VARIABLE('id')	1
HTTP_VARIABLE('URL1')	one
HTTP_VARIABLE('URL2')	two
HTTP_VARIABLE('URL3')	NULL
HTTP_HEADER('@HttpQueryString')	id=1

最多可以获取 10 个元素。如果不提供相应的元素，则返回 NULL 值。在上面的示例中，因为没有提供相应的元素，所以 HTTP_VARIABLE('URL3') 返回 NULL。

有关 URL 的详细信息，请参见如何浏览 SQL Anywhere HTTP Web 服务器和如何访问客户端提供的 HTTP 变量与标头。

AUTHORIZATION 子句 确定在连接服务时用户是否必须通过基本 HTTP 授权指定用户名和口令。缺省值为 ON。如果 AUTHORIZATION 为 OFF，则需要使用 AS 子句处理所有服务，并且必须用 USER 子句指定用户。所有请求都使用该用户的帐户和特权运行。如果 AUTHORIZATION 为 ON，则所有用户都必须提供用户名和口令。也可通过使用 USER 子句提供用户名或用户组名来限定允许使用服务的用户。如果用户名为 NULL，则所有已知用户都可以访问该服务。AUTHORIZATION 子句允许 Web 服务使用数据库授权和特权来控制对数据库中数据的访问。
当授权的值为 ON 时，与 Web 服务相连的 HTTP 客户端使用基本授权 (RFC 2617)。基本授权通过 64 位编码来模糊处理用户和口令信息。建议使用 HTTPS 协议以提高安全性。
ENABLE 和 DISABLE 子句 确定是否该服务是否可用。缺省情况下，创建服务时，即启用该服务。创建或变更服务时，可以包含 ENABLE 或 DISABLE 子句。禁用服务可以使该服务离线。之后可以使用 ALTER SERVICE 及 ENABLE 子句启用该服务。对已禁用服务的 HTTP 请求，通常返回 [404 未找到] HTTP 状态。

METHODS 子句 指定服务支持的 HTTP 方法。有效值有 DEFAULT、POST、GET、HEAD、PUT、DELETE 和 NONE。可使用星号 (*) 作为简写形式，用来表示 POST、GET 和 HEAD 方法，这些方法是 RAW、HTML 和 XML 服务类型的缺省请求类型。并非所有的 HTTP 方法都对所有服务类型有效。下表总结了每种服务类型可以应用的有效 HTTP 方法：

方法值	适用的服务	说明
DEFAULT	all	使用 DEFAULT 可重置给定服务类型的缺省 HTTP 方法集。该方法集不能包含在具有其它方法值的列表中。
POST	RAW、HTML、JSON、XML	缺省启用。
GET	RAW、HTML、JSON、XML	缺省启用。
HEAD	RAW、HTML、JSON、XML	缺省启用。
PUT	RAW、HTML、JSON、XML	缺省情况下不启用。
DELETE	RAW、HTML、JSON、XML	缺省情况下不启用。
NONE	all	使用 NONE 来禁止对服务的访问。
*	RAW、HTML、JSON、XML	与指定 'POST,GET,HEAD' 效果相同。

例如，要指定某个服务支持所有 HTTP 方法类型，可以使用以下任意一个子句：

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

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

METHODS 'DEFAULT'

SECURE 子句 指定服务是否能够通过安全或非安全监听器访问。ON 表示仅接受 HTTPS 连接，并且在 HTTP 端口上接收的连接都将自动重定向到 HTTPS 端口。OFF 表示只要在启动 Web 服务器时指定了必要的端口，就可同时接受 HTTP 和 HTTPS 连接。缺省值为 OFF。
USER 子句 指定数据库用户（或用户组）拥有执行 Web 服务请求的特权。如果应该指定 AUTHORIZATION ON 的服务配置为 AUTHORIZATION OFF（缺省值），则必须指定 USER 子句。对需要授权的服务执行 HTTP 请求会导致 401 Authorization Required HTTP 响应状态。根据该响应，Web 浏览器会提示需要用户 ID 和口令。

小心

强烈建议您在启用授权时（缺省情况）指定 USER 子句。否则，将向所有用户授予权限。

USER 子句控制可以使用哪些数据库用户帐户处理服务请求。数据库访问权限限制为分配给该服务的用户的权限。

语句指定访问服务时调用的命令，例如存储过程调用。

对非 DISH 服务的 HTTP 请求（无 statement）指定要在其 URL 内执行的 SQL 表达式。尽管有授权要求，依然不得在生产系统中使用此功能，因为它会给服务器带来 SQL 注入的风险。在该服务内定义语句时，指定的 SQL 语句是唯一可在整个服务内执行的语句。

在典型的 Web 服务应用中，使用 statement 调用函数或过程。可将主机变量作为参数传递以访问客户端提供的 HTTP 变量。

以下 statement 演示了一个过程调用，它会将两个主机变量传递到名为 AuthenticateUser 的过程。该调用假定 Web 客户端提供 user_name 和 user_password 变量：

CALL AuthenticateUser ( :user_name, :user_password );

有关将主机变量传递到函数或过程的详细信息，请参见如何访问客户端提供的 HTTP 变量与标头。

ALTER SERVICE 语句修改 Web 服务的属性。

您必须是服务的所有者，或者拥有 MANAGE ANY WEB SERVICE 系统特权。

无。

SQL/2008 服务商扩充。

以下示例演示如何使用 ALTER SERVICE 语句禁用现有 Web 服务：

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

ALTER SERVICE WebServiceTable DISABLE;

ALTER SERVICE 语句 [HTTP Web 服务]

语法

参数

小心

注释

特权

副作用

另请参见

标准和兼容性

示例