Estrattori

Un estrattore è un componente identificato da un nome stabile, pensato per raccogliere un determinato tipo di dati. In Guida 0.9 gli estrattori formano una piattaforma completa: i descrittori risiedono nello spazio di lavoro, Guida li riunisce in un catalogo ricercabile e chi opera sul sistema può convalidarli, certificarli e confrontarne i risultati senza affidarsi a procedure informali.

Gli estrattori vengono eseguiti da Guida Complete e Guida Node. Guida Control offre una vista remota sugli stessi contratti Remote Ops, senza creare un secondo catalogo.

Descrittore e implementazione

Il descrittore è il contratto pubblico dell’estrattore. Indica implementazione, origine, flusso di lavoro, coda, input predefinito, domini di destinazione, contratto di output e prove richieste. L’implementazione resta normale codice dello spazio di lavoro.

{
  "$schema": "../../../extractors.schema.json",
  "id": "careers.example.jobs",
  "profile": "web.discovery.browser",
  "label": "Example engineering jobs",
  "domain": "careers",
  "workflowName": "careers-example",
  "queueName": "careers_example",
  "implementation": {
    "module": "lib/careers-example-worker.js",
    "export": "discoverExampleJobs",
    "language": "javascript"
  },
  "source": {
    "kind": "web",
    "url": "https://example.com/careers",
    "label": "Example careers"
  },
  "targetDomains": ["example.com"],
  "input": {
    "defaultUrl": "https://example.com/careers",
    "defaultCompanyName": "Example",
    "defaultSlug": "example"
  },
  "evidence": {
    "requiresPageLoaded": true,
    "requiresResultEvidence": true,
    "allowQualifiedEmpty": true
  }
}

Un piccolo file radice extractors.json può includere i descrittori, selezionare i profili comuni e suddividere un catalogo esteso in sezioni deterministiche. Ogni voce conserva comunque identità e percorso di origine propri.

Contratti prima dell’esecuzione

La convalida individua descrittori malformati, ID duplicati, implementazioni mancanti, profili irrisolti, regole sui domini non valide e contratti di input o output incompatibili. I controlli di compatibilità rendono esplicito il confine fra un estrattore e chi ne usa i risultati.

L’API di scripting offre anche l’accesso sincrono e in sola lettura al catalogo con g.extractors.list(), g.extractors.get() e g.extractors.validate(). Per l’accesso remoto sono disponibili i gruppi workspace.extractors.* e workspace.extractors.contracts.*.

Certificazione basata su prove

La certificazione è una verifica operativa circoscritta, non un marchio valido per sempre.

• La modalità Quick controlla un insieme ridotto di destinazioni e restituisce rapidamente un primo riscontro.
• La modalità Coverage estende il controllo al catalogo selezionato, entro limiti dichiarati.
• Un risultato vuoto può essere accettato solo se la pagina risulta caricata e il descrittore consente esplicitamente un vuoto giustificato.
• Le prove relative ai selettori devono essere osservate, non soltanto dichiarate.
• Completezza e troncamento dell’esplorazione vengono registrati, così una verifica parziale non viene presentata come copertura completa.

Prima di avviare il lavoro, usa workspace.extractors.certification.plan. Il piano distingue ciò che è eseguibile da ciò che è bloccato e mostra i limiti applicati. Avvio, annullamento ed esportazione delle prove restano operazioni soggette ai controlli di Guida.

Risultati e storico operativo

Guida mantiene separati l’esito più recente e lo storico da cui proviene. È possibile consultare esecuzioni e risultati di certificazione, statistiche nel tempo, anomalie rilevate in base alla regola selezionata, variazioni dei contratti e prove esportate. La conservazione dello storico è regolata dal file di configurazione dello spazio di lavoro; i dati operativi sono salvati in operations.db.

Il catalogo e gli strumenti operativi sono stati verificati con 5.000 estrattori in prove deterministiche su un singolo host. Non si tratta di una promessa relativa a 5.000 sessioni browser contemporanee o alla capacità di una flotta Enterprise.

Dall’estrattore alla pipeline

Un estrattore produce dati conformi a un contratto. Una pipeline semantica collega tale output a controlli di convalida, trasformazioni e destinazioni. Le pipeline generate usano associazioni esplicite, per esempio $extractor.id e $extractor.source.url: Guida non deduce il significato da nomi di file o cartelle.

La Remote Ops API espone operazioni circoscritte per catalogo, contratti, certificazione, storico, statistiche e anomalie. Le letture possono alimentare un client di sola osservazione; le operazioni che eseguono lavoro mantengono tutti i controlli locali su capacità, regole e conferme.