← Browser Run / browser-run / quick-actions

/accessibilityTree - Получение дерева доступности

/accessibilityTree эндпоинт указывает браузеру перейти на сайт и получить дерево доступности страницы после выполнения JavaScript. Дерево доступности включает такую информацию, как роли, имена, значения, состояния и иерархию элементов.

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

Необходимо указать либо url или html:

• url (строка)
• html (строка)

• Предоставление ИИ-агентам структурированного представления страницы для навигации и задач автоматизации браузера
• Роли, доступные имена, значения и состояния для вспомогательных технологий
• Определяйте интерактивные элементы, такие как кнопки, ссылки, меню и поля форм, с которыми может взаимодействовать рабочий процесс автоматизации

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 это 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 не соответствует ни одному элементу на странице, запрос возвращает 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 и одностраничных приложений (SPA) поведение загрузки по умолчанию может давать пустые или неполные результаты. Дело в том, что браузер считает страницу загруженной ещё до того, как JavaScript закончит рендеринг контента.

Проще всего использовать gotoOptions.waitUntil параметр со значением networkidle0 или networkidle2:

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

Для более быстрого отклика опытные пользователи могут использовать waitForSelector чтобы дожидаться появления конкретного элемента вместо ожидания остановки всей сетевой активности. Для этого нужно знать, какой CSS-селектор указывает на загрузку нужного контента. Подробнее см. в Тайм-ауты Quick Actions.

User-Agent можно изменить на уровне страницы, передав userAgent в качестве параметра верхнего уровня в теле JSON. Это полезно, если целевой сайт показывает разный контент в зависимости от User-Agent.

Если у вас есть вопросы или возникла ошибка, см. Часто задаваемые вопросы и руководство по устранению неполадок Browser Run.