# web.rest.client 库模块帮助文档
说明

如果 URL 模板中的变量出现在 URL 路径中， 那么实际调用接口时被应用到 URL 路径中的模板实参内的中文字符 默认会自动以 UTF-8 编码并 URLEncode 编码发送，这是标准方式与具体的页面编码无关。 如果需要在 URL 内使用非 UTF-8 编码（不太可能有这种情况）， 可事先对模板实参进行 URL 编码以去掉中文字符。 放在下标内的字符串 HTTP 方法名仅表示网址资源名称，不会被声明为 HTTP 请求方法。 例如 restApi["get"] 这里的 `get` 仅表示网址中的 `/get`而非 HTTP 请求方法 `GET`。

[必读：web.rest 使用指南](https://www.aardio.com/zh-cn/doc/library-guide/std/web/rest/client.html) ## web.rest 成员列表 # ### web.rest.client # REST客户端 创建 REST 客户端。 ### web.rest.client() # [返回对象:webRestClientObject](#webRestClientObject) ### web.rest.client(config) # 创建 REST 客户端。 可选用一个表参数指定 API 自定义的配置项。 参数存为对象的 config 属性。 参数 config 的 userAgent,proxy,proxyBypass,flags 字段将作为 web.rest.client 构造参数。 ### web.rest.client(userAgent,proxy,proxyBypass,httpFlags) # 创建 REST 客户端，所有参数可选。 userAgent 参数用于自定义 User-Agent 请求标头，用于服务器识别请求程序特征。 HTTP 代理服务器请指定为 "代理服务器地址:端口" 格式， proxy 参数指定代理，proxyBypass 参数指定绕过代理的主机。 └── [代理参数格式说明](https://www.aardio.com/zh-cn/doc/library-guide/std/inet/proxy.html) httpFlags 可选用一个数值指定 HTTP 连接选项，一般不需要指定。 可选传入一个表指定以上参数以及其他 API 自定义设置。 如果传入表参数则存为对象的 config 属性。 ## webRestApiObject 成员列表 # ### webRestApiObject.* # 可输入任意 HTTP API 资源名。 返回一个 HTTP API 调用对象。 对 API 调用对象可以使用成员操作符继续获取下级资源， 也可以将其作为函数对象直接调用并自动发送 HTTP 请求。 作为函数调用时成功返回解析后数据，失败返回 null,错误信息,错误代码。 调用参数 @1 可选用表对象指定请求参数，也可直接用字符串指定请求参数。 可选用参数 @2 指定 URL 参数（包含名值对的表或字符串）。 可选用参数 @2 或 @3 指定 inet.http 对象的 onReceive 回调函数。 指定 onReceive 回调函数则自动支持自动解析 SSE 流，兼容 ndjson 流。。 onReceive 回调函数如果返回 false 则停止接收数据。 [返回对象:webRestApiObject](#webRestApiObject) ### webRestApiObject.delete() # DELETE 方法（HTTP method）提交请求，删除资源。 注意下标操作符内的"delete"仅表示资源名（`restApi["delete"]`）， 不会被识别为 HTTP 请求方法。 请求参数 @1 可以指定表或字符串、缓冲区（表对象在请求前会编码为字符串）。 可选用参数 @2 指定 URL 参数（包含名值对的表或字符串）。 可选用参数@3指定inet.http对象的onReceive回调函数 如果资源URL名称需要用到 delete，请使用["/delete"]替代以避免被识别为默认HTTP方法 ### webRestApiObject.deleteDelete() # 返回 HTTP API 调用对象， URL 资源名称与 HTTP 请求方法都设为 "delete"。 这是 delete["delete"] 的缩略写法 [返回对象:webRestApiObject](#webRestApiObject) ### webRestApiObject.get() # 使用 HTTP 协议的 GET 方法（HTTP method）提交 HTTP 请求。 注意下标操作符内的"get"仅表示资源名（`restApi["get"]`）， 不会被识别为 HTTP 请求方法。 成功返回解析后数据，失败返回 null,错误信息,错误代码。 调用参数 @1 可选用表对象指定请求参数，也可直接用字符串指定请求参数。 可选用参数 @2 指定 URL 参数（包含名值对的表或字符串）。 可选用参数 @2 或 @3 指定 inet.http 对象的 onReceive 回调函数。 指定 onReceive 回调函数则自动支持自动解析 SSE 流，兼容 ndjson 流。。 onReceive 回调函数如果返回 false 则停止接收数据。 [返回对象:webRestApiObject](#webRestApiObject) ### webRestApiObject.getGet() # 返回 HTTP API 调用对象， URL 资源名称与 HTTP 请求方法都设为 "get"。 这是 get["get"] 的缩略写法 [返回对象:webRestApiObject](#webRestApiObject) ### webRestApiObject.getUrl() # 返回当前对象发送请求使用的 URL 地址， 如果有远程函数与此函数同名，写为 ["getUrl"] 即可。 ### webRestApiObject.head() # HEAD方法提交请求 如果该函数返回非null值为成功,请使用 readHeader获 取应答HTTP头 请求参数可以指定表或字符串（表对象在请求前会编码为字符串）。 ### webRestApiObject.headHead() # 返回 HTTP API 调用对象， URL 资源名称与 HTTP 请求方法都设为 "head"。 这是 head["head"] 的缩略写法 [返回对象:webRestApiObject](#webRestApiObject) ### webRestApiObject.patch() # PATCH 方法（HTTP method）提交请求，更新资源。 注意下标操作符内的"patch"仅表示资源名（`restApi["patch"]`）， 不会被识别为 HTTP 请求方法。 请求参数@1可以指定表或字符串、缓冲区（表对象在请求前会编码为字符串）。 可选用参数 @2 指定 URL 参数（包含名值对的表或字符串）。 可选用参数@3指定inet.http对象的onReceive回调函数 ### webRestApiObject.patchPatch() # 返回 HTTP API 调用对象， URL 资源名称与 HTTP 请求方法都设为 "patch"。 这是 patch["patch"] 的缩略写法 [返回对象:webRestApiObject](#webRestApiObject) ### webRestApiObject.post() # 使用 HTTP 协议的 POST 方法（HTTP method）提交 HTTP 请求。 注意下标操作符内的"post"仅表示资源名（`restApi["post"]`）， 不会被识别为 HTTP 请求方法。 成功返回解析后数据，失败返回 null,错误信息,错误代码。 调用参数 @1 可选用表对象指定请求参数，也可直接用字符串指定请求参数。 可选用参数 @2 指定 URL 参数（包含名值对的表或字符串）。 可选用参数 @2 或 @3 指定 inet.http 对象的 onReceive 回调函数。 指定 onReceive 回调函数则自动支持自动解析 SSE 流，兼容 ndjson 流。。 onReceive 回调函数如果返回 false 则停止接收数据。 [返回对象:webRestApiObject](#webRestApiObject) ### webRestApiObject.postPost() # 返回 HTTP API 调用对象， URL 资源名称与 HTTP 请求方法都设为 "post"。 这是 post["post"] 的缩略写法 [返回对象:webRestApiObject](#webRestApiObject) ### webRestApiObject.put() # PUT 方法（HTTP method）提交请求，替换或更新资源。 注意下标操作符内的"put"仅表示资源名（`restApi["put"]`）， 不会被识别为 HTTP 请求方法。 请求参数 @1 可以指定表或字符串、缓冲区（表对象在请求前会编码为字符串）。 可选用参数 @2 指定 URL 参数（包含名值对的表或字符串）。 可选用参数@3指定inet.http对象的onReceive回调函数 ### webRestApiObject.putPut() # 返回 HTTP API 调用对象， URL 资源名称与 HTTP 请求方法都设为 "put"。 这是 put["put"] 的缩略写法 [返回对象:webRestApiObject](#webRestApiObject) ### webRestApiObject.receiveFile # 配置下次下载文件的参数， 此配置在后续用 get,post 等函数提交请求后自动清空 此函数成功返回对象自身，创建文件失败返回 null,错误信息 ### webRestApiObject.receiveFile() # [返回对象:webRestApiObject](#webRestApiObject) ### webRestApiObject.receiveFile(savePath,callback,saveDir) # 配置下次下载文件的参数， 此配置在后续用 get,post 等函数提交请求后自动清空 此函数返回对象自身 @savePath 参数指定下载文件路径， 可选用 @saveDir 指定下载根目录，指定此参数则参数 @1 应为相对路径。 可选用 @callback 参数指定下载进度回调函数, 进度回调函数参数依次为 recvData,recvSize,contentLength， 其中 recvData 为本次下载的数据， recvSize 为本次下载的字节数， contentLength 为需要下载的总字节数 ### webRestApiObject.sendFile("上传文件路径",进度回调函数,MIME,分块大小) # ```aardio webRestApiObject.sendFile( "上传文件路径" ,function(sendData,sendSize,contentLength,remainSize){ /*上传进度回调函数以及其他参数都可以省略， 如果打开文件失败，sendFile 函数返回 null 与错误信息， 否则返回响应数据*/ } ); ``` ### webRestApiObject.sendMultipartForm(上传字段表,进度回调函数,分块大小) # ```aardio webRestApiObject.sendMultipartForm( { file = "@/*上传文件路径字前必须添加@字符， 上传表单可添加多个字段， 上传进度回调函数以及其他参数都可以省略*/" },function(sendData,sendSize,contentLength,remainSize){ ..io.print("正在上传",sendSize,contentLength); } ); ``` ## webRestClientObject 成员列表 # ### webRestClientObject.* # web.rest.client 或继承自 web.rest.client 的对象的其他成员函数或属性。 请查看相关库函数文档或源码 ### webRestClientObject._http # inet.http客户端，用于执行 http 请求 [返回对象:inetHttpObject](https://www.aardio.com/zh-cn/doc/library-reference/inet/http.html#inetHttpObject) ### webRestClientObject.acceptType # 期望返回的MIME内容类型,多个类型用逗号分隔 ### webRestClientObject.afterSend # ```aardio webRestClientObject.afterSend = function(statusCode,contentLength){ /*向服务器发送数据结束触发此回调函数*/ var server = webRestClientObject._http.readHeader("Server:"); } ``` ### webRestClientObject.afterStringifyRequestParameters(提交数据,代码页) # ```aardio webRestClientObject.afterStringifyRequestParameters = function(payload,codepage){ /*此函数总是在请求之前被回调。 如果存在 params 参数，则 payload 已转换为字符串并准备提交到服务器（可能为 null 或 ""）。 codepage 参数为请求数据使用的代码页。 在该函数中可获取或修改对象的 lastRequestUrl, lastRequestMethod 属性。 必须用第一个返回值返回新的 params 。 此函数如果第一个返回值为 null， 且第二个返回值非 null， 则会终止调用并返回前 3 个返回值。*/ return payload; } ``` ### webRestClientObject.api # 定义API对象，使用成员操作符或下标获取API对象的成员时将会自动转换为新的API对象 ### webRestClientObject.api("/路径") # 如果客户端使用 defaultUrlTemplate 属性指定了默认网址模板。 则这里的第一个参数可以省略，或者仅指定以 `/` 或 `.` 字符开始的路径。 ### webRestClientObject.api("网址模板","HTTP动词","模式串") # 网址模板可使用 {name}、{/name}、或 {...} 指定模板参数, 大括号内的参数名可使用英文字符或数字, 模板参数名首字符为斜杠（例如{/name}）表示使用实参替换后保留斜杠， {...} 表示不定个数的模板参数,如使用多个实参替换则自动使用斜杠拼接， 默认在网址模板尾部自动添加 {...} 返回API对象使用下标指定模板实参， 如果下标是字符串，按下标出现的前后顺序替换模板参数， 如果下标是表对象，则表中的键值对用于替换与键同名的模板参数, 可选用参数@2指定HTTP动词,默认值为"POST" 参数@3如果为模式串，则使用模式匹配转换响应数据并返回。 参数@3如果为函数，则调用该函数转换转换响应数据并返回。 参数@3如果为数组，则作为string.map的模式参数@2转换响应数据并返回 ### webRestClientObject.api("网址模板","HTTP动词","模式串",HTTP选项) # 可选使用参数 @4 指定 _INTERNET_FLAG_ 前缀常量自定义 HTTP 请求选项。 其他参数用法同上 ### webRestClientObject.api() # [返回对象:webRestApiObject](#webRestApiObject) ### webRestClientObject.beforeRequestHeaders(提交参数,提交数据,请求网址,请求方法,请求类型) # ```aardio webRestClientObject.beforeRequestHeaders = function(params,payload,url,httpMethod,contentType){ /*每次请求前都会触发此函数。 params 参数为本次请求的提交参数， payload 为转换为字符串格式的提交数据（无数据传入 "" 而不是 null） url 参数为本次请求网址。 httpMethod 参数为 HTTP 方法（大写）。 contentType 参数为请求内容类型。 可选以字符串、数组、键值等 web.joinHeaders 函数支持的格式返回 HTTP 头。 */ return {}; } ``` ### webRestClientObject.beforeSend # ```aardio webRestClientObject.beforeSend = function(){ /*已准备向服务器发送数据触发此回调函数*/ } ``` ### webRestClientObject.beforeStringifyRequestParameters(提交参数,代码页) # ```aardio webRestClientObject.beforeStringifyRequestParameters = function(params,codepage){ /*可以在该函数中修改提交提交参数表，或在此添加默认参数。 此函数在 stringifyRequestParameters 之前调用， 参数可能是 null、字符串或者表。 在该函数中可获取或修改对象的 lastRequestUrl, lastRequestMethod 属性。 此函数如果第一个返回值为 null， 且第二个返回值非 null， 则会终止调用并返回前 3 个返回值。*/ return params; } ``` ### webRestClientObject.charset # 指定服务端使用的编码,默认为"UTF-8", 服务端HTTP响应头里如果显式指定了编码，会自动修改此属性 对于服务端返回的数据,会根据charset自动转换为aardio默认的UTF8编码 对于请求参数,如果使用JSON编码统一转换为Unicode编码格式,不需要考虑编码转换, 如果使用UrlEncode编码与浏览器的规则一致，根据charset转换为对应编码后提交， 开发服务端接口应统一使用UTF8编码,可避免任何乱码问题 ### webRestClientObject.checkResponseResult(result) # ```aardio webRestClientObject.checkResponseResult = function(result){ if(result[["errcode"]]==40014){ var lastRequestInfo = http.lastRequestInfo; /*此函数在成功解析服务器响数数据后会被自动调用， 可在此函数中检查 token 是否过期并重新发送请求*/ return http.requestEx(lastRequestInfo); } return result; } ``` ### webRestClientObject.close() # 关闭对象释放资源 ### webRestClientObject.config # 自定义的 API 配置表。 默认指向创建对象时指定的表参数。 如果构造对象未指定表参数，此配置默认为 null 值。 ### webRestClientObject.contentType # 写入HTTP头ContentType属性的内容类型 设为null空值,或每次请求完成将自动重置为defaultContentType ### webRestClientObject.defaultContentType # 默认内容类型 ### webRestClientObject.defaultHeaders # 替换所有请求默认添加的HTTP头 请求结束时不会清空此属性 该值可以是一个字符串,也可以是键值对组成的table对象 ### webRestClientObject.defaultHttpMethod # 默认 HTTP 请求方法。 调用 api 方法时如果未指定参数 @2 则使用此值。 此属性的默认值为 "POST" ### webRestClientObject.defaultUrlTemplate # 默认 API 网址模板。 调用 api 方法时如果未指定参数 @1 则使用此值。 ### webRestClientObject.delete(网址,参数表) # 使用该 DELETE 方法提交请求,删除资源 请求参数可以指定表或字符串（表对象在请求前会编码为字符串）。 成功返回数据,失败返回空值,错误信息,错误代码 ### webRestClientObject.encodeKey # 自定义替换 API 网址变量值使用的编码函数, 此函数接收一个资源名参数,返回编码后的资源名, 必须在定义 API 对象之前指定, 默认已指定为 inet.url.encodeMbcs 函数。 如果在调用声明的 HTTP API 时传入多项索引，则资源名参数是纯数组。 默认的 encodeKey 并不支持纯数组，此功能预留于继承类实现其他功能。 ### webRestClientObject.endRequest() # 可用于afterSend事件提前结束当前请求 ### webRestClientObject.extraParameters # 指定附加到所有请求参数表中的默认附加参数表，此属性必须是 null 或者表对象。 调用 HTTP API 接口时，请求参数指定表对象时或为 null 才会附加 extraParameters 属性指定的参数。 不会用附加参数表覆盖请求参数表中已存在的字段。 如果请求参数表与附加参数表中都已存在同名字段，并且值也是一个表时会合并子表的值。 仅合并第一层子表，合并子表时也不会覆盖已存在的值。 ### webRestClientObject.extraUrlParameters # 指定附加到所有请求 URL 的默认参数。 该值可以是一个表或字符串。 表参数使用 inet.url.stringifyParameters 转换为字符串。 表中的值如果是函数则每次请求都调用该函数取值 ### webRestClientObject.get(网址,参数表) # 使用 该 GET 方法提交请求,获取资源 请求参数将会自动转换为URL附加参数, 请求参数可以指定表或字符串（表对象在请求前会编码为字符串）。 成功返回数据,失败返回空值,错误信息,错误代码 ### webRestClientObject.get(网址,参数表,接收数据回调函数) # 使用该 GET 方法提交请求,获取资源 请求参数将会自动转换为URL附加参数, 请求参数可以指定表或字符串（表对象在请求前会编码为字符串）。 如果服务端返回内容类型为 text/event-stream， 则接收数据回调函数的参数为解析服务端每次推送数据的表对象， 否则回调参数依次为：当前响应数据，本次响应数据长度，响应数据总长度。 回调函数如果返回 false 则停止接收数据。 ### webRestClientObject.getUserAgent() # 返回HTTP客户端请求HTTP头中用户代理头的值, 该值可在创建HTTP客户端的构造参数中指定 ### webRestClientObject.head(网址,参数表) # 使用 HEAD 方法提交请求 如果该函数返回非 null 值为成功,请使用 readHeader 获取应答 HTTP 头。 成功返回 true,失败返回 null,错误信息,错误代码 ### webRestClientObject.headGet(网址,参数表) # 使用 GET 方法提交请求，但仅获取 HTTP 头。 如果该函数返回非 null 值为成功,请使用 readHeader 获取应答 HTTP 头 成功返回数据,失败返回空值,错误信息,错误代码 ### webRestClientObject.headPost(网址,参数表) # 使用 POST 方法提交请求，但仅获取 HTTP 头。 如果该函数返回非 null 值为成功,请使用 readHeader 获取应答HTTP头 成功返回数据,失败返回空值,错误信息,错误代码 ### webRestClientObject.httpGet(url,http头,引用网址,MIME) # 调用 _http 属性所指向的 inet.http 对象的 get 方法， 向服务器发送 HTTP GET 请求并直接下载服务器返回的数据（不进行解码）。 除参数 @url 需要指定请求网址,其他均为可选参数（请参考 inet.http 的 get 方法文档）。 本地内部错误返回值为:null,错误信息,错误代码 服务端返回HTTP错误时返回值为:false,错误信息,HTTP错误代码 成功返回字符串对象 ### webRestClientObject.lastRequestInfo # 最后一次请示使用的所有参数信息 ### webRestClientObject.lastRequestMethod # 最后一次请示使用的HTTP方法 ### webRestClientObject.lastRequestUrl # 获取最后一次请求的 URL。 允许的 beforeRequestHeaders 事件中修改此属性以改变请求地址。 ### webRestClientObject.lastResponse() # 获取最后一次服务器返回的数据, 如果控制台已打开或在开发环境中导入 console 库则在控制台输出数据 下载文件时该值为空 ### webRestClientObject.lastResponseContentType # 服务器响应头 Content-Type 的值 ### webRestClientObject.lastResponseError() # 返回服务器最后一次返回的错误响应，并转换为错误对象。 与调用 API 时转换响应数据一样，支持相同的服务器响应格式 。 如果错误来自本地（lastStatusCode 属性为 null）则此函数返回 null 。 如果最后一次发生请求成功，则此函数返回 null 。 如果在参数 @1 中指定返回字段，且错误对象包含该字段则使用直接下标获取并返回字段值。 获取错误对象失败、或格式解析失败、获取字段失败都会返回 null 而非抛出异常 ### webRestClientObject.lastResponseObject() # 获取最后一次服务器返回的对象（已将响应文本解析为对象）， 请求失败，或者下载文件时此属性值为空。 如果是 SSE 流式调用，默认无返回值。 web.rest.aiChat 则在流式调用时会返回最后一次接受的包含 token 计数的对象。 ### webRestClientObject.lastResponseString() # 获取最后一次服务器返回的原始数据， 请求失败，或者下载文件时此属性值为空 ### webRestClientObject.lastStatusCode # 获取最近一次请求返回的HTTP状态码 100 ~ 101 为信息提示 200 ~ 206 表示请求成功 300 ~ 305 表示重定向 400 ~ 415 表求客户端请求出错 500 ~ 505 表示服务端错误 ### webRestClientObject.lastStatusMessage() # 获取最近返回的HTTP状态码文本描述 第二个返回值为状态码 ### webRestClientObject.notify(回调函数) # ```aardio webRestClientObject.notify( function(){ /*在此回调函数中所有请求在发送数据后立即关闭连接*/ } ) ``` ### webRestClientObject.ok() # 最后一次请求是否成功 服务器应答并且状态码为2XX该函数返回真 ### webRestClientObject.parseResponseError(响应数据) # ```aardio webRestClientObject.parseResponseError = function(respError){ /*用于 HTTP 状态码是错误代码时解析服务器应答的错误信息。 此函数一般由库文件定义，一般调用不应修改此函数。 respError 为服务器应答字符串，应返回新的错误信息或错误对象。 此函数不应返回 null 值（避免调用者误判为请求已成功）。 根据 aardio 惯例此函数应返回字符串以避免混淆（除非调用代码明确知道怎么处理）。 lastResponseError 方法也可以用于解析错误响应数据，但不要求返回字符串*/ return owner.parseResponseResult(respError)[["detail"]] || respError; } ``` ### webRestClientObject.parseResponseResult(响应数据,单个流式数据块) # ```aardio webRestClientObject.parseResponseResult = function(resp,streamChunk){ /*用于解析服务器应答数据。 此函数一般由库文件定义，一般调用不应修改此函数。 resp 为服务器应答字符串， streamChunk 指示是否在 SSE 或 ndjson 流回调函数中解析单个块。 HTTP 状态码是错误代码时调用 parseResponseError 而非 parseResponseResult 。*/ } ``` ### webRestClientObject.patch(网址,参数表) # 使用该 PATCH 方法提交请求,更新资源 请求参数可以指定表或字符串（表对象在请求前会编码为字符串）。 成功返回数据,失败返回空值,错误信息,错误代码 ### webRestClientObject.post(网址,参数表) # 使用该 POST方法提交请求,新增或修改资源 请求参数可以指定表或字符串（表对象在请求前会编码为字符串）。 成功返回数据,失败返回空值,错误信息,错误代码 ### webRestClientObject.post(网址,参数表,接收数据回调函数) # 使用该 POST 方法提交请求,新增或修改资源 请求参数可以指定表或字符串（表对象在请求前会编码为字符串）。 如果服务端返回内容类型为 text/event-stream， 则接收数据回调函数的参数为解析服务端每次推送数据的表对象， 否则回调参数依次为：当前响应数据，本次响应数据长度，响应数据总长度。 回调函数如果返回 false 则停止接收数据。 ### webRestClientObject.put(网址,参数表) # 使用该 PUT 方法提交请求,替换或更新资源 请求参数可以指定表或字符串（表对象在请求前会编码为字符串）。 成功返回数据,失败返回空值,错误信息,错误代码 ### webRestClientObject.readHeader # 获取返回的 HTTP 响应头。 可在 afterSend 事件中使用。 ### webRestClientObject.readHeader("Content-Length:") # 获取单个指定的 HTTP 服务器响应头，返回字符串。 参数指定HTTP头名字或部分名字，忽略大小写，忽略冒号以后部分。 如果调用 head, headGet, headPost 等函数。 或调用 或 API 对象的 head.get,head.post 等函数， 则在请求成功后可调用此函数读取 HTTP 头 ### webRestClientObject.readHeader() # 获取返回的 HTTP 响应头。 如果最后一次请求是调用 head, headGet, headPost 等函数， 或调用 或 API 对象的 head.get,head.post 等函数， 或者在 afterSend 事件中无参数调用过 readHeader 事件， 则在请求成功后可调用此函数读取 HTTP 头 ### webRestClientObject.readHeaderList("字符串参数") # 获取所有指定字符串作为开始段的 HTTP 头。 忽略大小写，不忽略冒号以后部分。 不指定参数则读取全部响应头。 返回键值对组成的表对象，键名转为小写，每个值都是一个数组。 如果调用 head, headGet, headPost 等函数。 或调用 或 API 对象的 head.get,head.post 等函数， 则在请求成功后可调用此函数读取 HTTP 头 ### webRestClientObject.receiveFile # 配置下次下载文件的参数， 此配置在后续用 get,post 等函数提交请求后自动清空 此函数成功返回对象自身，创建文件失败返回 null,错误信息 ### webRestClientObject.receiveFile() # [返回对象:webRestClientObject](#webRestClientObject) ### webRestClientObject.receiveFile(savePath,callback,saveDir) # 配置下次下载文件的参数， 此配置在后续用 get,post 等函数提交请求后自动清空 此函数成功则返回对象自身 @savePath 参数指定下载文件路径， 可选用 @saveDir 指定下载根目录，指定此参数则参数 @1 应为相对路径。 可选用 @callback 参数指定下载进度回调函数, 进度回调函数参数依次为 recvData,recvSize,contentLength， 其中 recvData 为本次下载的数据， recvSize 为本次下载的字节数， contentLength 为需要下载的总字节数 ### webRestClientObject.referer # 引用页地址。 如果此属性指定了一个值，则每次请求都会使用该引用页。 如果不指定，每次请求都会自动设置上次请求的网址为引用页。 这个属性不像 inet.http 对象的 referer 属性那样每次请求结束都会清空。 ### webRestClientObject.request # 发送请求, 该函数不会解析URL中的模板参数 ### webRestClientObject.request(网址,参数表,"HTTP动词",URL参数表) # 除参数@1以外，其他所有参数都可以省略, 省略参数@3则使用默认的调用方法 成功返回数据,失败返回空值,错误信息,错误代码 ### webRestClientObject.requestEx(lastRequstInfo) # 用于重新发送请求， 参数必须指定当前对象的lastRequestInfo属性 ### webRestClientObject.responseHeaders # 自定义在每次请求结束后需要读取的 HTTP 响应头。 responseHeaders 如果指定表对象， 则表中的所有键都必须是指定响应头名称的字符串，且不应包含`:`符号 每次发送请求后都会读取同名响应头的值并更新 responseHeaders 表。 注意这个表中只会保存响应头的首个查询值，如果有多个值请改为在 afterSend 事件内读取。 responseHeaders 的默认值为 null（也就是不会自动保存响应头）。 注意 Content-Type 响应头已经默认存于 lastResponseContentType 属性。 ### webRestClientObject.sendFile("上传文件路径",进度回调函数) # ```aardio webRestClientObject.sendFile( "上传文件路径" ,function(sendData,sendSize,contentLength,remainSize){ /*上传进度回调函数以及其他参数都可以省略， 如果打开文件失败，sendFile 函数返回 null 与错误信息， 否则返回响应数据*/ } ); ``` ### webRestClientObject.sendFile() # [返回对象:webRestClientObject](#webRestClientObject) ### webRestClientObject.sendMultipartForm() # [返回对象:webRestClientObject](#webRestClientObject) ### webRestClientObject.sendMultipartForm(上传字段表,进度回调函数) # ```aardio webRestClientObject.sendMultipartForm( { file = "@/*上传文件路径字前必须添加 @ 字符，字段值可指定纯数组。 上传表单可添加多个字段， 上传进度回调函数以及其他参数都可以省略*/" },function(sendData,sendSize,contentLength,remainSize){ } ); ``` ### webRestClientObject.setAuth # 设置登录名,密码，或者设置 API Key 与 Secret Key ### webRestClientObject.setAuth("API Key","Secret Key") # 设置 API Key，Secret Key。 此函数会清空 setAuthToken 设置的认证令牌（token） ### webRestClientObject.setAuth("登录名","密码") # 设置登录名,密码, 默认用于HTTP登录认证 , 支持 Basic , Digest 认证 此函数会清空 setAuthToken 设置的认证令牌（token） ### webRestClientObject.setAuthToken # 设置认证令牌（token） ### webRestClientObject.setAuthToken(token,tokenType) # 设置认证令牌（token）。 @token 可指定令牌，也可以指定返回令牌的网址。 @tokenType 为可选参数，默认为"Bearer"。 如果指定了令牌，则会添加请求头 "Authorization:Bearer 令牌"。 @tokenType 也可以指定为空字符串。 此函数会清空 setAuth 设置的用户名与密码 ### webRestClientObject.setCookie # 调用 inet.setCookie 设置 Cookie 。 所有 web.rest 命名空间的客户端,inet.http,web.form 等共享 cookie 设置。 此函数用法与 inet.setCookie 函数完全相同。 这里仅列出几种常用的参数用法， 其他用法请查看 inet.setCookie 函数说明 如果需要读取 cookie 请直接使用 inet.getCookie 或 inet.getCookieEx 函数 ### webRestClientObject.setCookie(cookieArray) # 设定数组参数指定的多个 Cookie 对象。 如果参数 @cookieArray 为 null 则返回 false ，不会报错。 如果参数 @cookieArray 数组则返回 true 数组中的每个 Cookie 对象都必须是一个表。 - 表中 domain 指定域名, path 指定网站目录（可省略）。 - name 字段（Cookie 名字）与 value 字段（Cookie 值，必须是字符串）至少指定一个。 - expires 字段可不指定（设置会话 Cookie）。 expires 可指定 time.gmt 参数所支持的时间格式，指定数值则表示时间戳。 此数组格式兼容 fsys.cookies 以及 CDP 方法 Network.getCookies 。 ### webRestClientObject.setCookie(params) # ```aardio webRestClientObject.setCookie({ domain = "example.com"; cookies = { name1 = "value1"; name2 = "value2"; }/*使用表参数批量设置 Cookie，参数 @1 不能是数组包含数组成员。 - 可用 url 指定网址,或者用 domain 字段指定域名（可选用 path 字段指定路径）。 - 可选用 expires 字段指定过期时间（可指定 time.gmt 支持的参数），数值表示过期天数。 - cookies 字段必须指定一个包含 Cookie 名值对的表对象（table）。 Cookie 值会自动调用 tostring 转换为字符串。*/ }) ``` ### webRestClientObject.setCookie(urlOrDomain,value,name,expiresOrDays) # 设定指定网址（或域名）的 Cookie。 参数 @1 指定 Cookie 生效的网址，也可以仅指定域名。 如果不指定 @value 则删除删除指定名字的会话 cookie 与持久 Cookie。 如果指定 @value 与 @name 则设置 Cookie。 参数 @value 与 @name 可以合并写为一个 "name=value" 格式的字符串。 如果不指定过期时间则仅设置会话 Cookie，否则设置为持久 Cookie。 可选用 expiresOrDays 指定过期时间（可传入 time.gmt 参数支持的格式），数值表示过期天数 ### webRestClientObject.setCookie(wb) # 参数 @wb 必须指定提供 getCookies 方法的对象， 这通常指的是 web.view。 web.view 提供 getCookies 方法调用 wb.cdp 获取浏览器控件的 Cookies 。 getCookies 可返回 inet.setCookie 支持的参数 @cookieArray 或 @params 也可以返回 null 值（inet.setCookie 也会返回 null,不执行其他操作）。 ### webRestClientObject.setHeaders # 设置所有请求默认添加的HTTP头 ### webRestClientObject.setHeaders(headers) # 参数 @headers 必须指定一个表对象（table）， 用该表中的名值对更新 defaultHeaders 属性中的键值。 如果 defaultHeaders 的原属性值不是一个表对象，则先清空 defaultHeaders ### webRestClientObject.setTimeouts(连接超时,请求超时,接收超时) # 设置超时,以亳秒为单位（1秒为1000毫秒）。 ### webRestClientObject.strictParsing # 对于 JSON 客户端，如果此属性设为 true： 且服务器响应头未声明 JSON 类型，返回数据第一个字符不是 { 也不是 [， 则直接返回包含服务器响应数据的字符串。 此属性值默认为 null ### webRestClientObject.stringifyRequestParameters(提交参数表,代码页) # ```aardio webRestClientObject.stringifyRequestParameters = function(params,codepage){ /*当 HTTP 请求方法不是 `GET` 并且调用参数是表对象， 则调用此函数转换为字符串。 此函数一般由库文件定义，一般调用不应修改此函数 注意返回的文本格式应与 owner.contentType 一致，这里也可以临时修改 contentType 属性。 在该函数中可获取或修改对象的 lastRequestUrl, lastRequestMethod 属性。 此函数如果第一个返回值为 null， 且第二个返回值非 null， 则会终止调用并返回前 3 个返回值。*/ return params; } ``` ### webRestClientObject.tempHeaders # 设置本次请求的临时 HTTP 头。 此属性会在每次发送请求以后重置为空值 该值可以是 web.joinHeaders 函数支持的字符串、表（数组、键值对） ## webRestClientObject 事件列表 # ### webRestClientObject.onAuthenticate # function(authHeader){ __/*请求遇到 401 错误触发此函数, authHeader 为服务器响应HTT头 WWW-Authenticate 的值 登录成功请返回 true 以重新发送上次失败的请求*/ }