> For the complete documentation index, see [llms.txt](https://chaoses-ib.gitbook.io/directory-opus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chaoses-ib.gitbook.io/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/httprequest.zh.md).

# HTTPRequest

**HTTPRequest** 对象允许您轻松地向远程 Web 服务器发送异步 HTTP 请求并接收和处理响应。

此对象是通过 [Dialog](/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/dialog.zh.md) 对象的 `NewHTTPReq` 方法创建的，因此需要 [脚本对话框](/directory-opus/guan-fang-shou-ce/readme.zh-8/readme.zh-4.md)才能使用。对话框还必须是 [分离的](/directory-opus/guan-fang-shou-ce/readme.zh-8/readme.zh-4/readme.zh/detached_dialogs.zh.md)。

使用此对象的通用过程如下：

1. 创建 **HTTPRequest** 对象
2. 添加任何必需的标头
3. 根据需要添加 POST 数据或 GET 查询名称/值对
4. 发送请求
5. 在您的消息循环中处理 "http" 事件
6. 当您收到 "data" 事件时，读取任何返回的数据。

| 属性名称         | 返回类型     | 描述                                                                                                                                                                                                                                                                                                                                                            |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contenttype  | *string* | 当收到响应时，返回 Content-Type 响应标头的值。                                                                                                                                                                                                                                                                                                                                |
| complete     | *bool*   | 当请求完成（并且所有数据都已收到）时返回 True。                                                                                                                                                                                                                                                                                                                                    |
| errorcode    | *int*    | 返回错误代码（如果有）。                                                                                                                                                                                                                                                                                                                                                  |
| errortext    | *string* | 返回错误消息（如果有）。                                                                                                                                                                                                                                                                                                                                                  |
| id           | *int*    | 返回请求的 ID。此 ID 在创建请求时自动分配。如果您一次使用多个请求，则需要此 ID。                                                                                                                                                                                                                                                                                                                 |
| response     | *string* | 返回 HTTP 响应消息。                                                                                                                                                                                                                                                                                                                                                 |
| responsecode | *int*    | 返回 HTTP 响应代码（例如 200、404）。                                                                                                                                                                                                                                                                                                                                     |
| status       | *string* | <p>返回请求的当前状态。当您在消息循环中检索 HTTP 消息时，这也会通过 <a href="/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/msg.zh.md"><strong>Msg</strong></a><strong>.value</strong> 属性提供。有效的状态值是：notready、ready、pending、data、complete、error、shutdown。</p><p>状态值为 "data" 表示响应已收到，并且数据可供读取。状态值为 "complete" 表示响应已完成（例如 HEAD 请求不会返回任何数据，因此在这种情况下您会查找 "complete"）。</p> |

| 方法名称               | **参数**                                                                                                                                                     | 返回类型                                                                          | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Abort              | *none*                                                                                                                                                     | *none*                                                                        | <p>如果请求尚未返回任何数据，则中止请求，并删除您添加的任何标头和发布数据。</p><p>调用此方法会将 <code>HTTPRequest</code> 对象重置为其初始状态，这意味着它可以重新用于发送另一个请求。</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| AddHeader          | <p>\<string:name><br>\<string:value><br><em>或</em><br><<strong>Map</strong>:headers></p>                                                                   | *none*                                                                        | 向 HTTP 请求添加一个或多个标头。您可以提供两个字符串（名称和值），也可以提供一个名称 -> 值对的 [Map](/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/map.zh.md) 来一次添加多个标头。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| AddPostData        | <p>\<string:name><br>\<value><br>\[\<string:contenttype>]<br>\[\<string:filename>]<br>\[\<string::encoding>] <em>或</em><br><<strong>Map</strong>:data></p> | *none*                                                                        | <p>向请求的 POST 数据添加一个或多个名称/值对。您可以提供两个参数的名称和值，在这种情况下，您还可以选择提供内容类型字符串。或者，您可以提供一个名称 -> 值对的 <a href="/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/map.zh.md">Map</a>。发布数据元素的 <em>value</em> 可以是字符串，也可以是 <a href="/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/blob.zh.md">Blob</a> 对象来提供二进制数据。</p><p>如果您只添加了一项 POST 数据，您可以将名称留空（传递空字符串）。这可以让您例如以 JSON 格式发布数据 - 将 <em>name</em> 设置为空字符串，将 <em>value</em> 设置为字符串形式的 JSON 数据，并将 <em>contenttype</em> 设置为 <code>application/json</code>。</p><p>如果添加 <strong>Blob</strong>，您可以提供 <em>filename</em> 参数，该参数为接收系统提供一个建议的存储文件的文件名。您还可以指定 <em>encoding</em> 类型 - 设置为 "base64" 以将 <strong>Blob</strong> 作为 base64 编码的数据发送（否则默认情况下将作为二进制数据发送）。如果您已对数据进行了编码，您可以指定另一个编码类型，该类型将作为 <em>Content-Transfer-Encoding</em> 标头的值传递。</p><p>如果您传递 <strong>Blob</strong> 对象，或者 <strong>Map</strong> 包含多个名称/值对，则数据将作为 <code>multipart/form-data</code> 发送。</p> |
| AddQueryData       | <p>\<string:name><br>\<string:value><br><em>或</em><br><<strong>Map</strong>:data></p>                                                                      | *none*                                                                        | 向请求的 QUERY 数据添加一个或多个名称/值对。您可以提供两个参数的名称和值，也可以提供一个名称 -> 值对的 [Map](/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/map.zh.md)。查询数据将自动进行 URL 编码，并在发送请求时附加到请求字符串。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| GetResponseHeaders | *none*                                                                                                                                                     | **Map**                                                                       | 在收到响应数据后，返回一个包含名称 -> 值对的 [Map](/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/map.zh.md)，其中包含响应标头。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ReadResponse       | *none*                                                                                                                                                     | <p><em>string</em> 或<br><strong>Image</strong> 或<br><strong>Blob</strong></p> | <p>在收到响应后（即您的消息循环收到一个值为 "data" 的 "http" 消息），您可以调用此函数来读取返回的数据。请注意，此函数将阻塞，直到所有数据都收到。</p><p>该函数尝试根据响应中的 Content-Type 标头自动解释返回的数据。如果可能，文本数据将转换为字符串。如果它是 Opus 识别的格式，图像数据将作为 <a href="/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/image.zh.md">Image</a> 对象返回。否则，将返回包含响应数据的 <a href="/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/blob.zh.md">Blob</a>。</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ReadResponseData   | \[\<int:size>]                                                                                                                                             | **Blob**                                                                      | <p>使用此函数而不是 <code>ReadResponse</code> 来读取响应中的原始数据，而无需尝试解释它。数据将作为 <a href="/directory-opus/guan-fang-shou-ce/readme.zh-10/readme.zh-3/readme.zh/blob.zh.md">Blob</a> 对象返回。</p><p>您可以指定要读取的最大数据量（以字节为单位）。如果请求的大小可用，则将返回该大小；否则，该函数将立即返回尽可能多的数据。如果您将 <em>size</em> 指定为 0，或者没有指定大小，则该函数将阻塞，直到整个响应都收到。如果您将 <em>size</em> 指定为 -1，则该函数将返回尽可能多的数据，但不会阻塞。</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| SendRequest        | <p>\<string:url><br>\[\<string:action>]</p>                                                                                                                | *none*                                                                        | <p>将 HTTP 请求发送到指定的 Web 服务器。<em>url</em> 参数应该是要检索的完整 URL（例如 <code><https://www.gpsoft.com.au></code>）。如果您使用 <code>AddQueryData</code> 方法添加了任何查询参数，这些参数将自动附加。</p><p>默认情况下，HTTP 操作将根据对象的 state 自动选择 - 如果使用了 <code>AddPostData</code> 则为 <code>POST</code>，否则为 <code>GET</code>。如果您愿意，您可以使用可选的 <em>action</em> 参数覆盖此操作 - 例如，指定 <code>HEAD</code> 只检索标头，不返回任何响应数据。</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| SetTimeout         | \<int:seconds>                                                                                                                                             | *none*                                                                        | 指定超时时间（以秒为单位）（默认值为 30 秒）。如果在指定时间内未收到完整的响应，则阻塞的函数（如 `ReadResponse`）将超时。设置为 0 表示不超时。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| SetUserAgent       | \<string:agent>                                                                                                                                            | *none*                                                                        | 指定请求的 User-Agent 字符串（如果需要）。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Shutdown           | *none*                                                                                                                                                     | *none*                                                                        | <p>调用此方法关闭请求并释放任何关联的资源。如果请求仍然未完成，则会中止该请求。调用此函数后，您将无法查询请求以获取任何其它数据，除了 <code>complete</code> 属性。</p><p>您无需调用此函数，但如果您使用大量请求，您可能希望在请求完成后调用它以释放内存。</p><p>在调用 <code>Shutdown</code> 后，请求对象将无法再使用。请注意，即使在调用 <code>Shutdown</code> 后，来自请求的消息可能仍然存在于您的对话框的消息队列中 - 最佳做法是在使用任何其它方法或属性之前检查 <code>complete</code> 属性。</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
