Workers Binding API

VPC バインディングは、Worker からプライベートサービスへアクセスする API を提供します。VPC Services と VPC Networks はどちらも、HTTP トラフィック向けの fetch() メソッドを公開します。VPC Networks は、生の TCP 接続向けの connect() メソッドも公開します。バインディング種類の違いは API 面ではなく、ルーティングの範囲です。

バインディングの種類

VPC Service

VPC Service バインディングは、事前登録した特定のホストとポートへリクエストをルーティングします。fetch() 呼び出しに別の URL やホストがあっても、接続先は常に VPC Service の設定が決めます。

fetch() で渡した host はルーティングを制御しません。Host ヘッダーと、https 使用時の Server Name Indication (SNI) 値を埋めるだけです。
fetch() で渡した port は無視されます。常に VPC Service 設定で指定したポートが使われます。

VPC Network

VPC Network バインディングは、バインドした Cloudflare Tunnel または Cloudflare Mesh 経由で到達できる任意のサービスへのアクセスを与えます。Cloudflare Tunnel または Mesh 経由で広告されるサブネットおよびホスト名ルート、Cloudflare WAN オンランプ（GRE、IPsec、または CNI）経由で接続された宛先も含みます。実際の宛先は、fetch() に渡す URL、または connect() に渡すアドレスが決めます。ホスト名または IP アドレスとポートです。

fetch()

バインドした Cloudflare Tunnel または Cloudflare Mesh 経由で、プライベートサービスへ HTTP リクエストを送ります。VPC Service バインディングと VPC Network バインディングの両方で利用できます。

const response = await env.MY_BINDING.fetch(resource, options);

パラメーター

resource (string | URL | Request) — 取得する URL です。プロトコル、ホスト、パスを含む絶対 URL である必要があります（例: http://internal-api/api/users）。
options (optional RequestInit) — 標準の fetch オプションです。次を含みます。
- method — HTTP メソッド（GET、POST、PUT、DELETE など）
- headers — リクエストヘッダー
- body — リクエストボディ
- signal — リクエストキャンセル用の AbortSignal

戻り値

標準の Fetch API Response オブジェクト ↗ に解決する Promise<Response> を返します。

例

次の例は、VPC Service バインディングと VPC Network バインディングの両方に当てはまります。

基本的な GET リクエスト

export default {
	async fetch(request, env) {
		const privateRequest = new Request(
			"http://internal-api.company.local/users",
		);
		const response = await env.MY_BINDING.fetch(privateRequest);
		const users = await response.json();

		return new Response(JSON.stringify(users), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

ボディ付きの POST リクエスト

export default {
	async fetch(request, env) {
		const privateRequest = new Request(
			"http://internal-api.company.local/users",
			{
				method: "POST",
				headers: {
					"Content-Type": "application/json",
					Authorization: `Bearer ${env.API_TOKEN}`,
				},
				body: JSON.stringify({
					name: "John Doe",
					email: "john@example.com",
				}),
			},
		);

		const response = await env.MY_BINDING.fetch(privateRequest);

		if (!response.ok) {
			return new Response("Failed to create user", { status: response.status });
		}

		const user = await response.json();
		return new Response(JSON.stringify(user), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

HTTPS と IP アドレスを使うリクエスト

export default {
	async fetch(request, env) {
		const privateRequest = new Request("https://10.0.1.50/api/data");
		const response = await env.MY_BINDING.fetch(privateRequest);

		return response;
	},
};

connect()

バインドした Cloudflare Tunnel または Cloudflare Mesh 経由で、プライベートな宛先への生 TCP 接続を開きます。VPC Network バインディングでのみ利用できます。

const socket = await env.MY_BINDING.connect(address);

パラメーター

address (string | SocketAddress) — 接続先です。"host:port" 形式の文字列（例: "10.0.1.50:6379"）、または hostname と port を持つ SocketAddress オブジェクトを渡します。

戻り値

readable と writable ストリームを持つ Socket に解決する Promise<Socket> を返します。connect() が接続を確立できない場合は例外を投げます。

例

プライベートな Redis インスタンスへ接続する

export default {
	async fetch(request, env) {
		const socket = await env.MY_BINDING.connect("10.0.1.50:6379");

		const writer = socket.writable.getWriter();
		await writer.write(new TextEncoder().encode("PING\r\n"));
		await writer.close();

		return new Response(socket.readable);
	},
};

SocketAddress オブジェクトで接続する

export default {
	async fetch(request, env) {
		const socket = await env.MY_BINDING.connect({
			hostname: "10.0.1.50",
			port: 6379,
		});

		const writer = socket.writable.getWriter();
		await writer.write(new TextEncoder().encode("PING\r\n"));
		await writer.close();

		return new Response(socket.readable);
	},
};

必要なロール

Worker で VPC Service または VPC Network をバインドするには、ユーザーに Connectivity Directory Bind（または Connectivity Directory Admin）が必要です。VPC Network バインディング経由で Cloudflare Tunnel に直接バインドするには、Connectivity Directory Admin が必要です。ロールの定義はロールを参照してください。

次のステップ

VPC Services を設定する
VPC Networks を設定する
使用例を参照する