Sincronizzazione dei contenuti
Blockstudio si basa su un flusso di lavoro incentrato sui file: blocchi, campi, template, asset, pattern e pagine basate su file possono risiedere tutti nel vostro progetto. La sincronizzazione dei contenuti estende questo modello a contenuti selezionati del database WordPress, per i team che vogliono anche gestire post, termini, relazioni e metadati dichiarati in modo curato tramite git.
È un flusso di lavoro WP-CLI, non una replica del database in tempo reale. Durante il pull, la sincronizzazione dei contenuti esporta post, postmeta, termini, termmeta e relazioni post-termine autorizzati in file portabili nel tema. Durante il push, applica quei file a un altro ambiente usando UID stabili e riscrive solo i riferimenti dichiarati esplicitamente.
Nota
La sincronizzazione dei contenuti è su richiesta. Non viene eseguita a ogni richiesta di amministrazione. I comandi restituiscono una riga saltata finché
content.enablednon ètrue.
Quando usare la sincronizzazione dei contenuti
Usate la sincronizzazione dei contenuti per insiemi di contenuti importanti da versionare, revisionare e trasferire tra ambienti:
- contenuti strutturati come membri del team, sedi, casi di studio, prodotti, voci di documentazione o pagine di campagne
- tassonomie e relazioni associate a tali insiemi di contenuti
- metadati autorizzati, sicuri da salvare nel repository e che richiedono riferimenti stabili
- insiemi di contenuti da piccoli a medi, per cui è ancora pratico revisionare i file in git
Come regola generale, la sincronizzazione dei contenuti è adatta a decine o centinaia di righe e può gestirne alcune migliaia se i dati sono strutturati, cambiano di rado e sono suddivisi in tipi di post mirati. Non è pensata per replicare un intero database di produzione, contenuti editoriali ad alto traffico, log, ordini, analisi, invii di moduli, sessioni o altri dati voluminosi o soggetti a frequenti modifiche. Se i file generati sono difficili da revisionare, i push richiedono troppo tempo per essere valutati o la maggior parte delle righe cambia al di fuori del flusso di distribuzione, usate invece uno strumento di backup, migrazione o importazione/esportazione del database.
I file multimediali binari non vengono copiati. I riferimenti agli allegati possono essere registrati in un manifesto e convalidati, ma i file devono già esistere nell’ambiente di destinazione.
Configurazione
Abilitate la sincronizzazione dei contenuti in blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"content": {
"enabled": true,
"id": "default",
"path": "content",
"includePageSyncManaged": false,
"authors": "ignore",
"postTypes": ["team_member"],
"meta": {
"include": ["_my_*"],
"exclude": ["_edit_lock", "_edit_last", "_wp_old_slug"],
"references": {
"_thumbnail_id": { "kind": "attachment" },
"_related_posts": { "kind": "post", "path": "*" },
"_hero": { "kind": "attachment", "path": "image.id" }
}
},
"taxonomies": [],
"media": "manifest"
}
}
postTypes è un elenco di autorizzazione. Se è vuoto, la sincronizzazione dei contenuti non interviene sui post. taxonomies è un elenco di tassonomie già registrate i cui termini e relazioni con i post devono essere sincronizzati. Blockstudio non registra definizioni di tassonomie dai file della sincronizzazione dei contenuti. I metadati di post e termini sono autorizzati tramite meta.include; meta.exclude ha sempre la precedenza.
Avvertenza
Considerate
meta.includeun confine per il commit. I file sincronizzati sono destinati a essere conservati in git, quindi non includete chiavi contenenti segreti, token, credenziali o dati personali identificativi.wp bs content statussegnala righe di avviso quando una chiave di metadati autorizzata sembra contenere dati sensibili.
content.id viene memorizzato nelle entità sincronizzate come _blockstudio_content_set. Le verifiche di eliminazione e proprietà si basano su quel valore, così un insieme di contenuti non può cancellare i contenuti di un altro.
Per impostazione predefinita, i post gestiti dalla sincronizzazione delle pagine sono esclusi. Se includePageSyncManaged è abilitato, la sincronizzazione dei contenuti può sincronizzarne i metadati configurati, ma la sincronizzazione delle pagine mantiene la gestione di post_content.
Queste proiezioni contengono "bodyOwner": "page-sync". Pull segnala la scrittura JSON come composta solo da metadati e aggiunge una riga del corpo skipped, invece di presentare l’articolo come se avesse un corpo vuoto. Non scrive né elimina un file .html associato. Una copia di revisione esistente viene mantenuta e ignorata da push. Gli stessi messaggi sulla proprietà sono inclusi nell’output di dry-run.
In un altro ambiente, eseguite prima Page Sync. Una proiezione con
bodyOwner: "page-sync" deve fare riferimento a un post esistente gestito da Page Sync;
push rifiuta di creare un segnaposto vuoto o di applicare la copia di revisione di quel contenuto.
Le proiezioni senza il marcatore delle versioni precedenti continuano a essere supportate.
Per impostazione predefinita, gli autori vengono ignorati perché gli utenti non vengono sincronizzati. Impostate authors: "login" per salvare il nome di accesso dell’autore nei file dei post e risolverlo in un utente esistente durante il push. Gli utenti mancanti causano un errore nella verifica preliminare; la sincronizzazione dei contenuti non crea utenti.
Comandi
wp bs content pull [--post-type=<type>] [--taxonomy=<taxonomy>] [--dry-run]
wp bs content push [--dry-run] [--prune] [--yes]
wp bs content status
pull acquisisce i contenuti del database e li salva in file. Assegna _blockstudio_content_uid ai post nell’ambito che ne sono ancora sprovvisti e segnala i file obsoleti la cui origine nel database non esiste più. Il pull non elimina i file obsoleti.
push applica i file al database corrente. Convalida il piano prima di scrivere e blocca i riferimenti dichiarati non risolti, i conflitti tra slug, le entità bloccate e i tipi di post mancanti.
status confronta i file con il database e segnala ogni entità come unchanged, would-update, missing-db, conflict, locked o orphaned. Segnala anche le chiavi di metadati autorizzate che sembrano contenere segreti, prima che tali valori vengano registrati nel repository, e i numeri ID nei corpi del markup dei blocchi, perché la sincronizzazione dei contenuti non riscrive gli ID nei file .html.
Usate --dry-run per esaminare un pull o un push senza scrivere modifiche. Usate push --prune --yes per rimuovere dal database le entità appartenenti a un insieme di contenuti che non esistono più nei file.
Gestione sicura degli errori
push analizza e convalida il piano completo delle fonti prima di scrivere o
eliminare elementi. I file JSON malformati, i riferimenti dichiarati non risolti, le assegnazioni di proprietà non valide e
altri errori nella verifica preliminare bloccano la fase distruttiva. L’eliminazione resta limitata
a tipi di post, tassonomie e content.id configurati.
pull scrive ogni file esportato prima di registrare l’entità come sincronizzata. Se la scrittura sul file system non riesce, viene restituita una riga di errore e lo stato di sincronizzazione salvato per quell’entità non viene aggiornato.
La gestione degli allegati segue content.media. Con "manifest", gli UID degli allegati referenziati devono esistere nell’ambiente di destinazione. Con "none", i riferimenti agli allegati dichiarati vengono rimossi intenzionalmente dall’output portabile, invece di conservarne gli ID specifici dell’ambiente.
File
Content Sync scrive i file nella directory content.path configurata:
content/
posts/
team_member/
jane.9b1c0e6e.json
jane.9b1c0e6e.html
terms/
category/
leadership.5e900000.json
media/
manifest.json
I file dei post .json contengono identità, campi del post, relazioni con i termini, metadati dichiarati e codifica dei metadati. Il file .html associato contiene post_content come markup grezzo dei blocchi e viene omesso quando il contenuto è vuoto. I file dei termini .json contengono identità, tassonomia, slug, nome, descrizione, UID del termine genitore, termmeta dichiarati e codifica dei metadati.
L’altro caso senza un file .html è un contenuto gestito da Page Sync, identificato da
bodyOwner sopra. Per i post ordinari il cui contenuto diventa vuoto, pull rimuove
il vecchio file del contenuto e lo indica in una riga separata del contenuto deleted.
{
"uid": "9b1c0e6e-0000-4000-9000-000000000000",
"type": "team_member",
"status": "publish",
"slug": "jane",
"title": "Jane",
"parent": null,
"menuOrder": 0,
"terms": {
"category": ["5e900000-0000-4000-9000-000000000000"]
},
"meta": {
"_my_subtitle": "Creative Director",
"_thumbnail_id": "a1b2c3d4-0000-4000-9000-000000000000"
},
"metaEncoding": {
"_my_subtitle": "scalar",
"_thumbnail_id": "scalar"
}
}
Lo stato di sincronizzazione memorizzato è:
| Chiave meta | Scopo |
|---|---|
_blockstudio_content_uid |
Identità portabile del contenuto |
_blockstudio_content_set |
Namespace del set di contenuti da content.id |
_blockstudio_content_source |
Percorso del file sorgente relativo al tema |
_blockstudio_content_fingerprint |
Ultima impronta digitale sincronizzata del file/database |
_blockstudio_content_locked |
Un valore truthy impedisce al push di sovrascrivere l’entità |
Riferimenti
Content Sync non presume mai che un numero intero sia un ID. I riferimenti vengono riscritti solo quando configurati in meta.references.
{
"meta": {
"references": {
"_related_posts": { "kind": "post", "path": "*" },
"_topic": { "kind": "term" },
"_hero": { "kind": "attachment", "path": "image.id" }
}
}
}
Durante il pull, gli ID locali in quei percorsi diventano UID portabili. Durante il push, gli UID vengono risolti nuovamente negli ID locali del database corrente.
I post genitori, i termini genitori e le relazioni post-termine sono riferimenti strutturali gestiti da Content Sync e vengono memorizzati automaticamente come UID. Le tassonomie configurate vengono scritte nei file dei post anche quando sono vuote; un array vuoto cancella le relazioni di quella tassonomia durante il push.
I riferimenti agli allegati vengono convalidati, non importati. Con media: "manifest", gli allegati referenziati sono elencati in content/media/manifest.json; il push richiede che l’UID dell’allegato referenziato esista localmente. Con media: "none", i riferimenti agli allegati dichiarati vengono omessi dai file portabili. Poiché una chiave omessa non viene applicata durante il push, un post di destinazione esistente conserva i metadati degli allegati correnti.
Flusso di lavoro per la portabilità
- Registrate il tipo di post di destinazione in ogni ambiente.
- Configurate
content.postTypes,meta.includee gli eventuali riferimenti dichiarati. - Eseguite
wp bs content pullnell’ambiente sorgente. - Eseguite il commit dei file generati.
- Eseguite
wp bs content pushnell’ambiente di destinazione. - Eseguite
wp bs content statusper verificare che il database corrisponda ai file.
I file sono la fonte attendibile per push. Il database viene acquisito nuovamente nei file con pull.
Ambito
Content Sync supporta:
- post appartenenti a tipi di post inclusi nella allowlist
- postmeta inclusi nella allowlist
- termini appartenenti a tassonomie registrate incluse nella allowlist
- termmeta inclusi nella allowlist
- relazioni post-termine
- riferimenti
post,attachmentetermdichiarati - UID portabili per post e termini e proprietà dei set di contenuti
- esclusione predefinita di Page Sync
- manifesto degli allegati e convalida preliminare
- gestione di
pull,push,status,--dry-run,--prunee delle entità bloccate
L’acquisizione delle definizioni delle tassonomie, la copia dei file binari multimediali e la riscrittura degli ID nel markup dei blocchi non sono supportate.