Importatore di immagini e coda

Questo documento descrive come il plugin ADP Car Market Hub scarica, deduplica e associa le immagini dei veicoli, e come la coda asincrona delle immagini sposta le operazioni di elaborazione delle immagini a lungo termine al di fuori del percorso di importazione sincrono.

Quando utilizzare questo documento

Leggi questo documento se hai bisogno di:

• Capire quali immagini finiscono nella Libreria media di WordPress e quali vengono riutilizzate o saltate.
• Diagnosticare immagini dei veicoli mancanti, obsolete o duplicate.
• Pianificare la conversione in WebP o la capacità di archiviazione per un catalogo di grandi dimensioni.
• Ottimizzare l'elaborazione delle immagini in modalità cron per hosting lenti o limitati.

Per il flusso di importazione generale, consulta Import Engine. Per la pianificazione lato cron, consulta Cron Events And Scheduler.

Panoramica

Due classi condividono la responsabilità della gestione delle immagini:

• AS24CI\Image_Importer — scarica un elenco di URL di immagini, opzionalmente le converte in WebP, le associa a un articolo di tipo veicolo tramite media_handle_sideload() e registra l'URL di origine nel postmeta dell'allegato per la deduplicazione.
• AS24CI\Scheduler — gestisce la coda asincrona delle immagini. L'hook del worker as24ci_image_queue_process elabora gli elementi in sospeso in batch con un proprio blocco transitorio e un budget di tempo dedicato.

L'importatore (Import Engine) decide se importare le immagini in modo sincrono o differirne la maggior parte nella coda, in base alla modalità cron dell'esecuzione corrente.

Fonte di verità per le immagini

Per qualsiasi allegato importato, il marcatore canonico "da dove proviene questo elemento?" è il postmeta _as24ci_source_url sull'articolo allegato (attachment). Il plugin utilizza questo marcatore per:

• Deduplicare i download — se esiste già un allegato con lo stesso URL di origine, il plugin lo riutilizza anziché scaricarlo nuovamente.
• Ricostruire l'elenco _as24ci_image_ids del veicolo in modo autorevole al termine del lavoro del worker della coda, interrogando gli allegati figli con questa chiave meta.

Due chiavi postmeta sull'articolo veicolo tengono traccia delle immagini importate:

• _as24ci_image_ids — array di ID allegato WordPress che appartengono alla galleria dell'importatore.
• _as24ci_images_hash — hash MD5 dell'elenco delle immagini di origine. Può contenere il valore sentinella 'pending_queue' mentre gli elementi sono ancora in coda. L'importazione successiva tratterà 'pending_queue' come una mancata corrispondenza, in modo che l'elenco delle immagini venga sempre rivalutato fino a quando non sarà completamente importato.

Gli allegati della galleria aggiunti manualmente vengono tracciati separatamente in _as24ci_manual_image_ids e non vengono mai eliminati dal plugin.

Importazione sincrona delle immagini

Image_Importer::import_images( int $post_id, array $images, string $listing_id ) esegue il lavoro sincrono:

1. Include in modo lazy i file di amministrazione dei media di WordPress (wp-admin/includes/media.php, file.php, image.php).
2. Riapplica in modo difensivo la capacità as24ci_max_images.
3. Pre-recupera gli URL di origine noti dell'articolo in un'unica operazione tramite prefetch_known_urls_for_post() per evitare N query di database per singola immagine.
4. Per ogni immagine (URL stringa o array con le chiavi url / src / href / original / imageUrl): - Riutilizza un allegato esistente se l'URL di origine è già noto (prima tramite mappa in memoria, poi tramite una ricerca postmeta _as24ci_source_url). - In caso contrario, chiama download_url( $url, 30 ) (timeout di 30 secondi), opzionalmente converte in WebP e chiama media_handle_sideload() per creare l'allegato. - Scrive _as24ci_source_url sul nuovo allegato e lo aggiunge alla mappa di deduplicazione in memoria. - Registra i fallimenti nei log (errori di download, errori di sideload) e passa all'immagine successiva.
5. Unisce i nuovi ID allegato in _as24ci_image_ids (preservando gli elementi importati in precedenza) e imposta l'immagine in evidenza (post thumbnail) sul primo allegato se l'articolo non ne ha già una.

Gli ID esistenti vengono uniti anziché sovrascritti, in modo che le chiamate del worker della coda accumulino gli allegati per lo stesso articolo nel corso di più esecuzioni.

Conversione in WebP

Quando as24ci_convert_to_webp è impostato su 1, l'importatore tenta di convertire ogni immagine scaricata in WebP prima del sideload:

• La qualità viene letta da as24ci_webp_quality (valore predefinito 80 se non impostato) e limitata all'intervallo 1–100. Il filtro as24ci_webp_quality può sovrascrivere il valore.
• Viene tentata prima la funzione imagewebp() di GD; Imagick viene utilizzato come fallback.
• Se nessuna delle due estensioni è disponibile, la conversione viene saltata e viene eseguito il sideload dell'immagine originale. Viene emessa una riga di log.
• Se la conversione produce un file vuoto o fallisce, il file temporaneo viene rimosso e viene utilizzata l'immagine originale.

Il file convertito eredita il nome del file originale con l'estensione sostituita da .webp.

Importazione in modalità cron (in coda)

Quando il pianificatore esegue un'importazione (cron o REST), imposta Importer::set_cron_image_queue( true ) se as24ci_cron_image_queue è 1 (il valore predefinito). Per ogni veicolo con più di un'immagine, l'importatore:

1. Scarica solo la prima immagine immediatamente tramite il percorso sincrono, in modo che il veicolo abbia un'immagine in evidenza.
2. Verifica preventivamente se tutte le immagini rimanenti sono già associate (tramite la mappa di deduplicazione). In caso affermativo, non viene creata alcuna voce in coda e il valore finale _as24ci_images_hash viene scritto immediatamente.
3. In caso contrario, chiama enqueue_remaining_images() per aggiungere elementi nel formato { post_id, listing_id, url, images_hash } all'opzione as24ci_image_queue. Il valore _as24ci_images_hash del veicolo viene impostato sulla sentinella 'pending_queue' in modo che le importazioni future continuino a rivalutare la coda fino al suo completamento.

La coda ha un limite massimo rigido di Scheduler::IMAGE_QUEUE_SIZE_LIMIT elementi. Le nuove voci vengono scartate al raggiungimento del limite e viene emessa una riga di log.

Worker della coda

AS24CI\Scheduler::run_image_queue() è associato all'hook cron as24ci_image_queue_process ed esegue i download differiti effettivi:

1. Chiama set_time_limit(300) (soggetto alle restrizioni dell'host).
2. Acquisisce il blocco transitorio as24ci_image_queue_running con il TTL Scheduler::IMAGE_QUEUE_LOCK_TTL. Un blocco obsoleto (più vecchio del TTL) viene rimosso automaticamente.
3. Carica la coda dall'opzione as24ci_image_queue.
4. Elabora gli elementi in batch di Scheduler::IMAGE_QUEUE_BATCH_SIZE finché la coda non è vuota e il budget di tempo (IMAGE_QUEUE_LOCK_TTL − 60s) non è esaurito.
5. Per ogni elemento, chiama Image_Importer::import_images() per il singolo URL. Gli errori vengono intercettati e registrati nei log; l'elemento viene rimosso per evitare un ciclo infinito causato da un elemento corrotto.
6. Salva la coda rimanente e scrive le statistiche per esecuzione su as24ci_image_queue_last_run ({ processed, failed, remaining, timestamp }).
7. Per ogni articolo completamente rimosso dalla coda in questa esecuzione, ricostruisce _as24ci_image_ids in modo autorevole dagli allegati figli effettivi contrassegnati con _as24ci_source_url e memorizza il valore finale _as24ci_images_hash. Questo garantisce che i metadati siano completi e coerenti anche se singoli elementi della coda non sono andati a buon fine.
8. Pianifica l'esecuzione successiva tramite maybe_schedule_image_queue_worker() se rimangono elementi.

Il valore images_hash del worker viene convalidato come stringa MD5 minuscola di 32 caratteri prima dell'uso. Le voci corrotte vengono trattate come assenti, in modo che l'hash dell'articolo non venga finalizzato a partire da dati errati.

Riferimento di configurazione

I valori esatti di IMAGE_QUEUE_LOCK_TTL, IMAGE_QUEUE_BATCH_SIZE e IMAGE_QUEUE_SIZE_LIMIT sono definiti come costanti su AS24CI\Scheduler e possono variare tra le versioni del plugin. Verificali nel codice sorgente corrente se hai bisogno di pianificare un carico specifico.

Note operative

• WP-Cron è l'attivatore predefinito. Sui siti a basso traffico, considera l'utilizzo di un cron lato server / cron di sistema che punti a wp-cron.php (con DISABLE_WP_CRON impostato su true) in modo che la coda si svuoti in modo prevedibile.
• I download delle immagini vengono eseguiti tramite download_url() che utilizza l'API HTTP di WordPress. Gli host che bloccano l'HTTP in uscita devono inserire nella whitelist gli host di immagini di AutoScout24.
• La deduplicazione delle immagini si basa sull'URL di origine esatto. Gli URL che differiscono solo per la stringa di query o per i parametri di firma verranno trattati come origini distinte e scaricati separatamente.
• Gli allegati manuali della galleria tracciati in _as24ci_manual_image_ids non vengono mai sovrascritti o rimossi dall'importatore o dal worker della coda.
• Il worker della coda ricostruisce _as24ci_image_ids dagli allegati figli effettivi al termine di ogni articolo completamente elaborato; se manipoli i metadati direttamente tra le esecuzioni del worker, le tue modifiche potrebbero essere annullate.

Risoluzione dei problemi

• I veicoli appaiono senza immagini. Verifica che as24ci_import_images sia abilitato. Controlla che as24ci_max_images sia diverso da zero dove previsto. In modalità cron, l'immagine principale viene importata in modo sincrono; se non appare alcuna immagine, cerca eventuali errori di download nel log del plugin.
• È presente solo la prima immagine dopo un'importazione cron. Questo è il comportamento previsto durante le importazioni in modalità cron fino al completamento del worker as24ci_image_queue_process. Controlla as24ci_image_queue_last_run per verificare lo stato di avanzamento e la dimensione della coda.
• La coda cresce ma non si svuota mai. Verifica che WP-Cron sia in esecuzione (o che un cron di sistema attivi wp-cron.php). Controlla la presenza di un transitorio as24ci_image_queue_running bloccato più vecchio del TTL del worker. Il worker rimuove automaticamente i blocchi obsoleti all'esecuzione successiva.
• La conversione in WebP non avviene. Assicurati che as24ci_convert_to_webp sia impostato su 1 e che sia installata la libreria GD con supporto WebP (imagewebp) o Imagick. Il plugin registra nei log il motivo per cui la conversione viene saltata.
• Nella galleria appaiono immagini che sembrano duplicate. La chiave di deduplicazione è l'URL di origine esatto. Le CDN che aggiungono parametri di query univoci per richiesta impediranno la deduplicazione. Verifica gli URL nel payload dell'API tramite il logging dettagliato.
• Le immagini sono scomparse dopo aver eliminato un veicolo. L'operazione Vehicle_Deleter rimuove gli allegati tracciati in _as24ci_image_ids. Gli allegati manuali della galleria (_as24ci_manual_image_ids) vengono preservati. Verifica quale elenco conteneva l'ID dell'allegato interessato.

Documenti correlati

• Import Engine
• Cron Events And Scheduler
• Data Model
• Database Schema
• Panoramica della sezione