extract_embedded_state

Casos de uso

Endpoint

Parameters

Qué lee

Cada fuente que contiene la página aparece en found y se indexa en data con su nombre. Una variable global que no es JSON simple se lee como un literal de JavaScript evaluado de forma estática (objetos, arrays, cadenas, números y la función de retorno único de Nuxt 2) y nunca se ejecuta código de la página; lo que llama a código o lee otras variables se indica en warnings.

• next_data - __NEXT_DATA__ de Next.js.
• next_f - filas flight de React Server Components (self.__next_f), indexadas por id de fila, con las referencias $<id> entre filas resueltas en su sitio (como mucho duplica la carga).
• data_rows - un índice de las filas de next_f que llevan datos en lugar de marcado, de mayor a menor, cada una { id, bytes, keys, length }. Los datos de productos y listados suelen estar en estas filas; lee una con path: "next_f.<id>".
• nuxt - __NUXT__ de Nuxt 2; nuxt_data - __NUXT_DATA__ de Nuxt 3, decodificado de su array de índices a objetos simples.
• sveltekit_data - los datos de kit.start de SvelteKit, una entrada por nodo de ruta, empezando por el layout raíz.
• yt_initial_data y yt_initial_player_response - ytInitialData y ytInitialPlayerResponse de YouTube.
• apollo_state, apollo_ssr_transport, initial_state, preloaded_state, preloaded_data, remix_context (__remixContext), tgt_data (__TGT_DATA__), pws_data (__PWS_DATA__), server_data (__SERVER_DATA__), app_state (__APP_STATE__), state (__STATE__) y global_data (__data__) - variables globales de window de Apollo, de estilo Redux y otras.
• inertia_page - el JSON data-page de Inertia.
• shopify - ShopifyAnalytics.meta y los scripts JSON de producto de Shopify. Los precios de meta son enteros en unidades menores: 10500 es 105.00 en meta.currency.
• json_scripts - bloques <script type="application/json"> y <script type="text/json">, cada uno { id, data }.
• json_attributes - atributos data-* que contienen un objeto JSON de 2 KB o más, cada uno { tag, attribute, id, data }.

Encontrar una ruta

En una carga de varios megabytes, pide la clave que quieres en lugar de los datos. find busca en toda la carga, o solo dentro de path si lo envías, y devuelve dónde aparece la clave con el comienzo de cada valor.

curl -X POST https://crawlforge.dev/api/v1/tools/extract_embedded_state \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "path": "yt_initial_player_response",
    "find": "viewCount"
  }'

Respuesta de find

matches sustituye a data. Cada path ya empieza por el path que enviaste, así que pásalo tal cual como path en la siguiente llamada para obtener el valor completo. matches_total cuenta todas las coincidencias; matches_truncated es true cuando se encontraron más de las 50 devueltas. Una coincidencia marcada addressable: false está bajo una clave que contiene . o [, algo que una ruta no puede expresar.

{
  "success": true,
  "data": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "found": [
      { "name": "yt_initial_data", "variable": "ytInitialData", "bytes": 21239 },
      { "name": "yt_initial_player_response", "variable": "ytInitialPlayerResponse", "bytes": 8076 }
    ],
    "path": "yt_initial_player_response",
    "bytes": 8076,
    "matches": [
      {
        "path": "yt_initial_player_response.videoDetails.viewCount",
        "preview": "\"1822707973\""
      },
      {
        "path": "yt_initial_player_response.microformat.playerMicroformatRenderer.viewCount",
        "preview": "\"1822707973\""
      }
    ],
    "matches_total": 2,
    "matches_truncated": false,
    "warnings": []
  },
  "credits_used": 2,
  "credits_remaining": 996,
  "processing_time": 640
}

Ejemplos de solicitud

curl -X POST https://crawlforge.dev/api/v1/tools/extract_embedded_state \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products/widget"
  }'

// npm install crawlforge-sdk
import { CrawlForge, ValidationError } from 'crawlforge-sdk';

const client = new CrawlForge({ apiKey: process.env.CRAWLFORGE_API_KEY });

try {
  const result = await client.extractEmbeddedState({
    url: 'https://example.com/products/widget',
    // Dotted keys and array indexes. Not JSONPath: no wildcards or filters.
    path: 'next_data.props.pageProps',
  });

  // result.data is untyped in crawlforge-sdk 0.1 — its shape is the Response Example below.
  const { found, data } = result.data as {
    found: { name: string; variable: string; bytes: number }[];
    data: { product: { price: number } };
  };

  // Every state source on the page, largest first, whether or not it was scoped.
  for (const source of found) {
    console.log(source.name, source.variable, source.bytes);
  }

  // The values are the site's own, so they can be used as they are.
  console.log(data.product.price);
} catch (err) {
  // A path that does not resolve is a 400 naming the keys that were available.
  if (err instanceof ValidationError) {
    console.error(err.message);
  } else {
    throw err;
  }
}

# pip install crawlforge
from crawlforge import CrawlForge

client = CrawlForge()  # reads CRAWLFORGE_API_KEY

# 1. Discover what the page carries. Nothing is truncated, so this can be big.
discovery = client.extract_embedded_state(
    url='https://example.com/products/widget',
)

# discovery.data is a plain dict — its shape is the Response Example below.
for source in discovery.data['found']:
    print(source['name'], source['variable'], source['bytes'])

# This tool's warnings live inside data, next to the state itself.
for warning in discovery.data['warnings']:
    print('warning:', warning)

# 2. Ask again for just the branch you want.
scoped = client.extract_embedded_state(
    url='https://example.com/products/widget',
    path='next_data.props.pageProps.product',
)

print(scoped.data['bytes'], 'bytes')
print(scoped.data['data'])

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "url": "https://example.com/products/widget",
    "found": [
      {
        "name": "next_data",
        "variable": "__NEXT_DATA__",
        "bytes": 125
      }
    ],
    "path": null,
    "bytes": 139,
    "data": {
      "next_data": {
        "buildId": "KfC_3GF1zuM",
        "props": {
          "pageProps": {
            "product": {
              "sku": "WID-9001",
              "price": 149.99,
              "currency": "USD",
              "inStock": true
            }
          }
        }
      }
    },
    "warnings": []
  },
  "credits_used": 2,
  "credits_remaining": 998,
  "processing_time": 980
}

Gestión de errores

Herramientas relacionadas