← Browser Run / browser-run / quick-actions

/json - Zachycení strukturovaných dat pomocí AI

/json endpoint extrahuje strukturovaná data z webové stránky. Očekávaný výstup můžete zadat pomocí prompt nebo response_format parametr, který přijímá schéma JSON. Koncový bod vrací extrahovaná data ve formátu JSON.

Tento koncový bod můžete použít dvěma způsoby:

REST API: Vytvořte vlastní API Token hodnotou Browser Rendering - Edit oprávnění.
Workers Bindings: Volejte endpoint přímo z Cloudflare Worker pomocí Workers Bindings. Není potřeba žádný API token.

Další informace najdete v tématu Quick Actions: Než začnete.

Endpoint

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

Povinná pole

Musíte zadat buď url nebo html:

url (řetězec)
html (řetězec)

A alespoň jedno z následujícího:

prompt (řetězec), nebo
response_format (objekt se schématem JSON Schema)

Běžné případy použití

Extrakce informací o produktech (název, cena, dostupnost) nebo výpisů (pracovní nabídky, pronájmy)
Normalizovat metadata článku (název, autor, datum publikace, kanonická adresa URL)
Převeďte nestrukturované stránky na typovaný JSON pro navazující pipeline

Základní použití

S promptem a schématem JSON

Tento příklad získává data webové stránky pomocí zadaného promptu a schématu JSON. Prompt řídí proces extrakce, zatímco schéma JSON definuje očekávanou strukturu výstupu.

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/"
			}
		]
	}
}

Níže je uveden příklad s využitím 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>;

Pouze s promptem

V tomto příkladu je poskytnut pouze prompt. Koncový bod prompt použije k extrakci dat, ale odpověď nebude strukturovaná podle schématu JSON. Toto je užitečné pro jednoduché extrakce, kde nepotřebujete konkrétní formát.

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"
		]
	}
}

Pouze se schématem JSON (bez promptu)

V tomto případě zadáte schéma JSON pomocí response_format parametr. Schéma definuje strukturu extrahovaných dat.

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/"
			}
		]
	}
}

Pokročilé použití

Používání vlastního modelu (BYO API Key)

Browser Run může využívat vlastní model, pro který dodáte přihlašovací údaje. Uveďte tyto modely v custom_ai pole:

model by měl mít tvar <provider>/<model_name> a poskytovatel musí být jedním z těchto podporovaní poskytovatelé.
authorization je bearer token nebo API klíč, který Browser Run umožňuje volat poskytovatele vaším jménem.

Tento příklad používá custom_ai parametr, kterým Browser Run pokynete, aby použil model Claude Sonnet 4 od Anthropic. Prompt požádá model, aby extrahoval hlavní <h1> a <h2> nadpisy z cílové adresy URL a vrátí je ve strukturovaném objektu 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"
	}
}

Používání vlastního modelu se záložními modely

Pro automatický failover můžete zadat více modelů. Browser Run modely vyzkouší postupně, dokud jeden neuspěje. Pro přidání failoveru uveďte další modely v custom_ai pole.

V tomto příkladu Browser Run nejprve zavolá model Claude Sonnet 4 od Anthropic. Pokud tento požadavek vrátí chybu, automaticky to zkusí znovu s modelem Meta Llama 3.3 70B z Workers AI, poté GPT-4o od OpenAI.

"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>"
  }
]

Řešení potíží

Extrakce JSON vrací null nebo prázdné výsledky

Pokud /json endpoint vrací null nebo prázdné výsledky:

Zadejte jasný prompt : Buďte konkrétní ohledně toho, jaká data chcete extrahovat a kde se na stránce nacházejí (například "Extrahujte název produktu, cenu a popis z hlavní sekce produktu").
Definujte schéma odpovědi : použijte response_format se schématem JSON, které vynutí očekávanou strukturu výstupu.
Použití vlastního modelu : Pokud výchozí Workers AI model neposkytuje požadované výsledky, použijte custom_ai parametr pro zadání jiného modelu. Další informace najdete v Používání vlastního modelu (BYO API Key) s podrobnostmi.

Práce se stránkami náročnými na JavaScript

U stránek s velkým množstvím JavaScriptu nebo jednostránkových aplikací (SPA) může výchozí chování při načítání stránky vracet prázdné nebo neúplné výsledky. Je to dáno tím, že prohlížeč považuje stránku za načtenou dříve, než JavaScript dokončí vykreslení obsahu.

Nejjednodušším řešením je použít gotoOptions.waitUntil parametr nastavený na networkidle0 nebo networkidle2:

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

Pro rychlejší odezvu mohou pokročilí uživatelé použít waitForSelector k čekání na konkrétní prvek namísto čekání na zastavení veškeré síťové aktivity. To vyžaduje znalost, který CSS selektor signalizuje, že se požadovaný obsah načetl. Další podrobnosti najdete v Časové limity Quick Actions.

Nastavení vlastního user-agenta

User agent můžete změnit na úrovni stránky předáním userAgent jako parametr nejvyšší úrovně v těle JSON. To je užitečné, pokud cílový web zobrazuje různý obsah podle uživatelského agenta.

Řešení potíží

Pokud máte dotazy nebo narazíte na chybu, podívejte se na Časté dotazy a průvodce řešením problémů Browser Run.