Preskoči na vsebino

Selitev vsebine zbirke podatkov v datoteke s sinhronizacijo vsebine

Bloki, predloge in strani iz datotek že živijo v vašem repozitoriju. Nekatera vsebina ne sodi v ta model, ker jo uredniki ustvarijo v skrbništvu: člani ekipe, lokacije pisarn, študije primerov. Tudi ta vsebina je za projekt pomembna. Testno mesto potrebuje isto stran ekipe kot produkcijsko, nov razvijalec potrebuje realistične podatke, pregledovalec pa bi moral videti, ko kdo spremeni naziv delovnega mesta. Izpisi zbirke podatkov tega ne rešijo dobro. Vsebujejo vse, ID-ji se med okolji razlikujejo in nihče ne pregleduje razlik SQL.

Content Sync zapolni to vrzel. Ukaz WP-CLI projicira seznam dovoljenih objav, izrazov, povezav in metapodatkov v datoteke JSON in HTML v vaši temi. Drug ukaz te datoteke uporabi v drugi zbirki podatkov. Vsaka entiteta dobi prenosljiv UID, sklici med entitetami pa se prepišejo samo tam, kjer jih določite.

Ta vodnik vas popelje skozi imenik ekipe: prenos v datoteke, pregled, urejanje datoteke, prenos v novo okolje in varno čiščenje.

Primer

Tema v vsakem okolju registrira vrsto objave acme_member in taksonomijo acme_team. Vsaka objava člana lahko vsebuje:

Ključ meta Vsebina
_acme_role Naziv delovnega mesta, navadno besedilo
_acme_mentor ID objave drugega člana
_thumbnail_id ID priloge s portretom
_acme_api_token Žeton za integracijo, ki nikoli ne sme priti do git

Content Sync nikoli ne registrira vrst objav ali taksonomij. Obstajati morajo v vsakem okolju, kamor pošiljate podatke.

1. korak: konfigurirajte Content Sync

Content Sync je izklopljen, dokler ga ne omogočite v blockstudio.json. Do takrat vsak ukaz vrne eno samo vrstico skipped:

Lupina
wp bs content status
Koda
action   entity   id       uid  message
skipped  content  default       Content Sync is disabled. Set content.enabled to true to run this command.

Dodajte skupino content:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "content": {
    "enabled": true,
    "id": "team",
    "path": "content",
    "postTypes": ["acme_member"],
    "taxonomies": ["acme_team"],
    "meta": {
      "include": ["_acme_*", "_thumbnail_id"],
      "references": {
        "_acme_mentor": { "kind": "post" },
        "_thumbnail_id": { "kind": "attachment" }
      }
    },
    "media": "manifest"
  }
}

Vsak ključ določa mejo:

  • postTypes in taxonomies sta seznama dovoljenih vrednosti. Zunaj njiju se nič ne bere, zapisuje ali odstranjuje. Prazen postTypes pomeni, da se nobene objave ne spremeni.
  • meta.include določa dovoljene ključe meta in podpira nadomestne znake *. meta.exclude ima vedno prednost, _edit_lock, _edit_last in _wp_old_slug pa so privzeto izključeni.
  • meta.references določa, katere vrednosti meta so ID-ji. Content Sync ne ugiba, ali je celo število ID.
  • id poimenuje nabor vsebine. Shrani se v vsako sinhronizirano entiteto, odstranjevanje pa zadeva samo entitete iz istega nabora.
  • path je izhodna mapa glede na imenik trenutno aktivne teme.

2. korak: prenos

Najprej si oglejte predogled projekcije. Nič se ne zapiše, prikazani UID-ji pa še niso shranjeni:

Lupina
wp bs content pull --dry-run
Koda
action       entity  id   uid          message
would-write  post    530  4c8e9997-...  .../posts/acme_member/jane.4c8e9997.json
would-write  post    531  6cddc303-...  .../posts/acme_member/sam.6cddc303.json
would-write  term    4    6661b6d9-...  .../terms/acme_team/leadership.6661b6d9.json

Nato zares izvedite pull. To vsakemu subjektu, ki ga še nima, dodeli trajni _blockstudio_content_uid in zapiše datoteke:

Lupina
wp bs content pull
Koda
action   entity  id        uid          message
written  post    530       5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
written  post    531       208db72e-...  .../posts/acme_member/sam.208db72e.json
written  term    4         7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
written  media   manifest                .../media/manifest.json

Rezultat v temi:

Koda
content/
├── media/
│   └── manifest.json
├── posts/
│   └── acme_member/
│       ├── jane.5d4bf9b5.html
│       ├── jane.5d4bf9b5.json
│       └── sam.208db72e.json
└── terms/
    └── acme_team/
        └── leadership.7491a6a1.json

Imena datotek združujejo oznako z začetnim delom UID-ja. Objava JSON vsebuje polja, povezave do izrazov in dovoljena meta polja:

JSON
{
    "uid": "5d4bf9b5-16b7-4975-acc6-51dc1d4e49ec",
    "type": "acme_member",
    "status": "publish",
    "slug": "jane",
    "title": "Jane Doe",
    "date": "2026-10-13T03:03:02+00:00",
    "modified": "2026-10-13T03:03:02+00:00",
    "parent": null,
    "menuOrder": 0,
    "terms": {
        "acme_team": [
            "7491a6a1-702c-4a29-9993-9ae7b2a79c0a"
        ]
    },
    "meta": {
        "_acme_role": "Design Lead",
        "_thumbnail_id": "72a2db75-6fd2-41f9-8d3c-b323ce3b3551"
    },
    "metaEncoding": {
        "_acme_role": "scalar",
        "_thumbnail_id": "scalar"
    }
}

Povezava do izraza in sličica sta UID-ja, ne lokalna ID-ja. Telo objave je poleg njega v jane.5d4bf9b5.html, kot neobdelana oznaka blokov. Objava s prazno vsebino, kot je Samova, nima datoteke .html. Samov _acme_mentor je shranjen kot Janein UID, ker je ključ določen kot sklic post.

3. korak: pregled pred objavo sprememb

Pred objavo sprememb zaženite status. Primerja datoteke z zbirko podatkov in označi tudi rizične podatke:

Lupina
wp bs content status
Koda
action     entity  id               uid          message
unchanged  post    530              5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
unchanged  post    531              208db72e-...  .../posts/acme_member/sam.208db72e.json
unchanged  term    4                7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
warning    meta    _acme_api_token                Allowlisted meta key may contain secrets or PII; review before committing synced files.

Nadomestni znak _acme_* je zajel žeton. Obravnavajte meta.include kot mejo objave sprememb in izrecno izključite ta ključ:

JSON
"meta": {
  "include": ["_acme_*", "_thumbnail_id"],
  "exclude": ["_acme_api_token"],
  "references": {
    "_acme_mentor": { "kind": "post" },
    "_thumbnail_id": { "kind": "attachment" }
  }
}

Naslednji zagon pull prepiše sam.208db72e.json brez žetona, druge datoteke pa pusti nedotaknjene. status opozori tudi na številske ID-je v telesih oznake blokov, saj Content Sync v datotekah .html ne prepisuje ID-jev.

Objavite mapo content/.

4. korak: uredite datoteko in pošljite spremembe

Datoteke so vir resnice za push. V datoteki JSON spremenite Janeino vlogo iz Design Lead v Head of Design, nato preverite, kaj bi se zgodilo:

Lupina
wp bs content status
Koda
action        entity  id   uid          message
would-update  post    530  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
unchanged     post    531  208db72e-...  .../posts/acme_member/sam.208db72e.json
unchanged     term    4    7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json

push --dry-run izpiše enak načrt v vrstnem redu pošiljanja. Uporabite ga:

Lupina
wp bs content push
Koda
action     entity  id   uid          message
unchanged  term    4    7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
updated    post    530  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
unchanged  post    531  208db72e-...  .../posts/acme_member/sam.208db72e.json

Pred zapisom Push preveri celoten načrt. Nerazrešeni določeni sklici, spori oznak, manjkajoče vrste objav in nepravilno oblikovane datoteke ustavijo postopek.

WordPress posodobljeni objavi nastavi nov čas spremembe, medtem ko je v datoteki še vedno stara vrednost modified. Zato zagon status takoj po tem pošiljanju Janeino objavo označi kot conflict s sporočilom »Zbirka podatkov je bila spremenjena od zadnje sinhronizacije.« Po pošiljanju enkrat zaženite pull, da zajamete novi čas; status nato poroča unchanged.

5. korak: prenos vsebine v drugo okolje

V novem okolju datoteke opisujejo objave, ki še ne obstajajo. V tem primeru tam že obstajata izraz in priloga s portretom z enakima UID-jema, zato manjkata samo člana:

Lupina
wp bs content status
Koda
action      entity  id    uid          message
missing-db  post    jane  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
missing-db  post    sam   208db72e-...  .../posts/acme_member/sam.208db72e.json
unchanged   term    4     7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
Lupina
wp bs content push
Koda
action     entity  id   uid          message
unchanged  term    4    7491a6a1-...  .../terms/acme_team/leadership.7491a6a1.json
created    post    536  5d4bf9b5-...  .../posts/acme_member/jane.5d4bf9b5.json
created    post    537  208db72e-...  .../posts/acme_member/sam.208db72e.json

Objavi sta dobili nova lokalna ID-ja, 536 in 537. Sklici so se ohranili: Samov _acme_mentor zdaj vsebuje 536, Jane je znova v izrazu leadership, njen _thumbnail_id pa kaže na lokalno prilogo z ustreznim UID-jem. Nadrejene objave, nadrejeni izrazi in povezave do izrazov so vedno shranjeni kot UID-ji; vrednosti meta se prepišejo samo za ključe v meta.references.

Varno odstranjevanje

Brisanje datoteke pri pošiljanju ne izbriše ničesar, razen če to zahtevate. Odstranite sam.208db72e.json in poskusite z odstranjevanjem:

Lupina
wp bs content push --prune
Koda
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.

Poskusni zagon pokaže, kaj bi bilo odstranjeno:

Lupina
wp bs content push --prune --dry-run
Koda
action             entity  id   uid          message
...
would-prune-trash  post    537  208db72e-...

push --prune --yes nato premakne Samovo objavo v koš in prikaže pruned-trash. Postopek omejuje več varovalk:

  • Kandidatke so samo entitete, ki pripadajo temu naboru vsebine (content.id).
  • Upoštevajo se samo konfigurirane vrste objav in taksonomije.
  • Celoten izvorni načrt se razčleni in preveri, preden se karkoli zapiše ali odstrani. Če je v mapi nepravilno oblikovana datoteka JSON, Push sporoči vrstico error, na primer could not be read: Syntax error, in ne odstrani ničesar.

Privzeto dejanje je trash. Filter blockstudio/content/orphan_action lahko za posamezno entiteto vrne trash, delete ali keep. Tako se izrazi ohranijo, objave pa ostanejo pri privzeti nastavitvi:

PHP
add_filter(
	'blockstudio/content/orphan_action',
	function ( string $action, string $type ) {
		return 'term' === $type ? 'keep' : $action;
	},
	10,
	2
);

Z njim se osiroteli izraz prikaže kot would-prune-keep namesto kot would-prune-trash.

Predstavnost

Predstavnostne datoteke se nikoli ne kopirajo. content.media določa, kaj se zgodi z določenimi sklici na priloge:

  • "manifest" (privzeto) shrani UID-je prilog in jih navede v content/media/manifest.json skupaj s potjo, vrsto MIME in nadomestnim besedilom. Push zahteva, da vsak sklicani UID priloge obstaja v ciljnem okolju, zato najprej prenesite naložene datoteke z običajnim postopkom za predstavnost.
  • "none" iz datotek izpusti določene sklice na priloge. Janein JSON nato vsebuje samo _acme_role. Ker izpuščen ključ pri pošiljanju ni uporabljen, obstoječa ciljna objava obdrži trenutno sličico.

Zaklepanje entitete

Včasih mora ciljno okolje obdržati svojo različico objave. V meta polje te objave nastavite _blockstudio_content_locked na vrednost, ki pomeni »resnično«, in Push jo preskoči z vrstico locked ter sporočilom »Zaklenjena entiteta je bila preskočena.« Če želite objavo znova vključiti, izbrišite meta polje.

Pravila lastništva

  • Objave, ki jih upravljajo strani na osnovi datotek, so privzeto izključene. Z includePageSyncManaged: true lahko Content Sync sinhronizira njihove nastavljene meta podatke, vendar je Page Sync še vedno odgovoren za njihove post_content. Te projekcije JSON vsebujejo bodyOwner: "page-sync", pri čemer ukaz pull izrecno poroča o preskočeni vsebini. Obstoječe pregledne kopije .html se ohranijo, ukaz push pa jih prezre. Pred pošiljanjem njihovih projekcij metapodatkov najprej sinhronizirajte strani v ciljnem okolju.
  • Avtorji so privzeto prezrti, ker se uporabniki ne sinhronizirajo. Z authors: "login" datoteke objav shranijo prijavno ime avtorja, ukaz push pa ga poišče med obstoječimi uporabniki; če uporabnika ni, pride do napake pri predhodnem preverjanju.
  • pull nikoli ne izbriše datotek. Ko entiteta v podatkovni zbirki ne obstaja več, ukaz pull datoteko označi kot zastarelo in prepusti čiščenje vam.

Kdaj ga ne uporabljati

Content Sync je primeren za izbrano vsebino z malo spremembami: za desetine ali stotine vnosov, pri strukturiranih podatkih, razdeljenih na osredotočene vrste objav, pa tudi za nekaj tisoč. Ni nadomestilo za varnostne kopije ali migracije zbirk podatkov. Naročila, oddaje obrazcev, dnevniki, analitika in obsežna uredniška vsebina sodijo v namenska orodja. Določanje taksonomij, binarne predstavnostne datoteke in ID-ji v oznaki blokov so zunaj njegovega obsega.

Naslednji koraki