Pular para o conteúdo

Sincronização de conteúdo

Blockstudio é estruturado em torno de um fluxo de trabalho de arquivos primeiro: blocos, campos, modelos, recursos, padrões e páginas baseadas em arquivos podem ficar no seu projeto. A Sincronização de conteúdo estende esse modelo a conteúdos selecionados do banco de dados WordPress para equipes que também querem posts, termos, relacionamentos e metadados declarados selecionados em git.

É um fluxo de trabalho WP-CLI, não uma replicação ativa do banco de dados. Ao baixar, a Sincronização de conteúdo projeta posts, postmeta, termos, termmeta e relacionamentos entre posts e termos permitidos em arquivos portáteis no seu tema. Ao enviar, aplica esses arquivos a outro ambiente, usando UIDs estáveis e reescrevendo apenas as referências que você declarar explicitamente.

Observação

A Sincronização de conteúdo é executada sob demanda. Ela não é executada em todas as solicitações de administração. Os comandos retornam uma linha ignorada até que content.enabled seja true.

Quando usar a Sincronização de conteúdo

Use a Sincronização de conteúdo para conjuntos de conteúdo importantes para versionar, revisar e mover entre ambientes:

  • conteúdo estruturado, como membros da equipe, locais, estudos de caso, produtos, entradas de documentação ou páginas de campanhas
  • taxonomias e relacionamentos associados a esses conjuntos de conteúdo
  • metadados permitidos, seguros para confirmar no repositório e que precisam de referências estáveis
  • conjuntos de conteúdo pequenos ou médios, nos quais ainda seja prático revisar arquivos em git

Como regra geral, a Sincronização de conteúdo funciona bem com dezenas ou centenas de linhas e pode chegar à casa dos milhares quando os dados são estruturados, mudam pouco e estão divididos em tipos de post específicos. Ela não foi feita para espelhar um banco de dados de produção inteiro, conteúdo editorial de alto tráfego, registros, pedidos, análises, envios de formulários, sessões ou outros dados de grande volume ou que mudam com frequência. Se os arquivos gerados forem difíceis de revisar, se levar muito tempo para avaliar os envios ou se a maioria das linhas mudar fora do seu fluxo de implantação, use uma ferramenta de backup, migração ou importação/exportação de banco de dados.

Os arquivos binários de mídia não são copiados. As referências a anexos podem ser registradas em um manifesto e validadas, mas os próprios arquivos precisam existir no ambiente de destino.

Configuração

Ative a Sincronização de conteúdo em 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 é uma lista de permissões. Se estiver vazia, a Sincronização de conteúdo não altera posts. taxonomies é uma lista de permissões de taxonomias já registradas cujos termos e relacionamentos com posts devem ser sincronizados. Blockstudio não registra definições de taxonomia a partir dos arquivos da Sincronização de conteúdo. postmeta e termmeta são autorizados por meta.include; meta.exclude sempre prevalece.

Aviso

Trate meta.include como um limite do que será confirmado no repositório. Os arquivos sincronizados devem ficar em git, portanto não inclua chaves que contenham segredos, tokens, credenciais ou dados pessoais identificáveis. wp bs content status informa linhas de aviso quando uma chave de metadados permitida parece conter dados sensíveis.

content.id é armazenado nas entidades sincronizadas como _blockstudio_content_set. A poda e as verificações de propriedade são limitadas a esse valor, para que um conjunto de conteúdo não possa excluir o conteúdo de outro conjunto.

Posts gerenciados pela Sincronização de páginas são excluídos por padrão. Se includePageSyncManaged estiver ativado, a Sincronização de conteúdo poderá sincronizar os metadados configurados desses posts, mas a Sincronização de páginas continuará sendo responsável pelo post_content deles.

Essas projeções contêm "bodyOwner": "page-sync". Pull informa a gravação de JSON como contendo apenas metadados e adiciona uma linha de corpo skipped, em vez de apresentar a publicação como se tivesse o corpo vazio. Não grava nem exclui um arquivo .html correspondente. Uma cópia de revisão existente é preservada e ignorada pelo push. As mesmas mensagens de propriedade são incluídas na saída da simulação.

Em outro ambiente, execute primeiro o Page Sync. Uma projeção com bodyOwner: "page-sync" deve referenciar uma publicação existente gerenciada pelo Page Sync; o push se recusa a criar um substituto vazio ou aplicar a cópia de revisão daquele conteúdo. As projeções sem o marcador, de versões anteriores, continuam sendo compatíveis.

Os autores são ignorados por padrão porque os usuários não são sincronizados. Defina authors: "login" para armazenar o login do autor nos arquivos de post e associar esse login a um usuário existente ao enviar. A ausência do usuário é um erro de pré-verificação; a Sincronização de conteúdo não cria usuários.

Comandos

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 captura o conteúdo do banco de dados em arquivos. Ele atribui _blockstudio_content_uid aos posts no escopo que ainda não tenham um e informa sobre arquivos obsoletos cuja origem no banco de dados já não existe. Arquivos obsoletos não são excluídos ao baixar.

push aplica arquivos ao banco de dados atual. Ele valida o plano antes de gravar e bloqueia referências declaradas não resolvidas, conflitos de slug, entidades bloqueadas e tipos de post ausentes.

status compara os arquivos com o banco de dados e informa o estado de cada entidade como unchanged, would-update, missing-db, conflict, locked ou orphaned. Também avisa sobre chaves de metadados permitidas que parecem conter segredos antes que esses valores sejam confirmados no repositório e sobre IDs numéricos em corpos de marcação de blocos, pois a Sincronização de conteúdo não reescreve IDs em arquivos .html.

Use --dry-run para inspecionar uma operação de baixar ou enviar sem gravar. Use push --prune --yes para remover entidades do banco de dados pertencentes ao conjunto de conteúdo que já não existem nos arquivos.

Segurança em caso de falha

push analisa e valida o plano de origem completo antes de gravar ou remover itens. JSON malformados, referências declaradas não resolvidas, propriedade inválida e outras falhas de pré-verificação bloqueiam a fase destrutiva. A remoção continua limitada aos tipos de post, taxonomias e content.id configurados.

pull grava cada arquivo projetado antes de registrar a entidade como sincronizada. Uma falha ao gravar no sistema de arquivos é retornada como uma linha de erro e não atualiza o estado de sincronização armazenado para essa entidade.

O tratamento de anexos segue content.media. Com "manifest", os UIDs dos anexos referenciados precisam existir no ambiente de destino. Com "none", as referências de anexos declaradas são removidas intencionalmente da saída portátil, em vez de preservar IDs específicos do ambiente.

Arquivos

O Content Sync grava arquivos em content.path configurado:

Código
content/
  posts/
    team_member/
      jane.9b1c0e6e.json
      jane.9b1c0e6e.html
  terms/
    category/
      leadership.5e900000.json
  media/
    manifest.json

Os arquivos .json de post armazenam identidade, campos do post, relações com termos, metadados declarados e codificação de metadados. O arquivo irmão .html armazena post_content como marcação bruta de blocos e é omitido quando o conteúdo está vazio. Os arquivos .json de termos armazenam identidade, taxonomia, slug, nome, descrição, UID do termo pai, metadados do termo declarados e codificação de metadados.

O outro caso sem arquivo .html é um conteúdo gerenciado pelo Page Sync, identificado acima por bodyOwner. Para publicações comuns cujo conteúdo fica vazio, o pull remove o arquivo de conteúdo antigo e o identifica em uma linha separada de conteúdo 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"
  }
}

O estado de sincronização armazenado é:

Chave de metadados Finalidade
_blockstudio_content_uid Identidade de conteúdo portátil
_blockstudio_content_set Namespace do conjunto de conteúdo de content.id
_blockstudio_content_source Caminho do arquivo de origem relativo ao tema
_blockstudio_content_fingerprint Última impressão digital sincronizada do arquivo/banco de dados
_blockstudio_content_locked Um valor verdadeiro impede que o envio sobrescreva a entidade

Referências

O Content Sync nunca presume que um número inteiro seja um ID. As referências só são reescritas quando configuradas em meta.references.

JSON
{
  "meta": {
    "references": {
      "_related_posts": { "kind": "post", "path": "*" },
      "_topic": { "kind": "term" },
      "_hero": { "kind": "attachment", "path": "image.id" }
    }
  }
}

Na importação, os IDs locais nesses caminhos se tornam UIDs portáteis. No envio, os UIDs são convertidos de volta em IDs locais no banco de dados atual.

Os posts pais, os termos pais e as relações entre posts e termos são referências estruturais gerenciadas pelo Content Sync e são armazenadas automaticamente como UIDs. As taxonomias configuradas são gravadas nos arquivos dos posts mesmo quando estão vazias; um array vazio limpa as relações dessa taxonomia no envio.

As referências de anexos são validadas, não importadas. Com media: "manifest", os anexos referenciados são listados em content/media/manifest.json; o envio exige que o UID do anexo referenciado exista localmente. Com media: "none", as referências de anexos declaradas são omitidas dos arquivos portáteis. Como uma chave omitida não é aplicada durante o envio, um post de destino existente mantém os metadados de anexo atuais.

Fluxo de trabalho de portabilidade

  1. Registre o tipo de post de destino em cada ambiente.
  2. Configure content.postTypes, meta.include e todas as referências declaradas.
  3. Execute wp bs content pull no ambiente de origem.
  4. Faça commit dos arquivos gerados.
  5. Execute wp bs content push no ambiente de destino.
  6. Execute wp bs content status para verificar se o banco de dados corresponde aos arquivos.

Os arquivos são a fonte da verdade para push. O banco de dados é capturado de volta em arquivos com pull.

Escopo

O Content Sync oferece suporte a:

  • posts de tipos de post permitidos
  • metadados de post permitidos
  • termos de taxonomias registradas permitidas
  • metadados de termo permitidos
  • relações entre posts e termos
  • referências declaradas post, attachment e term
  • UIDs portáteis de posts e termos e propriedade do conjunto de conteúdo
  • exclusão do Page Sync por padrão
  • manifesto de anexos e validação prévia
  • tratamento de pull, push, status, --dry-run, --prune e de entidades bloqueadas

A captura de definições de taxonomia, a cópia de arquivos binários de mídia e a reescrita de IDs na marcação de blocos não são compatíveis.