Motore di importazione

Questo documento descrive come il plugin ADP Car Market Hub importa le inserzioni dei veicoli dall'API di AutoScout24 in WordPress. Copre le responsabilità delle classi dell'importatore, il flusso per singola inserzione, il rilevamento delle modifiche, l'eliminazione con sincronizzazione completa e l'hook pubblico che si attiva dopo l'importazione di un veicolo.

Quando utilizzare questo documento

Leggere questo documento se si ha la necessità di:

• Comprendere cosa accade durante un'esecuzione di importazione.
• Diagnosticare perché un veicolo è stato inserito, aggiornato, saltato o rimosso.
• Creare un'integrazione personalizzata che reagisca alle importazioni tramite l'azione as24ci_vehicle_imported.
• Pianificare i requisiti di capacità o di hosting per cataloghi di grandi dimensioni.

Per i dettagli sulla pianificazione e sul cron, vedere Cron Events And Scheduler. Per la gestione delle immagini, vedere Image Importer And Queue.

Panoramica

Il motore di importazione è composto da diverse classi che lavorano insieme:

• AS24CI\Client — effettua richieste HTTP autenticate all'API di AutoScout24, gestisce i token OAuth (incluso la cache transitoria as24ci_access_token) ed espone helper per le pagine di anteprima e gli equipaggiamenti per singola inserzione.
• AS24CI\Importer — coordina l'importazione per singola inserzione. Decide se inserire, aggiornare o saltare e scrive l'articolo del veicolo, i relativi postmeta e i riferimenti alle immagini. Gestisce il rilevamento delle modifiche.
• AS24CI\Mapper — mappa il payload grezzo di AutoScout24 sui campi memorizzati nella tabella as24_vehicles tramite AS24CI\Vehicle_Repository. Mantiene le chiavi postmeta retrocompatibili.
• AS24CI\Vehicle_Repository — rende persistenti i dati dei campi del veicolo nella tabella dedicata {$wpdb->prefix}as24_vehicles.
• AS24CI\Image_Importer — scarica le immagini, opzionalmente le converte in WebP e le associa all'articolo del veicolo. Vedere Image Importer And Queue.
• AS24CI\Scheduler — avvolge Importer::import_all_for_seller() in un esecutore con blocco e sicuro contro i tentativi falliti, utilizzato da WP-Cron, dall'endpoint REST del cron e dal pulsante manuale "Esegui ora".

La stessa istanza di Importer viene riutilizzata dal Batch-Wizard manuale, dall'esecutore cron e dall'endpoint REST del cron.

Requisiti o prerequisiti

Prima di eseguire un'importazione sono necessari:

• Credenziali API di AutoScout24 valide configurate nel plugin (as24ci_base_url, as24ci_token_url, as24ci_client_id, as24ci_client_secret, as24ci_token_audience).
• Uno o più ID venditore in as24ci_seller_ids (separati da virgole).
• Un utente di WordPress designato come autore predefinito dell'articolo (as24ci_default_post_author); le importazioni tornano all'utente corrente quando non è impostato alcun valore predefinito.
• Accesso HTTPS in uscita funzionante dal server WordPress all'API di AutoScout24 e agli host di immagini a cui si fa riferimento nella risposta dell'API.
• Tempo di esecuzione PHP sufficiente. L'utilità di pianificazione aumenta il limite di tempo a 300 secondi tramite set_time_limit(300) per le esecuzioni cron e REST; alcuni host potrebbero ignorare questo valore.

Flusso per singola inserzione

AS24CI\Importer::upsert_post_from_listing() è la routine centrale per singola inserzione. Il flusso semplificato è:

1. Verificare che l'inserzione abbia un id. In caso contrario, saltarla.
2. Saltare le inserzioni il cui stato API non è activated o il cui flag live è vuoto.
3. Cercare un articolo di veicolo esistente tramite l'ID inserzione (find_post_id_by_listing_id()).
4. Eseguire il rilevamento delle modifiche (vedere sotto). Se nulla è cambiato, scrivere _as24ci_last_sync e restituire skipped.
5. Creare il titolo, l'estratto e il contenuto dell'articolo. Se il blocco AI (_as24ci_ai_locked = 'yes') è attivo, non sovrascrivere l'estratto o il contenuto dell'articolo.
6. Inserire o aggiornare l'articolo di WordPress con lo stato dell'articolo e l'autore predefiniti configurati.
7. Scrivere i postmeta di retrocompatibilità: _as24ci_listing_id, _as24ci_seller_id, _as24ci_last_modified (quando fornito dall'API) e _as24ci_last_sync.
8. Assicurarsi che lo slug termini con l'ID dell'inserzione (ensure_slug_has_listing_id()).
9. Mappare il payload dell'inserzione tramite AS24CI\Mapper::map_listing_to_post() in modo che i campi tipizzati vengano scritti nella tabella as24_vehicles.
10. Recuperare l'equipaggiamento tramite Client::get_listing_equipment() e mapparlo all'articolo tramite Mapper::map_equipment_to_post(). Gli errori vengono registrati nei log ma non fanno fallire l'importazione dell'inserzione.
11. Importare le immagini (soggetto all'opzione as24ci_import_images e al limite as24ci_max_images). Il flusso delle immagini è descritto in dettaglio in Image Importer And Queue.
12. Aggiornare _as24ci_content_hash e _as24ci_original_description.
13. Attivare l'azione as24ci_vehicle_imported con l'ID dell'articolo, l'inserzione API grezza e un booleano $is_update.
14. Restituire una delle stringhe inserted, updated, skipped o error (in caso di fallimento di wp_insert_post / wp_update_post).

Rilevamento delle modifiche

L'importatore salta le inserzioni che non sono cambiate rispetto all'esecuzione precedente, utilizzando due controlli a cascata:

• Principale: il campo lastModifiedDate restituito dall'API. Se il postmeta locale _as24ci_last_modified corrisponde al valore remoto, l'inserzione viene trattata come non modificata. L'importatore aggiorna comunque _as24ci_last_sync in modo che la logica di sincronizzazione completa sappia che l'inserzione esiste da remoto.
• Alternativo: quando lastModifiedDate è mancante, l'importatore calcola un MD5 del payload codificato in JSON e lo confronta con il valore memorizzato in _as24ci_content_hash.

Il rilevamento delle modifiche delle immagini viene eseguito in modo indipendente ed è descritto nella documentazione dell'importatore di immagini.

AI Lock

Quando _as24ci_ai_locked è 'yes', l'importatore mantiene i valori esistenti di post_content e post_excerpt in modo che i testi generati dall'intelligenza artificiale sopravvivano a una nuova importazione. Tutti gli altri campi, le assegnazioni delle tassonomie, gli equipaggiamenti e le immagini vengono comunque aggiornati. La descrizione originale dell'API viene inoltre conservata separatamente in _as24ci_original_description.

Stabilità dello slug

ensure_slug_has_listing_id() aggiorna lo slug dell'articolo per farlo terminare con -<listing_id> ogni volta che lo slug cambia. Ciò mantiene gli URL stabili tra le varie re-importazioni ed evita reindirizzamenti accidentali quando i titoli cambiano.

Operazioni di massa

AS24CI\Importer espone i seguenti metodi di alto livello:

• get_seller_ids() — restituisce l'elenco pulito degli ID venditore configurati.
• get_all_preview_listings_for_seller( $seller_id, $max_pages = 20, $page_size = 50 ) — scorre le pagine dell'API e restituisce l'insieme completo di inserzioni attive e pubblicate per un singolo venditore.
• preview_listings_for_seller( $seller_id, $page = 1, $per_page = 50 ) — anteprima impaginata utilizzata dall'interfaccia utente del wizard.
• import_selected_listings( $seller_id, $listing_ids, $max_vehicles = 0 ) — importa gli ID inserzione forniti. Rispetta il budget di $max_vehicles; i veicoli saltati non consumano budget.
• import_all_for_seller( $seller_id, $max_vehicles = 0 ) — recupera l'elenco completo di anteprima per un venditore e delega a import_selected_listings(). Restituisce i conteggi più listing_ids (l'insieme completo visto in questa esecuzione) e api_active (numero di inserzioni attive restituite dall'API).
• full_sync_after_import( array $remote_listing_ids ) — elimina gli articoli locali di as24ci_car il cui _as24ci_listing_id non è presente nel set remoto fornito. Saltato se il set remoto è vuoto come misura di sicurezza contro cancellazioni accidentali.
• hard_delete_listing( $listing_id ) — eliminazione distruttiva manuale per una singola inserzione; esegue la stessa pulizia di Vehicle_Deleter dell'eliminazione nativa di WordPress.

La versione "All-in-One" del plugin non impone alcun limite alle inserzioni; get_free_import_limit() e get_free_slots_left() restituiscono PHP_INT_MAX.

Eliminazione dei veicoli

Ogni percorso di eliminazione permanente passa attraverso AS24CI\Vehicle_Deleter:

• L'azione nativa "Elimina definitivamente" di WordPress nell'elenco Auto.
• Sincronizzazione completa dell'importatore (full_sync_after_import()).
• Azioni di massa (AS24CI\Bulk_Actions).
• Importer::hard_delete_listing() manuale.

L'eliminatore viene eseguito su before_delete_post / deleted_post e:

• Rimuove gli allegati tracciati in _as24ci_image_ids.
• Rimuove la riga corrispondente in {$wpdb->prefix}as24_vehicles.
• Attiva l'azione as24ci_vehicle_deleted.

Gli allegati manuali della galleria (_as24ci_manual_image_ids) e altri allegati non tracciati dall'importatore vengono intenzionalmente conservati.

Hook pubblici

Il motore di importazione attiva i seguenti hook. Verificare le firme degli hook nell'attuale versione del plugin prima di fare affidamento su di essi.

Il plugin legge anche il filtro as24ci_webp_quality durante la conversione delle immagini; vedere la documentazione dell'importatore di immagini.

Riferimento di configurazione

Note operative

• L'importatore non si interrompe mai a causa di una singola inserzione errata. Gli errori provenienti da wp_insert_post, wp_update_post, Client::get_listing_equipment e dall'importatore di immagini vengono registrati tramite AS24CI\Logger e conteggiati ma non interrompono l'esecuzione.
• Il rilevamento delle modifiche significa che una re-importazione completa di un catalogo non modificato è economica: la maggior parte delle inserzioni viene saltata e i download delle immagini non vengono effettuati nuovamente.
• Il mappatore scrive sulla tabella as24_vehicles tramite il repository, non su wp_postmeta, ad eccezione del piccolo set di chiavi di retrocompatibilità documentato in Data Model.
• La sincronizzazione completa è opzionale. Se as24ci_full_sync è abilitato, assicurarsi che gli ID venditore configurati coprano l'intero catalogo che si desidera mantenere online; i veicoli le cui inserzioni scompaiono dall'API vengono eliminati in modo permanente.
• La registrazione dettagliata (verbose) produce righe di log dettagliate e cresce rapidamente su cataloghi di grandi dimensioni. Il plugin impone un limite di 10 MB per i log con rotazione; regolare la registrazione dettagliata per bilanciare la diagnostica con lo spazio di archiviazione.

Risoluzione dei problemi

• Nessun veicolo importato. Verificare le credenziali API, che as24ci_seller_ids non sia vuoto e che l'API restituisca inserzioni con status = activated e live = true. Controllare il log del plugin per eventuali errori HTTP da AS24CI\Client.
• Le inserzioni rimangono nello stato draft. Il plugin imposta come predefinito as24ci_default_post_status su draft in modo che gli amministratori possano rivedere le mappature. Cambiare l'opzione in publish una volta che si è soddisfatti, oppure pubblicare i singoli veicoli dall'elenco di amministrazione.
• Re-importazioni ripetute continuano ad aggiornare gli stessi veicoli. Verificare che l'API fornisca un valore lastModifiedDate stabile. Quando questo è mancante, l'hash del contenuto alternativo rileva le modifiche; l'hash cambierà ogni volta che il payload dell'API cambia per qualsiasi motivo.
• Un veicolo è scomparso dopo un'esecuzione cron. Controllare se as24ci_full_sync è abilitato. Con la sincronizzazione completa attiva, qualsiasi inserzione mancante dall'API viene eliminata in modo permanente (inclusi i relativi allegati importati).
• Importer ran but no images were downloaded. Controllare as24ci_import_images e as24ci_max_images. Nelle esecuzioni cron/REST con as24ci_cron_image_queue = 1, solo la prima immagine viene scaricata immediatamente e le restanti vengono rimandate al worker della coda delle immagini.
• Skipping listing_id=… : lastModifiedDate unchanged. Questa è la riga di log dettagliata prevista per le inserzioni non modificate; conferma che il rilevamento delle modifiche funziona correttamente.

---

---

Documenti correlati

• Importatore di immagini e coda
• Eventi Cron e pianificatore
• Panoramica dell'architettura
• Modello dei dati
• Schema del database
• Panoramica della sezione