Vai al contenuto

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.enabled non è 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:

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.include un 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 status segnala 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

Shell
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:

Codice
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.

JSON
{
  "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.

JSON
{
  "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à

  1. Registrate il tipo di post di destinazione in ogni ambiente.
  2. Configurate content.postTypes, meta.include e gli eventuali riferimenti dichiarati.
  3. Eseguite wp bs content pull nell’ambiente sorgente.
  4. Eseguite il commit dei file generati.
  5. Eseguite wp bs content push nell’ambiente di destinazione.
  6. Eseguite wp bs content status per 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, attachment e term dichiarati
  • 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, --prune e 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.