--- title: ZEPETO.Multiplay.HttpService slug: world-sdk-guide-ch/zepetomultiplayhttpservice docTags: createdAt: 2026-09-04T05:17:29.368Z --- | 类型 | 说明 | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [HttpContentType](./#httpcontenttype) | 用于指定 HTTP Content-Type 的常量枚举。 | | [HttpBodyType](./#httpbodytype) | HTTP 请求体内容的类型别名，可以是纯文本或键值对象。 | | [HttpHeader](./#httpheader) | HTTP 请求头的类型别名，表示一个键值对象。 | | [HttpErrorType](./#httperrortype) | 用于指定 HTTP 请求失败原因的常量枚举。 | | [HttpError](./#httperror) | 表示 HTTP 请求过程中发生的错误。 | | [HttpResponse](./#httpresponse) | 表示 HTTP 响应。 | | [HttpService](./#httpservice) | `HttpService` 提供用于与外部 Web 服务建立 HTTP 连接并发起请求的 API。 - 请确保使用 HTTPS 协议；HTTP 仅在开发环境中受支持。 - 请求仅限于 80 和 443 端口。 - 请求体和响应体的最大大小为 16KB。 - 请将每分钟请求数控制在 500 以下，以免因请求过多导致 World 服务受到限制。 - 若外部 Web 服务未在 5 秒内响应，请求将失败。 - 请确保响应头中的 Content-Type 与 `HttpContentType` 枚举中定义的值一致，以避免请求失败。 - 由于 Web 请求可能因各种原因失败，建议采用防御性编程。 | ## HttpContentType `enum` 用于指定 HTTP Content-Type 的常量枚举。 | 名称 | 值 | 说明 | | --------------------- | ----------------------------------- | ------------------------------------------ | | ApplicationJson | "application/json" | 表示 application/json 内容类型。 | | ApplicationXml | "application/xml" | 表示 application/xml 内容类型。 | | ApplicationUrlEncoded | "application/x-www-form-urlencoded" | 表示 application/x-www-form-urlencoded 内容类型。 | | TextPlain | "text/plain" | 表示 text/plain 内容类型。 | | TextXml | "text/xml" | 表示 text/xml 内容类型。 | ## HttpBodyType `delegate` HTTP 请求体内容的类型别名，可以是纯文本或键值对象。 `string | { [key: string]: any; }` ## HttpHeader `delegate` HTTP 请求头的类型别名，表示一个键值对象。 `{ [key: string]: string | number; }` ## HttpErrorType `enum` 用于指定 HTTP 请求失败原因的常量枚举。 | 名称 | 值 | 说明 | | --------------------- | ----------------------- | ---------- | | ERR\_ACCESS\_DENIED | "ERR\_ACCESS\_DENIED" | 错误：访问被拒绝。 | | ERR\_LENGTH\_REQUIRED | "ERR\_LENGTH\_REQUIRED" | 错误：需要指定长度。 | ## HttpError `interface` · extends `Error` 表示 HTTP 请求过程中发生的错误。 ### 属性 | 名称 | 类型 | 说明 | | ------- | -------- | ------------------------------- | | message | `string` | 错误消息。 | | code | `string` | 以 `HttpErrorType` 枚举中的值定义的错误代码。 | ## HttpResponse `interface` 表示 HTTP 响应。 ### 属性 | 名称 | 类型 | 说明 | | ---------- | -------- | ---------------------------------------------------------------------- | | statusCode | `number` | 响应的状态码。通常 200 表示请求成功。 | | statusText | `string` | 与状态码相对应的状态消息。通常 "OK" 表示请求成功。 | | response | `string` | HTTP 响应的正文，其格式可能因响应的 Content-Type 而异。建议根据实际接收到的 Content-Type 使用相应的解析器。 | ## HttpService `interface` `HttpService` 提供用于与外部 Web 服务建立 HTTP 连接并发起请求的 API。 - 请确保使用 HTTPS 协议；HTTP 仅在开发环境中受支持。 - 请求仅限于 80 和 443 端口。 - 请求体和响应体的最大大小为 16KB。 - 请将每分钟请求数控制在 500 以下，以免因请求过多导致 World 服务受到限制。 - 若外部 Web 服务未在 5 秒内响应，请求将失败。 - 请确保响应头中的 Content-Type 与 `HttpContentType` 枚举中定义的值一致，以避免请求失败。 - 由于 Web 请求可能因各种原因失败，建议采用防御性编程。 ### 方法 ### getAsync `getAsync(url: string, headers?: HttpHeader) → Promise` 以异步方式执行 HTTP GET 请求。会抛出 `HttpError`。 | 参数 | 类型 | 说明 | | ------------ | --------------------------- | ------------- | | url | `string` | 发送请求的目标网址。 | | headers （可选） | [HttpHeader](./#httpheader) | HTTP 请求头。（可选） | **返回值：** `Promise` — 处理完成时兑现的 `Promise`，携带 `HttpResponse` 对象。 ### postAsync `postAsync(url: string, body: HttpBodyType, headers?: HttpHeader) → Promise` 以异步方式执行 HTTP POST 请求。会抛出 `HttpError`。 | 参数 | 类型 | 说明 | | ------------ | ------------------------------- | ------------- | | url | `string` | 发送请求的目标网址。 | | body | [HttpBodyType](./#httpbodytype) | 请求体内容。 | | headers （可选） | [HttpHeader](./#httpheader) | HTTP 请求头。（可选） | **返回值：** `Promise` — 处理完成时兑现的 `Promise`，携带 `HttpResponse` 对象。 ### postAsync `postAsync(url: string, body: HttpBodyType, httpContentType: HttpContentType, headers?: HttpHeader) → Promise` 以异步方式执行 HTTP POST 请求。会抛出 `HttpError`。 使用该签名时，即便在 headers 中添加 'Content-Type'，也会被 `httpContentType` 中指定的值覆盖。 | 参数 | 类型 | 说明 | | --------------- | ------------------------------------- | ----------------------- | | url | `string` | 发送请求的目标网址。 | | body | [HttpBodyType](./#httpbodytype) | 请求体内容。 | | httpContentType | [HttpContentType](./#httpcontenttype) | 指定请求的 Content-Type 请求头。 | | headers （可选） | [HttpHeader](./#httpheader) | HTTP 请求头。（可选） | **返回值：** `Promise` — 处理完成时兑现的 `Promise`，携带 `HttpResponse` 对象。