Синхронизация контента
Blockstudio построен вокруг файлового рабочего процесса: блоки, поля, шаблоны, ресурсы, паттерны и страницы на основе файлов могут находиться в вашем проекте. Синхронизация контента расширяет эту модель на выбранный контент базы данных WordPress для команд, которым также нужно хранить отобранные записи, таксономии, связи и объявленные метаданные в git.
Это синхронизация WP-CLI, а не репликация базы данных в реальном времени. При получении данные из разрешенных списком записей, метаданных записей и терминов, а также связей между терминами и записями преобразуются в переносимые файлы в вашей теме. При отправке эти файлы применяются в другом окружении с использованием постоянных UID; переписываются только явно объявленные ссылки.
Примечание
Синхронизация контента выполняется по запросу. Она не запускается при каждом запросе администратора. Пока
content.enabledнеtrue, команды возвращают строку о пропуске.
Когда использовать синхронизацию контента
Используйте синхронизацию контента для наборов данных, которые важно версионировать, проверять и переносить между окружениями:
- структурированный контент: например, сведения о команде, местоположения, истории проектов, товары, документационные записи или страницы кампаний
- таксономии и связи, относящиеся к этим наборам данных
- разрешенные списком метаданные, которые безопасно добавлять в репозиторий и которым нужны постоянные ссылки
- небольшие и средние наборы данных, для которых проверка файлов в git остается практичной
Как правило, синхронизация контента подходит для десятков или сотен строк и может работать с несколькими тысячами, если данные структурированы, меняются редко и разделены по сфокусированным типам записей. Она не предназначена для зеркального копирования всей рабочей базы данных, редакционного контента с большим трафиком, журналов, заказов, аналитики, отправленных форм, сеансов и других больших или часто меняющихся данных. Если созданные файлы трудно проверять, отправки сложно анализировать или большинство строк меняется вне рабочего процесса развертывания, используйте резервную копию базы данных, инструмент миграции или импорта/экспорта.
Бинарные файлы медиафайлов не копируются. Ссылки на вложения можно записать в манифест и проверить, но сами файлы должны существовать в целевом окружении.
Настройка
Включите синхронизацию контента в 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 — список разрешенных типов записей. Если он пуст, синхронизация контента не затрагивает записи. taxonomies — список уже зарегистрированных таксономий, термины и связи записей для которых нужно синхронизировать. Blockstudio не регистрирует определения таксономий из файлов синхронизации контента. Метаданные записей и терминов разрешаются через список meta.include; meta.exclude всегда имеет приоритет.
Предупреждение
Считайте
meta.includeграницей фиксации изменений. Синхронизированные файлы должны находиться в git, поэтому не добавляйте ключи с секретами, токенами, учетными данными или персональными данными.wp bs content statusсообщает о предупреждении, если разрешенный ключ метаданных выглядит чувствительным.
content.id сохраняется в синхронизированных сущностях как _blockstudio_content_set. Проверки очистки и принадлежности ограничены этим значением, поэтому один набор данных не может удалить содержимое другого.
По умолчанию управляемые публикации синхронизации страниц исключены. Если включен includePageSyncManaged, синхронизация контента может синхронизировать заданные для них метаданные, но их post_content по-прежнему контролирует синхронизация страниц.
Эти проекции содержат "bodyOwner": "page-sync". Pull помечает запись JSON как содержащую только метаданные и добавляет строку тела skipped, вместо того чтобы отображать запись как имеющую пустое тело. При этом соседний файл .html не создаётся и не удаляется. Существующая копия для проверки сохраняется и игнорируется при push. Те же сообщения о владении включаются в вывод пробного запуска.
В другой среде сначала запустите Page Sync. Проекция с bodyOwner: "page-sync" должна ссылаться на существующую запись, управляемую Page Sync; команда push откажется создавать пустую подменную запись или применять копию тела на проверке. Проекции без этого маркера из старых версий по-прежнему поддерживаются.
По умолчанию авторы игнорируются, поскольку пользователи не синхронизируются. Установите authors: "login", чтобы сохранять имя пользователя автора в файлах записей и при отправке сопоставлять его с существующим пользователем. Если пользователя нет, проверка перед выполнением завершится ошибкой; синхронизация контента не создает пользователей.
Команды
wp bs content pull [--post-type=<type>] [--taxonomy=<taxonomy>] [--dry-run]
wp bs content push [--dry-run] [--prune] [--yes]
wp bs content status
pull переносит контент из базы данных в файлы. Команда присваивает _blockstudio_content_uid записям, входящим в область синхронизации и еще не имеющим его, и сообщает об устаревших файлах, для которых больше нет исходной записи в базе данных. Устаревшие файлы при получении не удаляются.
push применяет файлы к текущей базе данных. Перед записью команда проверяет план и блокирует выполнение, если есть неразрешенные объявленные ссылки, конфликты слагов, заблокированные сущности или отсутствующие типы записей.
status сравнивает файлы с базой данных и сообщает о состоянии каждой сущности: unchanged, would-update, missing-db, conflict, locked или orphaned. Также команда предупреждает о разрешенных ключах метаданных, похожих на секреты, до их фиксации, и о числовых ID в телах разметки блоков, поскольку синхронизация контента не переписывает ID в файлах .html.
Используйте --dry-run, чтобы проверить получение или отправку без записи изменений. Используйте push --prune --yes, чтобы удалить из базы данных сущности, принадлежащие набору данных и отсутствующие в файлах.
Защита от сбоев
push разбирает и проверяет весь исходный план до записи или
очистки. Некорректный JSON, неразрешенные объявленные ссылки, неверная принадлежность и
другие ошибки предварительной проверки блокируют деструктивную фазу. Очистка ограничена
настроенными типами записей, таксономиями и content.id.
pull записывает каждый преобразованный файл перед тем, как отметить соответствующую сущность как синхронизированную. Ошибка записи в файловую систему возвращается как строка ошибки и не обновляет сохраненное состояние синхронизации этой сущности.
Обработка вложений выполняется согласно content.media. При использовании "manifest" UID вложений, на которые есть ссылки, должны существовать в целевой среде. При использовании "none" объявленные ссылки на вложения намеренно удаляются из переносимого результата, а не сохраняют специфичные для среды идентификаторы.
Файлы
Content Sync записывает файлы в настроенный content.path:
content/
posts/
team_member/
jane.9b1c0e6e.json
jane.9b1c0e6e.html
terms/
category/
leadership.5e900000.json
media/
manifest.json
Файлы .json записей содержат идентификатор, поля записи, связи с терминами, объявленные метаданные и кодировку метаданных. В соседнем файле .html хранится post_content в виде исходной разметки блоков; файл не создается, если содержимое пусто. Файлы .json терминов содержат идентификатор, таксономию, слаг, название, описание, UID родительского элемента, объявленные метаданные термина и кодировку метаданных.
Другой случай, когда файл .html отсутствует, — тело, принадлежащее Page Sync, указанное выше как bodyOwner. Для обычных записей, у которых тело становится пустым, команда pull удаляет старый файл тела и указывает его в отдельной строке тела 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"
}
}
Сохраненное состояние синхронизации:
| Ключ метаданных | Назначение |
|---|---|
_blockstudio_content_uid |
Переносимый идентификатор содержимого |
_blockstudio_content_set |
Пространство имен набора содержимого из content.id |
_blockstudio_content_source |
Путь к исходному файлу относительно темы |
_blockstudio_content_fingerprint |
Отпечаток последней синхронизации файла/базы данных |
_blockstudio_content_locked |
Истинное значение предотвращает перезапись сущности при отправке |
Ссылки
Content Sync не предполагает, что целое число является идентификатором. Ссылки переписываются только в случаях, настроенных в meta.references.
{
"meta": {
"references": {
"_related_posts": { "kind": "post", "path": "*" },
"_topic": { "kind": "term" },
"_hero": { "kind": "attachment", "path": "image.id" }
}
}
}
При получении локальные идентификаторы в этих путях преобразуются в переносимые UID. При отправке UID преобразуются обратно в локальные идентификаторы в текущей базе данных.
Родительские записи, родительские термины и связи записи с терминами — это структурные ссылки, которыми управляет Content Sync; они автоматически сохраняются как UID. Настроенные таксономии записываются в файлы записей, даже если они пусты; пустой массив удаляет связи с этой таксономией при отправке.
Ссылки на вложения проверяются, но вложения не импортируются. При использовании media: "manifest" ссылки на вложения перечисляются в content/media/manifest.json; при отправке требуется, чтобы UID указанного вложения существовал локально. При использовании media: "none" объявленные ссылки на вложения исключаются из переносимых файлов. Поскольку пропущенный ключ не применяется при отправке, существующая запись в целевой среде сохраняет текущие метаданные вложения.
Процесс переноса
- Зарегистрируйте тип записи в каждой среде.
- Настройте
content.postTypes,meta.includeи все объявленные ссылки. - Запустите
wp bs content pullв исходной среде. - Зафиксируйте созданные файлы.
- Запустите
wp bs content pushв целевой среде. - Запустите
wp bs content status, чтобы проверить соответствие базы данных файлам.
Файлы являются источником истины для push. База данных сохраняется обратно в файлы с помощью pull.
Область поддержки
Content Sync поддерживает:
- записи из разрешенных типов записей
- разрешенные метаданные записей
- термины из разрешенных зарегистрированных таксономий
- разрешенные метаданные терминов
- связи записей с терминами
- объявленные ссылки
post,attachmentиterm - переносимые UID записей и терминов, а также принадлежность к набору содержимого
- исключение Page Sync по умолчанию
- манифест вложений и предварительную проверку
pull,push,status,--dry-run,--pruneи обработку заблокированных сущностей
Сбор определений таксономий, копирование бинарных данных медиафайлов и переписывание идентификаторов в разметке блоков не поддерживаются.