1 バリエーション ＝ 1 バーコードだった制約が外れ、UPC / EAN / ISBN / GTIN / ASIN を型付きで最大 20 件まで保持できるようになった。従来の barcode フィールドは動き続けるが deprecated。読み取りだけを続けると「他のバーコードの存在に気づけない」状態になる。
2 つ目以降の識別子はメタフィールド／タグ／外部システムに退避。どこに何が入っているかがストアごとに属人化していた。
ProductVariant.barcodes connection で読み、barcodes input で書く。タイプを宣言すれば規格ルールで検証される。
productSet ／ productVariantsBulkCreate ／ productVariantsBulkUpdate の 3 つ。いずれも barcodes input を受け付ける。products と productVariants クエリの barcode フィルタは、バリエーションが持つ いずれかの バーコードにマッチするようになった。先頭だけしか引っかからない、ということはない。各バーコードは type を宣言できる。宣言した場合、その規格の 文字種・桁数・プレフィックス・チェックディジット のルールに従って検証される。
文字種・長さ・プレフィックス・チェックディジットのルールに合致しない値はエラー。データ品質を API レイヤで担保できる。
タイプを宣言しなければ、送信された値がそのまま格納される。型なしの既存データは今まで通り動くので、一括で型付けし直す必要はない。
| ルール | 内容 | 実装上の意味 |
|---|---|---|
| 件数上限 | 20 件 / バリエーション | 21 件目を入れたいケースは設計を見直す（別バリエーション or メタフィールド） |
| 文字数上限 | 255 文字 / 1 バーコード | 実運用の識別子には十分。連結値を詰め込む用途ではない |
| 並び順 | 最初に送った値が connection の先頭にソートされる | 「主識別子」を先頭に置く設計が可能 |
| 書き込み挙動 | 全置換 barcodes 送信はセット全体を置き換える |
残したいバーコードも必ず含めて送る。差分パッチではない |
| 排他制約 | 不可 1 つの variant input で barcode と barcodes の両方は設定できない |
移行期のコードで「両方セット」を書くと落ちる。どちらか一方に寄せる |
| 検索フィルタ | products / productVariants の barcode フィルタは任意の 1 件にマッチ |
サブ識別子で検索してもヒットする |
barcodes: [新しい値] を送ると、既存のバーコードは全部消える。必ず 読み取り → マージ → 全件送信 の順で実装すること。ProductVariant.barcode は非推奨になったが、今日時点で壊れるものは何もない。挙動は「常に connection の先頭を指す」と覚えれば足りる。
barcode を読むと、barcodes connection の先頭のエントリが返る。
barcode への書き込みは 先頭の 1 件だけを更新し、他のバーコードには触れない。
空値を送ると先頭がクリアされ、セット内の次のバーコードが繰り上がる。以降、残りが無くなるまで同じ挙動。
barcode だけを読むインテグレーションは「そのうちの 1 件」しか見えず、他が存在するというシグナルすら受け取れない。barcodes connection に移すこと。
コード内の barcode 読み取りを全部拾う。特に外部システムへ書き出している経路を優先。
connection で全件取得し、必要なら type で絞り込む。先頭 1 件でよい箇所も明示的に先頭を取る形に。
barcodes は全置換なので「読む → マージ → 全件送る」に。barcode との併用は不可なので片方に統一。
barcodes を送るとバリエーションのセット全体が置き換わる。残したいものを含めて送るのが必須。既存アプリの update 系コードをそのまま流用すると全消しになる。
1 つの variant input で両方を設定することはできない。移行途中で「安全のため両方書く」実装は成立しないので、経路ごとにどちらを使うか決め切る。
UPC / EAN / ISBN / GTIN / ASIN を宣言すると、文字種・長さ・プレフィックス・チェックディジットが検証される。型を付けた瞬間、今まで通っていた汚いデータが弾かれる可能性がある点に注意。
レガシー画面や未移行の連携先が見るのは常に先頭。先頭に何を置くかがそのまま互換性の設計になる。移行順に合わせて主識別子を先頭に固定しておくと事故が減る。
サイレント切り捨ては例外も警告も出さない。ERP / マーケットプレイス / POS / サプライヤーフィードへ識別子を同期しているアプリは、明日壊れなくても「静かに間違ったデータを流し続ける」状態になり得る。廃止日は未定（将来告知＋API バージョン 1 つ分の予告）だが、移行の緊急度は廃止日ではなくデータ整合性で決まる。
productVariantsBulkUpdate の barcodes input で 1 バリエーションに集約。規格が分かるものは type を宣言して検証を通す。barcode フィルタで全件横断できる。棚卸し過程で不正な値も洗い出せる。barcode 1 件だけを読んで外部へ同期している。マーチャント側が 2 件目のバーコードを登録した瞬間から、外部システムには不完全な識別子が流れ続ける（警告は出ない）。barcode 参照を洗い出し、barcodes connection 読みに置換。移行前の暫定対応として「バーコードが 2 件以上あるバリエーション」を抽出してレポート化する。productVariants を舐めて barcodes の件数を見る。廃止日は未定だが、影響は廃止前から発生する点が要注意。type（UPC / EAN / ISBN / GTIN / ASIN）を宣言して書き込み、Shopify 側の検証を通す。規格が特定できない値は type 未宣言のまま送り、現状維持で保存する。barcode は非推奨だが今日は壊れない。ただし 2 件目が登録された瞬間から、barcode しか読まない連携は静かに識別子を取りこぼす。barcodes へ移すのが先。」