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

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

文章目录

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

​​URL and Input JSON Message​​​​URL Parameters​​​​HTTP Headers​​​​JSON Messages​​​​HTTP 返回码​​

​​GetDoc​​

​​URL​​​​URL Parameters​​​​HTTP Headers​​​​JSON Messages​​​​HTTP 返回码​​

第二十二章 源代码文件 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 ​​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 ​​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​​​（请参阅​​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" }}

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。