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

PutDoc

This method saves the provided source code file.如果文件不存在,This method will create it,如果文件存在,This method replaces the existing file with the specified file.To ensure the correct version of the file is overwritten,请指定 If-None-Match header as well as previous PutDoc 或 GetDoc 的 ETAG The timestamp value returned in the header.If you want to overwrite the file without checking the version,请指定 ?ignoreConflict=1 URL 参数.This method returns a corresponding source code file object.If you want to save binary files,please pass in JSON 消息的 enc 元素设置为 true,and include the file contents as base64 块数组.If the text on the server was changed during the save process（For example via source control hooks）,then the updated text will be returned in the content array of the returned source code file.

Errors related to source code files will be in the status property of the returned source code file object.

版本 2 PutDoc Can accept file content in three formats：默认 UDL 格式、XML format and old %RO The format used by the export utility. PutDoc Automatically recognizes the format of the file content.

For examples and other details,See Creating a New File or Updating an Existing File in a Namespace in the Tutorials chapter of this manual.

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

Below is the source code file xyz.mac 的 PutDoc 的输入 JSON 消息示例：

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

注意：如果正在创建 CSP 文件）,则 doc-name 的值包括 /（斜杠）字符.这就是定义 PutDoc 的 URLMap contains the name of this parameter (.*) 而不是 :docname 的原因.

URL Parameters

可以传递 URL 参数 ?ignoreConflict=1 以绕过 ETAG 检查.This forces the source code files to be written to the server,Even if the file has changed since your previous access.

HTTP Headers

• If-None-Match - To ensure the correct version of the file is overwritten,请指定 If-None-Match header as well as before PutDoc 或 GetDoc 的 ETAG The timestamp value returned in the header.

JSON Messages

Below is the source code file 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": []
  }
}

when a class is saved,PutDoc Always return to the storage section,Because it may be normalized by the server.If the content is only the storage part,则 'flags' json 字段将为 1.如果 PutDoc Returns the entire class in content or the content is empty,则“标志”将为 0.

HTTP 返回码

• HTTP 200（if updated）.
• HTTP 201（如果已创建）.
• If the resource name is an invalid source code filename,则返回 HTTP 400.
• 如果找不到资源,则返回 HTTP 404.
• If a conflict between server and client versions is detected based on timestamps,则 HTTP 409.如果文件存在,PutDoc 将返回此代码,除非 If-None-Match The header specifies the current timestamp value of the file on the server.如果存在冲突,The return message contains the content of the source code file on the server.
• 如果未将 text/plain Passed as content type,则 HTTP 415.
• If the source code file is locked and cannot be written,则 HTTP 425.
• HTTP 500 如果发生意外错误（详细信息将在状态错误数组中）.

GetDoc

This method returns the text naming the source code file and namespace.

The returned content will contain a source code file object.

Errors related to source code files will be in the status property of the source code file object.If source control hooks are enabled for the namespace,then any console output generated by the hook will be captured and used as “控制台”An array of rows in an array is returned.

The result contains the name of the requested file、A database for storing files、Timestamp and category abbreviation (CLS = class; RTN = routine; CSP = CSP file;OTH = other),and the source code file contents returned as an array.

• 对于文本文件,This will be an array of strings,并且“enc”json 字段将设置为 false.
• 对于二进制文件,这将是一个 base64 An array of encoded blocks,并且“enc”字段将设置为 true.

版本 2 GetDoc 可以以 UDL 格式（默认）、XML format or old %RO The format used by the export utility returns the file contents.

URL

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

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

注意：If getting CSP 文件,则 doc-name 的值包括 /（斜杠）字符.这就是定义 GetDoc 的 URLMap contains the name of this parameter (.*) 而不是 :docname 的原因.有关详细信息,请参阅创建 REST 服务中的“为 REST 创建 URL 映射”.

URL Parameters

• 可以传递 URL 参数 ?binary=1 to force source code files to be encoded as binary.
• 可以传递 URL 参数 ?storageOnly=1 to return only the stored part of the class.
• 在版本 2 中,可以传递 URL 参数 ?format= parameter to specify should be UDL 格式（默认）、XML format or old %RO The format used by the export utility returns the contents of the file.
  • ?format=udl
  • ?format=xml
  • ?format=%RO

如果指定 ?binary=1,GetDoc The format parameter will be ignored.

HTTP Headers

• If-None-Match - Specifies the last call to this file GetDoc 或 PutDoc 时在 HTTP ETAG The value returned in the header.If the file has not changed since the last call,GetDoc 将返回 HTTP 304 状态.

JSON Messages

以下是请求 %Api.DocDB.cls Returns an example of the first part of the result：

{
    
  "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 result of the same request：

{
    
  "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 如果正常.
• If the source code file has not been modified,则为 HTTP 304（请参阅 https://en.wikipedia.org/wiki/HTTP_ETag）.
• If the named resource is not a valid source code filename,则返回 HTTP 400.
• 如果The source code file does not exist,则返回 HTTP 404.
• HTTP 500 如果发生意外错误（详细信息将在状态错误数组中）.

如果发生“soft”错误,例如“The source code file does not exist”,can be found in the result“状态”Additional information can be found in the fields.Examples of other soft errors include“文件已锁定”.例如,可以使用 HTTP 404 The return code returns the following：

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