第十四章 手动创建 REST 服务（二）

指定数据格式

可以定义 REST 服务以处理不同格式的数据，例如 JSON、XML、文本或 CSV。 REST 调用可以通过在 HTTP 请求中指定 ContentType 元素来指定它期望发送的数据的形式，并且可以通过在 HTTP 请求中指定 Accept 元素来请求返回数据格式。

在 DocServer 示例中，GetNamespaces() 方法检查 REST 调用是否使用以下内容请求 JSON 数据：

If $Get(%request.CgiEnvs("HTTP_ACCEPT"))="application/json"

本地化 REST 服务

REST 服务返回的任何字符串值都可以本地化，以便服务器以不同语言存储多个版本的字符串。然后，当服务接收到包含 HTTPAccept-Language 标头的 HTTP 请求时，服务会使用相应版本的字符串进行响应。

本地化 REST 服务：

1. 在实现代码中，不要包含硬编码的文字字符串，而是使用 $$$Text 宏的实例，为宏参数提供如下值：

• 默认字符串
• （可选）该字符串所属的域（将字符串分组到域中时，本地化更易于管理）
• （可选）默认字符串的语言代码

例如，而不是这个：

 set returnvalue="Hello world"

 set returnvalue=$$$TEXT("Hello world","sampledomain","en-us")

2. 如果省略 $$$Text 宏的域参数，则还要在 REST 服务类中包含 DOMAIN 类参数。例如：

Parameter DOMAIN = "sampledomain"

3. 编译代码。当这样做时，编译器会在消息字典中为 $$$Text 宏的每个唯一实例生成条目。

消息字典是全局的，因此可以在管理门户中轻松查看（例如）。有一些类方法可以帮助完成常见任务。

4. 开发完成后，导出该域或所有域的消息字典。

结果是一个或多个 XML 消息文件，其中包含原始语言的文本字符串。

5. 将这些文件发送给翻译人员，请求翻译版本。

6. 当收到已翻译的 XML 消息文件时，将它们导入到导出原始文件的同一名称空间中。

译文和原文在消息词典中并存。

7. 在运行时，REST 服务根据 HTTP Accept-Language 标头选择要返回的文本。

通过REST 使用 Web 会话

有关介绍，请参阅本书前面的“将 Web 会话与 REST 结合使用”。

要使 REST 服务能够通过多个 REST 调用使用单个 Web 会话，请在 REST 服务类中将 UseSession 参数设置为 1：

Parameter UseSession As Integer = 1;

支持 CORS

有关介绍，请参阅本书前面的“CORS 简介”。请注意，当按照本附录中的描述手动创建 Web 服务时，支持 CORS 的详细信息会略有不同。

修改 REST 服务以使用 CORS

要指定 REST 服务支持 CORS，请按如下方式修改 REST 服务类，然后重新编译它。

1. 为 HandleCorsRequest 参数指定一个值。

要为所有调用启用 CORS 标头处理，请将 HandleCorsRequest 参数指定为 1：

Parameter HandleCorsRequest = 1;

或者，要为某些调用启用 CORS 标头处理，但不是调用，请将 HandleCorsRequest 参数指定为“”（空字符串）：

Parameter HandleCorsRequest = "";

（如果 HandleCorsRequest 为 0，则对所有调用禁用 CORS 标头处理。在这种情况下，如果 REST 服务接收到带有 CORS 标头的请求，服务将拒绝该请求。这是默认设置。）

2. 如果将 HandleCorsRequest 参数指定为“”，请编辑 URLMap XData 块以指示哪些调用支持 CORS。具体来说，对于任何应该支持 CORS 的 <Route>，添加以下属性名称和值：

Cors="true"

或者在 <Route> 元素中指定 Cors="false" 以禁用 CORS 处理。

如果 REST 服务类将 REST 请求转发到另一个 REST 服务类，则 CORS 处理的行为由包含与给定请求匹配的 <Route> 元素的类确定。

覆盖 CORS 标头处理

重要提示：默认 CORS 标头处理不适用于处理机密数据的 REST 服务。

默认的 CORS 头处理不做任何过滤，只是将 CORS 头传递给外部服务器并返回响应。可能希望限制对域允许列表中的源的访问或限制允许的请求方法。可以通过覆盖 REST 服务类中的 OnHandleCorsRequest() 方法来做到这一点。

请注意，与 UrlMap 中的 <Route> 元素匹配的所有 URL 请求都使用类中定义的单个 OnHandleCorsRequest() 方法进行处理。如果需要针对不同的 REST URL 请求使用不同的 OnHandleCorsRequest() 方法实现，则应使用 Forward 将请求发送到其他 REST 服务类。

变量：访问查询参数

将参数传递给 REST 服务的推荐方法是将它们作为用于调用服务的 URL 路径的一部分传递（例如，/myapi/someresource/parametervalue）。但是，在某些情况下，将参数作为查询参数传递可能更方便（例如，/myapi/someresource?parameter=value）。在这种情况下，可以使用 %request 变量来检索参数值。在 REST 服务中，%request 变量是 %CSP.Request 的一个实例，它包含整个 URL 查询。要检索给定查询参数的值，请使用以下语法：

$GET(%request.Data(name,1),default)

其中 name 是查询参数的名称，default 是要返回的默认值。或者，如果同一个 URL 包含同一个查询参数的多个副本，请使用以下语法：

$GET(%request.Data(name,index),default)

其中 index 是要检索的副本的数字索引。