跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

/json - 使用 AI 捕获结构化数据

最后更新 查看 MarkdownAgent 设置

/json 端点从网页提取结构化数据。你可以使用 prompt 或接受 JSON schema 的 response_format 参数指定预期输出。端点以 JSON 格式返回提取的数据。

可通过两种方式使用此端点：

更多信息请参阅 Quick Actions：开始之前。

端点

https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/json

必填字段

必须提供 url 或 html 之一：

  • url（字符串）
  • html（字符串）

并且至少提供以下之一：

  • prompt（字符串），或
  • response_format（包含 JSON Schema 的对象）

常见使用场景

  • 提取产品信息（标题、价格、库存）或列表（职位、租赁）
  • 规范化文章元数据（标题、作者、发布日期、canonical URL）
  • 将非结构化页面转换为类型化 JSON，供下游管道使用

基本用法

使用 Prompt 和 JSON schema

此示例通过同时提供 prompt 和 JSON schema 捕获网页数据。prompt 指导提取过程，JSON schema 定义输出的预期结构。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/json' \
  -H 'authorization: Bearer <apiToken>' \
  -H 'content-type: application/json' \
  -d '{
  "url": "https://developers.cloudflare.com/",
  "prompt": "Get me the list of AI products",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
        "type": "object",
        "properties": {
          "products": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "link": {
                  "type": "string"
                }
              },
              "required": [
                "name"
              ]
            }
          }
        }
      }
  }
}'
{
	"success": true,
	"result": {
		"products": [
			{
				"name": "Build a RAG app",
				"link": "https://developers.cloudflare.com/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/"
			},
			{
				"name": "Workers AI",
				"link": "https://developers.cloudflare.com/workers-ai/"
			},
			{
				"name": "Vectorize",
				"link": "https://developers.cloudflare.com/vectorize/"
			},
			{
				"name": "AI Gateway",
				"link": "https://developers.cloudflare.com/ai-gateway/"
			},
			{
				"name": "AI Playground",
				"link": "https://playground.ai.cloudflare.com/"
			}
		]
	}
}

以下是使用 TypeScript SDK 的示例：

import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiToken: process.env["CLOUDFLARE_API_TOKEN"], // This is the default and can be omitted
});

const json = await client.browserRendering.json.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://developers.cloudflare.com/",
	prompt: "Get me the list of AI products",
	response_format: {
		type: "json_schema",
		json_schema: {
			type: "object",
			properties: {
				products: {
					type: "array",
					items: {
						type: "object",
						properties: {
							name: {
								type: "string",
							},
							link: {
								type: "string",
							},
						},
						required: ["name"],
					},
				},
			},
		},
	},
});
console.log(json);
interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("json", {
			url: "https://developers.cloudflare.com/",
			prompt: "Get me the list of AI products",
			response_format: {
				type: "json_schema",
				json_schema: {
					type: "object",
					properties: {
						products: {
							type: "array",
							items: {
								type: "object",
								properties: {
									name: { type: "string" },
									link: { type: "string" },
								},
								required: ["name"],
							},
						},
					},
				},
			},
		});
	},
} satisfies ExportedHandler<Env>;

仅使用 prompt

在此示例中，仅提供 prompt。端点将使用 prompt 提取数据，但响应不会按 JSON schema 结构化。 当你不需要特定格式、只需简单提取时，这很有用。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/json' \
  -H 'authorization: Bearer <apiToken>' \
  -H 'content-type: application/json' \
  -d '{
    "url": "https://developers.cloudflare.com/",
    "prompt": "get me the list of AI products"
  }'
{
	"success": true,
	"result": {
		"AI Products": [
			"Build a RAG app",
			"Workers AI",
			"Vectorize",
			"AI Gateway",
			"AI Playground"
		]
	}
}

仅使用 JSON schema（无 prompt）

在此情况下，你通过 response_format 参数提供 JSON schema。schema 定义提取数据的结构。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/json' \
  -H 'authorization: Bearer <apiToken>' \
  -H 'content-type: application/json' \
  -d '{
	"url": "https://developers.cloudflare.com/",
	"response_format": {
		"type": "json_schema",
		"json_schema": {
			"type": "object",
			"properties": {
			"products": {
				"type": "array",
				"items": {
				"type": "object",
				"properties": {
					"name": {
					"type": "string"
					},
					"link": {
					"type": "string"
					}
				},
				"required": [
					"name"
				]
				}
			}
			}
		}
    }
  }'
{
	"success": true,
	"result": {
		"products": [
			{
				"name": "Workers",
				"link": "https://developers.cloudflare.com/workers/"
			},
			{
				"name": "Pages",
				"link": "https://developers.cloudflare.com/pages/"
			},
			{
				"name": "R2",
				"link": "https://developers.cloudflare.com/r2/"
			},
			{
				"name": "Images",
				"link": "https://developers.cloudflare.com/images/"
			},
			{
				"name": "Stream",
				"link": "https://developers.cloudflare.com/stream/"
			},
			{
				"name": "Build a RAG app",
				"link": "https://developers.cloudflare.com/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/"
			},
			{
				"name": "Workers AI",
				"link": "https://developers.cloudflare.com/workers-ai/"
			},
			{
				"name": "Vectorize",
				"link": "https://developers.cloudflare.com/vectorize/"
			},
			{
				"name": "AI Gateway",
				"link": "https://developers.cloudflare.com/ai-gateway/"
			},
			{
				"name": "AI Playground",
				"link": "https://playground.ai.cloudflare.com/"
			},
			{
				"name": "Access",
				"link": "https://developers.cloudflare.com/cloudflare-one/access-controls/policies/"
			},
			{
				"name": "Tunnel",
				"link": "https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/"
			},
			{
				"name": "Gateway",
				"link": "https://developers.cloudflare.com/cloudflare-one/traffic-policies/"
			},
			{
				"name": "Browser Isolation",
				"link": "https://developers.cloudflare.com/cloudflare-one/remote-browser-isolation/"
			},
			{
				"name": "Replace your VPN",
				"link": "https://developers.cloudflare.com/learning-paths/replace-vpn/concepts/"
			}
		]
	}
}

高级用法

使用自定义模型（自带 API 密钥）

Browser Run 可以使用你提供凭据的自定义模型。在 custom_ai 数组中列出模型：

  • model 应格式化为 <provider>/<model_name>，provider 必须是这些支持的提供商之一。
  • authorization 是 bearer token 或 API key，允许 Browser Run 代表你调用提供商。

此示例使用 custom_ai 参数指示 Browser Run 使用 Anthropic 的 Claude Sonnet 4 模型。prompt 要求模型从目标 URL 提取主要 <h1> 和 <h2> 标题，并以结构化 JSON 对象返回。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/json' \
  -H 'authorization: Bearer <apiToken>' \
  -H 'content-type: application/json' \
  -d '{
  "url": "http://demoto.xyz/headings",
  "prompt": "Get the heading from the page in the form of an object like h1, h2. If there are many headings of the same kind then grab the first one.",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "type": "object",
      "properties": {
        "h1": {
          "type": "string"
        },
        "h2": {
          "type": "string"
        }
      },
      "required": [
        "h1"
      ]
    }
  },
  "custom_ai": [
    {
      "model": "anthropic/claude-sonnet-4-20250514",
      "authorization": "Bearer <ANTHROPIC_API_KEY>"
    }
  ]
}'
{
	"success": true,
	"result": {
		"h1": "Heading 1",
		"h2": "Heading 2"
	}
}

使用带 fallback 的自定义模型

你可以指定多个模型以提供自动故障转移。Browser Run 将按顺序尝试模型，直到其中一个成功。要添加故障转移，在 custom_ai 数组中列出其他模型。

在此示例中，Browser Run 首先调用 Anthropic 的 Claude Sonnet 4 模型。如果该请求返回错误，它会自动使用 Workers AI 的 Meta Llama 3.3 70B 重试，然后使用 OpenAI 的 GPT-4o。

"custom_ai": [
  {
    "model": "anthropic/claude-sonnet-4-20250514",
    "authorization": "Bearer <ANTHROPIC_API_KEY>"
  },
  {
    "model": "workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "authorization": "Bearer <CLOUDFLARE_AUTH_TOKEN>"
  },
{
    "model": "openai/gpt-4o",
    "authorization": "Bearer <OPENAI_API_KEY>"
  }
]

故障排除

JSON 提取返回 null 或空结果

如果 /json 端点返回 null 或空结果：

  • 提供清晰的 prompt — 具体说明要提取什么数据以及它在页面上的位置（例如，「从主要产品部分提取产品名称、价格和描述」）。
  • 定义响应 schema — 使用带 JSON schema 的 response_format 强制预期的输出结构。
  • 使用自定义模型 — 如果默认 Workers AI 模型未产生预期结果，使用 custom_ai 参数指定不同模型。详情请参阅使用自定义模型（自带 API 密钥）。

处理 JavaScript 密集型页面

对于 JavaScript 密集型页面或单页应用（SPA），默认的页面加载行为可能返回空或不完整的结果。这是因为浏览器在 JavaScript 完成渲染内容之前就认为页面已加载完毕。

最简单的解决方案是将 gotoOptions.waitUntil 参数设置为 networkidle0 或 networkidle2：

{
	"url": "https://example.com",
	"gotoOptions": {
		"waitUntil": "networkidle0"
	}
}

如需更快响应，高级用户可使用 waitForSelector 等待特定元素，而非等待所有网络活动停止。这需要了解哪个 CSS 选择器表示所需内容已加载。更多详情，请参阅 Quick Actions 超时。

设置自定义 User Agent

可在 JSON 请求体的顶层传入 userAgent 参数，在页面级别更改 user agent。当目标网站根据 user agent 返回不同内容时很有用。

故障排除

如有疑问或遇到错误，请参阅 Browser Run 常见问题与故障排除指南。

这篇文档对您有帮助吗？