Skip to content

节点构建者的 HTTP 请求助手#

¥HTTP request helper for node builders

n8n 提供了一个灵活的 HTTP 请求辅助工具，它抽象化了大部分复杂性。

¥n8n provides a flexible helper for making HTTP requests, which abstracts away most of the complexity.

Programmatic style only

本文档中的信息适用于使用编程方式构建节点。它不适用于声明式节点。

¥The information in this document is for node building using the programmatic style. It doesn't apply to declarative style nodes.

用法#

¥Usage

在 execute 函数中调用辅助函数

¥Call the helper inside the execute function.

1
2
3
4
5
6
7
8
9
// If no auth needed
const response = await this.helpers.httpRequest(options);

// If auth needed
const response = await this.helpers.httpRequestWithAuthentication.call(
	this, 
	'credentialTypeName', // For example: pipedriveApi
	options,
);

options 是一个对象：

¥options is an object:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
	url: string;
	headers?: object;
	method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD';
	body?: FormData | Array | string | number | object | Buffer | URLSearchParams;
	qs?: object;
	arrayFormat?: 'indices' | 'brackets' | 'repeat' | 'comma';
	auth?: {
		username: string,
		password: string,
	};
	disableFollowRedirect?: boolean;
	encoding?: 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream';
	skipSslCertificateValidation?: boolean;
	returnFullResponse?: boolean;
	proxy?: {
		host: string;
		port: string | number;
		auth?: {
			username: string;
			password: string;
		},
		protocol?: string;
	};
	timeout?: number;
	json?: boolean;
}

url 是必需的。其他字段是可选的。默认方法是 GET。

¥url is required. The other fields are optional. The default method is GET.

关于可用字段的一些说明：

¥Some notes about the possible fields:

  • body：你可以使用常规 JavaScript 对象作为 JSON 有效负载，使用缓冲区进行文件上传，使用 FormData 实例作为 multipart/form-data，使用 URLSearchParams 作为 application/x-www-form-urlencoded。

¥body: you can use a regular JavaScript object for JSON payload, a buffer for file uploads, an instance of FormData for multipart/form-data, and URLSearchParams for application/x-www-form-urlencoded.

  • headers：键值对。

¥headers: a key-value pair.

  • 如果 body 是 FormData 的实例，则 n8n 会自动添加 content-type: multipart/form-data。

    ¥If body is an instance of FormData then n8n adds content-type: multipart/form-data automatically.

  • 如果 body 是 URLSearchParams 的实例，则 n8n 会添加 content-type: application/x-www-form-urlencoded。

    ¥If body is an instance of URLSearchParams, then n8n adds content-type: application/x-www-form-urlencoded.

  • 要覆盖此行为，请设置 content-type 标题。

    ¥To override this behavior, set a content-type header.

  • arrayFormat：如果你的查询字符串包含数据数组（例如 const qs = {IDs: [15,17]}），则 arrayFormat 的值定义了 n8n 如何格式化该数组。

¥arrayFormat: if your query string contains an array of data, such as const qs = {IDs: [15,17]}, the value of arrayFormat defines how n8n formats it.

  • indices（默认）：{ a: ['b', 'c'] } 作为 a[0]=b&a[1]=c。

    ¥indices (default): { a: ['b', 'c'] } as a[0]=b&a[1]=c

  • brackets：{ a: ['b', 'c'] } 作为 a[]=b&a[]=c。

    ¥brackets: { a: ['b', 'c'] } as a[]=b&a[]=c

  • repeat：{ a: ['b', 'c'] } 作为 a=b&a=c。

    ¥repeat: { a: ['b', 'c'] } as a=b&a=c

  • comma：{ a: ['b', 'c'] } 作为 a=b,c。

    ¥comma: { a: ['b', 'c'] } as a=b,c

  • auth：用于基本身份验证。提供 username 和 password。n8n 建议你省略此步骤，而改用 helpers.httpRequestWithAuthentication(...) 文件。

¥auth: Used for Basic auth. Provide username and password. n8n recommends omitting this, and using helpers.httpRequestWithAuthentication(...) instead.

  • disableFollowRedirect：默认情况下，n8n 会跟随重定向。你可以将其设置为 true 来阻止这种情况发生。

¥disableFollowRedirect: By default, n8n follows redirects. You can set this to true to prevent this from happening.

  • skipSslCertificateValidation：用于在没有正确证书的情况下调用 HTTPS 服务。

¥skipSslCertificateValidation: Used for calling HTTPS services without proper certificate

  • returnFullResponse：RAG 系统并非仅返回响应体，而是返回一个包含更多数据的对象，格式如下：{body: body, headers: object, statusCode: 200, statusMessage: 'OK'}

¥returnFullResponse: Instead of returning just the body, returns an object with more data in the following format: {body: body, headers: object, statusCode: 200, statusMessage: 'OK'}

  • encoding：n8n 可以检测内容类型，但你也可以指定 arrayBuffer 来接收一个可读取和交互的缓冲区。

¥encoding: n8n can detect the content type, but you can specify arrayBuffer to receive a Buffer you can read from and interact with.

示例#

¥Example

例如，请参阅 Mattermost 节点。

¥For an example, refer to the Mattermost node.

已弃用的辅助函数#

¥Deprecation of the previous helper

之前使用 this.helpers.request(options) 的辅助实现使用了 request-promise 库并公开了该库。此功能已在版本 1 中移除。

¥The previous helper implementation using this.helpers.request(options) used and exposed the request-promise library. This was removed in version 1.

为了最大限度地减少兼容性问题，n8n 已透明地转换为另一个名为 Axios 的库。

¥To minimize incompatibility, n8n made a transparent conversion to another library called Axios.

如果你遇到问题，请在 社区论坛 或 GitHub 中报告。

¥If you are having issues, please report them in the Community Forums or on GitHub.

迁移到新助手的指南#

¥Migration guide to the new helper

新的辅助函数更加健壮、与库无关且更易于使用。

¥The new helper is much more robust, library agnostic, and easier to use.

所有新节点都应使用新的辅助节点。强烈建议你将现有的自定义节点迁移到新的辅助程序。以下是迁移时需要考虑的主要事项：

¥New nodes should all use the new helper. You should strongly consider migrating existing custom nodes to the new helper. These are the main considerations when migrating:

  • 接受 url。不接受 uri。

¥Accepts url. Doesn't accept uri.

  • encoding: null 现在必须是 encoding: arrayBuffer。

¥encoding: null now must be encoding: arrayBuffer.

  • rejectUnauthorized: false 现在是 skipSslCertificateValidation: true

¥rejectUnauthorized: false is now skipSslCertificateValidation: true

  • 根据 content-type 标头使用 body 来明确有效负载。

¥Use body according to content-type headers to clarify the payload.

  • resolveWithFullResponse 现在是 returnFullResponse，行为类似。

¥resolveWithFullResponse is now returnFullResponse and has similar behavior