コンテンツへスキップ

コンテンツ同期

Blockstudioはファイル優先のワークフローを中心に構築されています。ブロック、フィールド、テンプレート、アセット、パターン、ファイルベースのページをすべてプロジェクトに保存できます。Content Syncはこのモデルを、gitに厳選した投稿、ターム、リレーションシップ、宣言済みメタデータも保存したいチーム向けに、選択したWordPressのデータベースコンテンツへと拡張します。

これはWP-CLIワークフローであり、データベースのライブレプリケーションではありません。プル時には、許可リストに登録した投稿、postmeta、ターム、termmeta、投稿とタームの関連付けをテーマ内の移植可能なファイルに変換します。プッシュ時には、安定したUIDを使い、明示的に宣言した参照のみを書き換えて、そのファイルを別の環境に適用します。

注意

コンテンツ同期は必要に応じて実行する機能です。管理画面へのリクエストごとには実行されません。content.enabledがtrueになるまでは、コマンドはスキップ行を返します。

コンテンツ同期を使う場面

バージョン管理、レビュー、環境間の移行が重要なコンテンツセットには、コンテンツ同期を使います。

  • チームメンバー、拠点、導入事例、製品、ドキュメント項目、キャンペーンページなどの構造化コンテンツ
  • それらのコンテンツ群に属するタクソノミーとリレーションシップ
  • コミットしても安全で、安定した参照先が必要な、許可リスト登録済みのメタデータ
  • gitでファイルをレビューしても無理のない、小〜中規模のコンテンツ群

目安として、コンテンツ同期は数十から数百件の行に適しており、データが構造化され、変更頻度が低く、対象の投稿タイプが用途ごとに分かれていれば、数千件程度まで扱えます。本番データベース全体、高頻度で更新される編集コンテンツ、ログ、注文、分析データ、フォーム送信、セッションなど、大量または頻繁に変わるデータのミラーリングには向いていません。生成されたファイルのレビューが煩雑になる、プッシュ内容の把握に時間がかかる、または大半の行がデプロイのワークフロー外で変更される場合は、データベースのバックアップ、移行、インポート/エクスポートツールを使ってください。

メディアのバイナリファイルはコピーされません。添付ファイルの参照はマニフェストに記録して検証できますが、ファイル自体は移行先の環境に存在している必要があります。

設定

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は許可リストです。空の場合、コンテンツ同期は投稿に触れません。taxonomiesは、すでに登録済みで、そのタームと投稿との関連付けを同期するタクソノミーの許可リストです。Blockstudioによってコンテンツ同期ファイルからタクソノミー定義が登録されることはありません。postmetaとtermmetaはmeta.includeで許可リストに登録し、常にmeta.excludeが優先されます。

警告

meta.includeをコミット境界として扱ってください。同期されたファイルはgitに保存するため、秘密情報、トークン、認証情報、個人識別情報(PII)を含むキーは登録しないでください。wp bs content statusは、許可リスト登録済みのメタキーに機密情報が含まれている可能性がある場合、警告行を報告します。

content.idは同期対象エンティティに_blockstudio_content_setとして保存されます。削除処理と所有権チェックはその値を対象とするため、あるコンテンツセットが別のセットのコンテンツを削除することはありません。

Page Syncが管理する投稿はデフォルトで除外されます。includePageSyncManagedが有効な場合、コンテンツ同期は設定済みのメタデータを同期できますが、post_contentの管理権限は引き続きPage Syncにあります。

これらの投影には"bodyOwner": "page-sync"が含まれます。PullはJSONの書き込みをメタデータのみとして報告し、skippedの本文行を追加します。そのため、投稿の本文が空であるかのようには表示されません。隣接する.htmlファイルの書き込みや削除は行いません。既存のレビュー用コピーは保持され、pushでは無視されます。同じ所有権に関するメッセージはdry-runの出力にも含まれます。

別の環境では、まず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にも警告を表示します。コンテンツ同期は.htmlファイル内のIDを書き換えないためです。

書き込みを行わずにプルまたはプッシュの内容を確認するには--dry-runを使います。ファイルに存在しなくなった、コンテンツセットが所有するデータベースエンティティを削除するにはpush --prune --yesを使います。

失敗時の安全性

pushは書き込みや削除の前に、ソース計画全体を解析して検証します。不正なJSON、未解決の宣言済み参照、無効な所有権などの事前検証エラーがあると、破壊的な処理は実行されません。削除対象は、設定済みの投稿タイプ、タクソノミー、content.idに限られます。

pullは、同期済みとして記録する前に、投影した各ファイルを書き込みます。ファイルシステムへの書き込みに失敗した場合はエラー行として返され、そのエンティティの保存済み同期状態は更新されません。

添付ファイルの処理はcontent.mediaに従います。"manifest"の場合、参照されている添付ファイルのUIDが移行先環境に存在する必要があります。"none"の場合、環境固有のIDを残さず、宣言済みの添付ファイル参照を移植可能な出力から意図的に削除します。

ファイル

コンテンツ同期は、設定済みの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、宣言済みtermmeta、メタデータのエンコード方式が保存されます。

.htmlファイルがないもう1つのケースは、上記のbodyOwnerで識別されるPage Sync所有の本文です。本文が空になった通常の投稿では、pullは古い本文ファイルを削除し、その名前を別の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"
  }
}

保存される同期状態は次のとおりです。

メタキー 用途
_blockstudio_content_uid 移植可能なコンテンツ識別子
_blockstudio_content_set content.idに基づくコンテンツセットの名前空間
_blockstudio_content_source テーマからの相対パスで示すソースファイル
_blockstudio_content_fingerprint 最後に同期したファイル/データベースのフィンガープリント
_blockstudio_content_locked 真と評価される値を設定すると、プッシュによるエンティティの上書きを防止

参照

コンテンツ同期は、整数値をIDだと推測しません。参照を書き換えるのはmeta.referencesで設定されている場合だけです。

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

プル時には、指定したパスにあるローカルIDを移植可能なUIDに置き換えます。プッシュ時には、現在のデータベース内のローカルIDにUIDを解決します。

投稿の親、タームの親、投稿とタームの関連付けは、コンテンツ同期が管理する構造上の参照であり、自動的にUIDとして保存されます。設定済みのタクソノミーは、空でも投稿ファイルに記録されます。空の配列を指定してプッシュすると、そのタクソノミーの関連付けがクリアされます。

添付ファイルの参照は検証されますが、インポートはされません。media: "manifest"の場合、参照された添付ファイルはcontent/media/manifest.jsonに一覧表示され、プッシュ時には参照先の添付ファイルUIDがローカルに存在する必要があります。media: "none"の場合、宣言済みの添付ファイル参照は移植可能なファイルから省略されます。省略されたキーはプッシュ時に適用されないため、既存の移行先投稿では現在の添付ファイルメタデータが維持されます。

移植のワークフロー

  1. すべての環境で対象の投稿タイプを登録します。
  2. content.postTypes、meta.include、宣言する参照を設定します。
  3. ソース環境でwp bs content pullを実行します。
  4. 生成されたファイルをコミットします。
  5. 移行先環境でwp bs content pushを実行します。
  6. wp bs content statusを実行して、データベースとファイルが一致することを確認します。

pushではファイルが信頼できる唯一の情報源です。pullでデータベースの内容をファイルに取り込みます。

対象範囲

コンテンツ同期が対応する内容:

  • 許可リストに登録した投稿タイプの投稿
  • 許可リストに登録したpostmeta
  • 許可リストに登録したタクソノミーのターム
  • 許可リストに登録したtermmeta
  • 投稿とタームの関連付け
  • 宣言済みのpost、attachment、term参照
  • 移植可能な投稿UIDとタームUID、およびコンテンツセットの所有権
  • デフォルトでPage Syncの対象を除外
  • 添付ファイルのマニフェストと事前検証
  • pull、push、status、--dry-run、--prune、およびロック済みエンティティの処理

タクソノミー定義の取り込み、メディアのバイナリファイルのコピー、ブロックマークアップ内のIDの書き換えには対応していません。