第二十二章 源代码文件 REST API 参考（四）

PutDoc

此方法保存提供的源代码文件。如果文件不存在，此方法将创建它，如果文件存在，此方法将现有文件替换为指定的文件。为确保覆盖文件的正确版本，请指定 If-None-Match 标头以及先前 PutDoc 或 GetDoc 的 ETAG 标头中返回的时间戳值。如果要覆盖文件而不检查版本，请指定 ?ignoreConflict=1 URL 参数。该方法返回一个对应的源代码文件对象。如果要保存二进制文件，请将传入 JSON 消息的 enc 元素设置为 true，并将文件内容包含为 base64 块数组。如果在保存过程中更改了服务器上的文本（例如通过源代码管理挂钩），则更新后的文本将在返回的源代码文件的内容数组中返回。

与源代码文件有关的错误将在返回的源代码文件对象的状态属性中。

版本 2 PutDoc 能够接受三种格式的文件内容：默认 UDL 格式、XML 格式和旧 %RO 导出实用程序使用的格式。 PutDoc 自动识别文件内容的格式。

有关示例和其他详细信息，请参阅本手册教程章节中的在命名空间中创建新文件或更新现有文件。

URL and Input JSON Message

PUT http://server:port/api/atelier/v1/namespace/doc/doc-name

PUT http://server:port/api/atelier/v2/namespace/doc/doc-name

以下是源代码文件 xyz.mac 的 PutDoc 的输入 JSON 消息示例：

{
 "enc": false,
 "content": [
   "ROUTINE xyz",
   "xyz ;",
   "   w \"hello\""
   ]
}

注意：如果正在创建 CSP 文件），则 doc-name 的值包括 /（斜杠）字符。这就是定义 PutDoc 的 URLMap 包含此参数名称的 (.*) 而不是 :docname 的原因。

URL Parameters

可以传递 URL 参数 ?ignoreConflict=1 以绕过 ETAG 检查。这会强制将源代码文件写入服务器，即使该文件在您之前访问后已更改。

HTTP Headers

• If-None-Match - 为确保覆盖文件的正确版本，请指定 If-None-Match 标头以及在先前 PutDoc 或 GetDoc 的 ETAG 标头中返回的时间戳值。

JSON Messages

以下是源代码文件 xyz.mac 的 PUT 的返回内容：

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "xyz.mac",
    "db": "INVENTORYR",
    "ts": "2016-09-14 14:10:16.540",
    "upd": false,
    "cat": "RTN",
    "status": "",
    "enc": false,
    "flags": 0,
    "content": []
  }
}

当一个类被保存时，PutDoc 总是返回存储部分，因为它可能被服务器规范化。如果内容只是存储部分，则 'flags' json 字段将为 1。如果 PutDoc 在内容中返回整个类或内容为空，则“标志”将为 0。

HTTP 返回码

• HTTP 200（如果已更新）。
• HTTP 201（如果已创建）。
• 如果资源名称是无效的源代码文件名，则返回 HTTP 400。
• 如果找不到资源，则返回 HTTP 404。
• 如果基于时间戳检测到服务器和客户端版本之间的冲突，则 HTTP 409。如果文件存在，PutDoc 将返回此代码，除非 If-None-Match 标头指定服务器上文件的当前时间戳值。如果存在冲突，则返回消息中包含服务器上源代码文件的内容。
• 如果未将 text/plain 作为内容类型传递，则 HTTP 415。
• 如果源代码文件被锁定并且无法写入，则 HTTP 425。
• HTTP 500 如果发生意外错误（详细信息将在状态错误数组中）。

GetDoc

此方法返回命名源代码文件和命名空间的文本。

返回内容将包含一个源代码文件对象。

与源代码文件有关的错误将在源代码文件对象的状态属性中。如果为命名空间启用源代码控制挂钩，则挂钩生成的任何控制台输出都将被捕获并作为“控制台”数组中的行数组返回。

结果包含请求文件的名称、存储文件的数据库、时间戳和类别缩写 (CLS = class; RTN = routine; CSP = CSP file；OTH = other)，以及以数组形式返回的源代码文件内容。

• 对于文本文件，这将是一个字符串数组，并且“enc”json 字段将设置为 false。
• 对于二进制文件，这将是一个 base64 编码块的数组，并且“enc”字段将设置为 true。

版本 2 GetDoc 可以以 UDL 格式（默认）、XML 格式或旧 %RO 导出实用程序使用的格式返回文件内容。

URL

GET http://server:port/api/atelier/v1/namespace/doc/doc-name

GET http://server:port/api/atelier/v2/namespace/doc/doc-name

注意：如果正在获取 CSP 文件，则 doc-name 的值包括 /（斜杠）字符。这就是定义 GetDoc 的 URLMap 包含此参数名称的 (.*) 而不是 :docname 的原因。有关详细信息，请参阅创建 REST 服务中的“为 REST 创建 URL 映射”。

URL Parameters

• 可以传递 URL 参数 ?binary=1 以强制将源代码文件编码为二进制。
• 可以传递 URL 参数 ?storageOnly=1 以仅返回类的存储部分。
• 在版本 2 中，可以传递 URL 参数 ?format= parameter 以指定应以 UDL 格式（默认）、XML 格式或旧 %RO 导出实用程序使用的格式返回文件的内容。
  • ?format=udl
  • ?format=xml
  • ?format=%RO

如果指定 ?binary=1，GetDoc 将忽略格式参数。

HTTP Headers

• If-None-Match - 指定上次调用该文件的 GetDoc 或 PutDoc 时在 HTTP ETAG 标头中返回的值。如果自上次调用以来文件未更改，GetDoc 将返回 HTTP 304 状态。

JSON Messages

以下是请求 %Api.DocDB.cls 返回结果的第一部分示例：

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "%Api.DocDB.cls",
    "db": "IRISLIB",
    "ts": "2016-09-13 22:31:24.000",
    "upd": true,
    "cat": "CLS",
    "status": "",
    "enc": false,
    "flags": 0,
    "content": [
       /// Routing class for the DocDB REST services",
       "Class %Api.DocDB Extends %DocDB.REST",
       "{",
...

以下是 ?binary=1 的相同请求的结果：

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "%Api.DocDB.cls",
    "db": "IRISLIB",
    "ts": "2016-01-04 14:00:04.000",
    "cat": "CLS",
    "status": "",
    "enc": true,
    "content": [
      "Ly8vIFRoaXMgY2xhc3MgaXMgdGhlIHN1cGVyY2xhc3MgZm9yIGFsbCBl  ... PSAzIF0KewoKfQo="
    ]
  }
}

HTTP 返回码

• HTTP 200 如果正常。
• 如果源代码文件未修改，则为 HTTP 304（请参阅 https://en.wikipedia.org/wiki/HTTP_ETag）。
• 如果命名资源不是有效的源代码文件名，则返回 HTTP 400。
• 如果源代码文件不存在，则返回 HTTP 404。
• HTTP 500 如果发生意外错误（详细信息将在状态错误数组中）。

如果发生“soft”错误，例如“源代码文件不存在”，则可以在结果的“状态”字段中找到其他信息。其他软错误的示例包括“文件已锁定”。例如，可以使用 HTTP 404 返回代码返回以下内容：

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "xyz1.mac",
    "db": "",
    "ts": "",
    "cat": "RTN",
    "enc": false,
    "content": "",
    "status": "ERROR #16005: Document 'xyz1.mac' does NOT exist"
  }
}