Renderizado de JS y control del navegador

Aprende a usar un parámetro render para definir instrucciones del navegador en Web Scraper API, de modo que puedas extraer páginas dinámicas complejas.

Renderizado de JavaScript

Si la página que quieres extraer usa JavaScript para cargar sus datos en el DOM, añade el render parámetro a tu solicitud. Luego la página se renderiza completamente antes de devolver el resultado, en uno de dos formatos:

valor de render	Obtienes
html	El HTML sin procesar de la página completamente renderizada
png	Una captura de pantalla (PNG) codificada en Base64 de la página renderizada

Si quieres extraer una imagen y descargarla, consulta esta sección.

Ejemplo de solicitud

cURL

curl --user "USERNAME:PASSWORD" \
'https://realtime.oxylabs.io/v1/queries' \
-H "Content-Type: application/json" \\
-d '{"source": "universal", "url": "https://www.example.com", "render": "html"}'

Python

import requests
from pprint import pprint

# Estructura del payload.
payload = {
    'source': 'universal',
    'url': 'https://www.example.com',
    'render': 'html',
}

# Obtén la respuesta.
response = requests.request(
    'POST',
    'https://realtime.oxylabs.io/v1/queries',
    auth=('USERNAME', 'PASSWORD'),
    json=payload,
)

# En lugar de una respuesta con el estado del trabajo y la URL de resultados, esto devolverá la
# respuesta JSON con el resultado.
pprint(response.json())

PHP

<?php

$params = [
    'source' => 'universal',
    'url' => 'https://www.example.com',
    'render' => 'html',
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://realtime.oxylabs.io/v1/queries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "USERNAME" . ":" . "PASSWORD");

$headers = array();
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
echo $result;

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

C#

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace OxyApi
{
    class Program
    {
        static async Task Main()
        {
            const string Username = "YOUR_USERNAME";
            const string Password = "YOUR_PASSWORD";

            var parameters = new Dictionary<string, string>()
            {
                { "source", "universal" },
                { "url", "https://www.example.com" },
                { "render" : "html" },
            };


            var client = new HttpClient();

            Uri baseUri = new Uri("https://realtime.oxylabs.io");
            client.BaseAddress = baseUri;

            var requestMessage = new HttpRequestMessage(HttpMethod.Post, "/v1/queries");
            requestMessage.Content = JsonContent.Create(parameters);

            var authenticationString = $"{Username}:{Password}";
            var base64EncodedAuthenticationString = Convert.ToBase64String(System.Text.ASCIIEncoding.UTF8.GetBytes(authenticationString));
            requestMessage.Headers.Add("Authorization", "Basic " + base64EncodedAuthenticationString);

            var response = await client.SendAsync(requestMessage);
            var contents = await response.Content.ReadAsStringAsync();

            Console.WriteLine(contents);
        }
    }
}

Golang

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	const Username = "YOUR_USERNAME"
	const Password = "YOUR_PASSWORD"

	payload := map[string]string{
		"source": "universal",
		"url": "https://www.example.com",
        	"render": "html",
	}

	jsonValue, _ := json.Marshal(payload)

	client := &http.Client{}
	request, _ := http.NewRequest("POST",
		"https://realtime.oxylabs.io/v1/queries",
		bytes.NewBuffer(jsonValue),
	)

	request.SetBasicAuth(Username, Password)
	response, _ := client.Do(request)

	responseText, _ := ioutil.ReadAll(response.Body)
	fmt.Println(string(responseText))
}

Java

package org.example;

import okhttp3.*;
import org.json.JSONObject;

public class Main implements Runnable {
    private static final String AUTHORIZATION_HEADER = "Authorization";
    public static final String USERNAME = "YOUR_USERNAME";
    public static final String PASSWORD = "YOUR_PASSWORD";

    public void run() {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("source", "universal");
        jsonObject.put("url", "https://www.example.com");
        jsonObject.put("render", "html");

        Authenticator authenticator = (route, response) -> {
            String credential = Credentials.basic(USERNAME, PASSWORD);

            return response
                    .request()
                    .newBuilder()
                    .header(AUTHORIZATION_HEADER, credential)
                    .build();
        };

        var client = new OkHttpClient.Builder()
                .authenticator(authenticator)
                .build();

        var mediaType = MediaType.parse("application/json; charset=utf-8");
        var body = RequestBody.create(jsonObject.toString(), mediaType);
        var request = new Request.Builder()
                .url("https://realtime.oxylabs.io/v1/queries")
                .post(body)
                .build();

        try (var response = client.newCall(request).execute()) {
            assert response.body() != null;
            System.out.println(response.body().string());
        } catch (Exception exception) {
            System.out.println("Error: " + exception.getMessage());
        }

        System.exit(0);
    }

    public static void main(String[] args) {
        new Thread(new Main()).start();
    }
}

Node.js

import fetch from 'node-fetch';

const username = 'YOUR_USERNAME';
const password = 'YOUR_PASSWORD';
const body = {
  'source': 'universal',
  'url': 'https://www.example.com',
  'render': 'html'
};
const response = await fetch('https://realtime.oxylabs.io/v1/queries', {
  method: 'post',
  body: JSON.stringify(body),
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64'),
  }
});

console.log(await response.json());

JSON

{
    "source": "universal", 
    "url": "https://www.example.com", 
    "render": "html"
}

El renderizado de JavaScript tarda más en extraer la página. Establece un timeout en el lado del cliente de 180 segundos si usas Realtime o Proxy Endpoint como métodos de integración.

Para garantizar el menor consumo de tráfico, nuestro sistema no carga activos innecesarios durante el renderizado de la página.

Forzar el renderizado en páginas específicas

Para una extracción exitosa, algunos tipos de páginas de dominios específicos requieren renderizado debido a su contenido dinámico. Para estas, nuestro sistema aplica automáticamente el renderizado incluso si no estableces el render parámetro, para que siempre obtengas datos precisos y fiables de estas páginas, que de otro modo son difíciles.

Ten en cuenta que los trabajos renderizados consumen más tráfico que los no renderizados.

La lista completa de objetivos afectados se mantiene en el archivo de abajo. Queremos que nuestros usuarios sean plenamente conscientes de ello al extraer las siguientes páginas:

forced-render-domains.csv

3KB

Abrir

Si deseas desactivar el renderizado, puedes hacerlo añadiendo el siguiente parámetro a tus solicitudes:

"render": ""

Instrucciones del navegador

Cuando una página necesita interacción, como hacer clic en un botón, introducir un término de búsqueda o desplazarte para cargar más elementos, puedes definir tus propias browser_instructions que se ejecutan mientras la página se renderiza.

La forma más sencilla de crear instrucciones del navegador es el generador visual impulsado por IA en el Playground de Web Scraper API. Lee sobre ello aquí.

Inicio rápido

Ante todo, las instrucciones del navegador requieren el render parámetro, ya sea html o png, y se proporcionan como una lista en el browser_instructions campo. Cada elemento de la lista se ejecuta en orden.

Supón que quieres buscar cajas de pizza en un sitio web — escribe el término en el campo de búsqueda, haz clic en el botón de búsqueda y espera 5 segundos a que carguen los resultados:

{
    "source": "universal",
    "url": "https://www.etsy.com/",
    "render": "html",
    "browser_instructions": [
        {
            "type": "input",
            "value": "pizza boxes",
            "selector": {
                "type": "css",
                "value": "#global-enhancements-search-query"
            }
        },
        {
            "type": "click",
            "selector": {
                "type": "css",
                "value": "button[data-id='gnav-search-submit-button']"
            }
        },
        {
            "type": "wait",
            "wait_time_s": 5
        }
    ]
}

El resultado contiene el HTML después de que las instrucciones se hayan ejecutado:

{
  "results": [
    {
      "content": "<!DOCTYPE html><html lang=\"en-US\">  Search results for \"pizza boxes\"  </html>",
      "created_at": "2026-08-19 12:23:06",
      "updated_at": "2026-08-19 12:23:24",
      "page": 1,
      "url": "https://www.etsy.com/search?q=pizza+boxes&ref=search_bar&instant_download=false",
      "job_id": "7495817623108602881",
      "is_render_forced": false,
      "type": "raw",
      "status_code": 200
    }
  ]
}

El HTML extraído debería verse así:

Obtención de recursos del navegador

Proporcionamos una instrucción independiente del navegador para obtener recursos del navegador.

La función se define aquí:

Usando fetch_resource hará que el trabajo devuelva la primera ocurrencia de un recurso Fetch/XHR que coincida con el formato proporcionado en lugar del HTML que se está apuntando.

Supongamos que queremos apuntar a un recurso GraphQL que se obtiene al visitar de forma orgánica una página de producto en el navegador. Proporcionaremos la información del trabajo así:

{
    "source": "universal",
    "url": "https://www.example.com/product-page/123",
    "render": "html",
    "browser_instructions": [
        {
            "type": "fetch_resource",
            "filter": "/graphql/product-info/123"
        }
    ]
}

Estas instrucciones darán como resultado algo así:

{
  "results": [
    {
      "content": "{'product_id': 123, 'description': '', 'price': 123}",
      "created_at": "2023-10-11 11:35:23",
      "updated_at": "2023-10-11 11:36:08",
      "page": 1,
      "url": "https://example.com/v1/graphql/product-info/123/",
      "job_id": "7117835067442906114",
      "status_code": 200
    }
  ]
}

Lista de instrucciones de navegador compatibles

Argumentos generales

Todas las instrucciones definidas a continuación tienen un conjunto coherente de argumentos. Los argumentos son los siguientes.

escribir

• Tipo: Enum["click", "input", "scroll", "scroll_to_bottom", "wait", "wait_for_element", "fetch_resource"]
• Descripción: Tipo de instrucción del navegador.
• Obligatorio: verdadero

timeout_s

• Tipo: entero
• Descripción: Cuánto tiempo hasta que se omita la acción si no se completa a tiempo.
• Restricciones: 0 < timeout_s <= 60
• Valor predeterminado: 5

wait_time_s

• Tipo: entero
• Descripción: Cuánto esperar antes de ejecutar la siguiente acción.
• Restricciones: 0 < wait_time_s <= 60
• Valor predeterminado: 0

on_error

• Tipo: Enum["error", "skip"]
• Descripción: Indicador de qué hacer con las instrucciones en caso de que esta instrucción falle:

  • "error": Detiene la ejecución de las instrucciones del navegador.
  • "skip": Continúa con la siguiente instrucción.
• Valor predeterminado: "error"

Ejemplo con argumentos generales

{
    "type": "wait_for_element",
    "selector": {
        "type": "text",
        "value": "Load More Items"
    },
    "timeout_s": 5,
    "wait_time_s": 2,
    "on_error": "skip"

}

Instrucciones

hacer clic

• Descripción: Hace clic en un elemento y espera una cantidad fija de segundos.
• Argumentos:

  • tipo: cadena = "click"
  • selector: diccionario

    • tipo: Enum["xpath", "css", "text"]
    • valor: cadena

Ejemplo:

{
    "type": "click",
    "selector": {
        "type": "xpath",
        "value": "//button"
    }
}

input

• Descripción: Introduce texto en un elemento seleccionado.
• Argumentos:

  • tipo: cadena = "input"
  • selector: diccionario

    • tipo: Enum["xpath", "css", "text"]
    • valor: cadena
  • valor: cadena

Ejemplo:

{
    "type": "input",
    "selector": {
        "type": "xpath",
        "value": "//input"
    },
    "value": "pizza boxes"
}

scroll

• Descripción: Desplaza una cantidad determinada de píxeles.
• Argumentos:

  • tipo: cadena = "scroll"
  • x: entero
  • y: entero

Ejemplo:

{
    "type": "scroll",
    "x": 0,
    "y": 100
}

scroll_to_bottom

• Descripción: Desplaza hasta abajo durante una cantidad determinada de segundos.
• Argumentos:

  • tipo: cadena = "scroll_to_bottom"

Ejemplo:

{
    "type": "scroll_to_bottom",
    "timeout_s": 10
}

esperar

• Descripción: Espera una cantidad determinada de segundos.
• Argumentos:

  • tipo: cadena = "wait"

Ejemplo:

{
    "type": "wait",
    "wait_time_s": 2
}

wait_for_element

• Descripción: Espera a que el elemento cargue durante una cantidad determinada de segundos.
• Argumentos:

  • tipo: cadena = "wait_for_element"
  • selector: diccionario

    • tipo: Enum["xpath", "css", "text"]
    • valor: cadena

Ejemplo:

{
    "type": "wait_for_element",
    "selector": {
        "type": "text",
        "value": "Load More Items"
    },
    "timeout_s": 5
}

fetch_resource

La fetch_resource la instrucción debe ser la última instrucción en la lista de instrucciones del navegador; cualquier instrucción posterior no se ejecutará.

• Descripción: Obtiene la primera ocurrencia de un recurso Fetch/XHR que coincida con el patrón establecido.
• Argumentos:

  • tipo: cadena = "fetch_resource"
  • filtro: cadena (expresión RegEx)
  • on_error: Enum["error", "skip"]

Ejemplo:

{
    "type": "fetch_resource",
    "filter": "/graphql/item/"
}

Validación de instrucciones

Cualquier inconsistencia con respecto al formato de la instrucción dará como resultado un 400 código de estado y un mensaje de error correspondiente.

Por ejemplo, una carga útil como esta:

{
    "source": "universal",
    "url": "https://www.example.com/",
    "render": "html",
    "browser_instructions": [
        {
            "type": "unsupported-wait",
            "wait_time_s": 5
        }
    ]
}

Dará como resultado:

{    
    "errors": {
        "message": "Unsupported action type `unsupported-wait`, choose from 'click,fetch_resource,input,scroll,scroll_to_bottom,wait,wait_for_element'"
    }
}

Solución de problemas

Códigos de estado

Consulte nuestros códigos de respuesta descritos aquí. Los códigos de estado relacionados con la validación de instrucciones están documentados aquí.

Errores y advertencias

Si hay un error o advertencia resultado de tus acciones de navegación, lo encontrarás en el resultado bajo las claves browser_instructions_error o browser_instructions_warnings. Por ejemplo, si has enviado las siguientes instrucciones del navegador y el esperado xpath no se encuentra en la página, el resultado incluirá una advertencia.

browser_instructions:

[
    {
        "type": "input", 
        "selector": {
            "type": "xpath",
            "value": "//input[@type='search']"
        },
        "value": "oxylabs"
    }
]

Resultados:

{
  "results": [
    {
      "content": "<!doctype html><html>
        Contenido después de ejecutar las instrucciones      
      </html>",
      "created_at": "2023-10-11 11:35:23",
      "updated_at": "2023-10-11 11:36:08",
      "browser_instructions_warnings": [
        {
          "action_type": "click",
          "msg": "No se puede encontrar el tipo de selector `xpath` con el valor `//input[@type=search]` en la página."
        },
      ],
      "page": 1,
      "url": "https://example.com",
      "job_id": "7117835067442906113",
      "status_code": 200
    }
  ]
}

Posibles errores y advertencias
Se produjo un error inesperado al convertir las instrucciones del navegador en acciones.
Se produjo un error inesperado al ejecutar {action.type} las instrucciones del navegador.
Acción {action.type} agotó el tiempo.
No se puede encontrar el tipo de selector {selector.type} con el valor {selector.value} en la página.