/accessibilityTree - アクセシビリティツリーを取得 · Cloudflare Browser Run ドキュメント

/accessibilityTree エンドポイントは、ブラウザーにウェブサイトへ移動させ、JavaScript 実行後のページのアクセシビリティツリーを取得します。アクセシビリティツリーには、ロール、名前、値、状態、階層など、アクセシビリティ関連の情報が含まれます。

エンドポイント

https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree

必須フィールド

url または html のいずれかを指定します。

url (string)
html (string)

よくある用途

AI エージェントに、ナビゲーションやブラウザー自動化向けの構造化されたページ表現を渡す
支援技術に公開されるロール、アクセシブルネーム、値、状態を確認する
ボタン、リンク、メニュー、フォーム欄など、自動化ワークフローが操作できるインタラクティブ要素を特定する

基本的な使い方

URL からアクセシビリティツリーを取得する

https://example.com/ に移動し、ページのアクセシビリティツリーを返します。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/"
}'

{
	"success": true,
	"result": {
		"accessibilityTree": {
			"role": "RootWebArea",
			"name": "Example Domain",
			"children": [
				{
					"role": "heading",
					"name": "Example Domain",
					"level": 1
				},
				{
					"role": "StaticText",
					"name": "This domain is for use in documentation examples without needing permission. Avoid use in operations."
				},
				{
					"role": "link",
					"name": "Learn more"
				}
			]
		}
	},
	"meta": {
		"status": 200,
		"title": "Example Domain"
	}
}

import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiToken: process.env["CLOUDFLARE_API_TOKEN"],
});

const accessibilityTree = await client.browserRendering.accessibilityTree.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://example.com/",
});

console.log(accessibilityTree.accessibilityTree);

interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("accessibilityTree", {
			url: "https://example.com/",
		});
	},
} satisfies ExportedHandler<Env>;

任意パラメーター

/accessibilityTree リクエストでは、必須の url または html に加えて、次の任意パラメーターを使えます。

任意パラメーター	型	説明
`interestingOnly`	Boolean	`true` のとき、意味のあるノードだけを返します。デフォルトは `true` です。`root` を指定して `interestingOnly` を省略した場合、デフォルトは `false` です。
`root`	String	アクセシビリティツリーを部分木に固定する CSS セレクターです。セレクターに一致する要素がない場合、`accessibilityTree` は `null` を返します。部分木内の意味のあるノードだけを返すには、`interestingOnly` を明示的に `true` にします。

高度な使い方

すべてのノードを含める

デフォルトでは interestingOnly は true で、意味のあるノードに絞り込んだ応答になります。アクセシビリティツリーのすべてのノード（汎用ノードや見た目用のノードを含む）を含めるには、interestingOnly を false にします。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "interestingOnly": false
}'

応答例

{
	"success": true,
	"result": {
		"accessibilityTree": {
			"role": "RootWebArea",
			"name": "Example Domain",
			"children": [
				{
					"role": "generic",
					"name": "",
					"children": [
						{
							"role": "heading",
							"name": "Example Domain",
							"level": 1
						},
						{
							"role": "paragraph",
							"name": "",
							"children": [
								{
									"role": "StaticText",
									"name": "This domain is for use in documentation examples without needing permission. Avoid use in operations."
								}
							]
						},
						{
							"role": "paragraph",
							"name": "",
							"children": [
								{
									"role": "link",
									"name": "Learn more"
								}
							]
						}
					]
				}
			]
		}
	},
	"meta": {
		"status": 200,
		"title": "Example Domain"
	}
}

部分木を取得する

root に CSS セレクター文字列を指定すると、ページの特定部分のアクセシビリティツリーを返せます。

root を指定して interestingOnly を省略した場合、interestingOnly のデフォルトは false です。部分木を意味のあるノードに絞り込むには、interestingOnly を明示的に true にします。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "root": "h1",
    "interestingOnly": true
}'

{
	"success": true,
	"result": {
		"accessibilityTree": {
			"role": "heading",
			"name": "Example Domain",
			"level": 1
		}
	},
	"meta": {
		"status": 200,
		"title": "Example Domain"
	}
}

一致しない root セレクターを扱う

root がページ上のどの要素にも一致しない場合、リクエストは HTTP 200 を返し、accessibilityTree は null です。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "root": "#does-not-exist"
}'

{
	"success": true,
	"result": {
		"accessibilityTree": null
	},
	"meta": {
		"status": 200,
		"title": "Example Domain"
	}
}

JavaScript が多いページの扱い

JavaScript が多いページや Single Page Application（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 の FAQ とトラブルシューティングガイドを参照してください。