文章
姚 鑫 · 八月 1 阅读大约需 4 分钟

第十四章 手动创建 REST 服务(二)

第十四章 手动创建 REST 服务(二)

指定数据格式

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

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

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

本地化 REST 服务

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

本地化 REST 服务:

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

- 默认字符串
- (可选)该字符串所属的域(将字符串分组到域中时,本地化更易于管理)
- (可选)默认字符串的语言代码

例如,而不是这个:

 set returnvalue="Hello world"
 set returnvalue=$$$TEXT("Hello world","sampledomain","en-us")
  1. 如果省略 $$$Text 宏的域参数,则还要在 REST 服务类中包含 DOMAIN 类参数。例如:
Parameter DOMAIN = "sampledomain"
  1. 编译代码。当这样做时,编译器会在消息字典中为 $$$Text 宏的每个唯一实例生成条目。

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

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

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

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

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

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

  1. 在运行时,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 = "";

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

  1. 如果将 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 是要检索的副本的数字索引。

0
0 4
讨论 (0)1
登录或注册以继续