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

指定数据格式

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

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

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

本地化 REST 服务

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

本地化 REST 服务：

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

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

例如，而不是这个：

 set returnvalue="Hello world"
1

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

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

Parameter DOMAIN = "sampledomain"
1

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;
1

支持 CORS

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

修改 REST 服务以使用 CORS

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

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

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

Parameter HandleCorsRequest = 1;
1

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

Parameter HandleCorsRequest = "";
1

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

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

Cors="true"
1

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

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

覆盖 CORS 标头处理

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

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

请注意，与 UrlMap 中的 元素匹配的所有 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)
1

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

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

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