記事のサマリー（TL;DR）
- Shopifyは、商品バリアントが複数のバーコード値を持てる新機能「barcodes」を発表しました。これまでバリアントは単一のバーコード値しか保持できず、追加の識別子はメタフィールドやタグ、またはShopify外部で管理する必要がありました。
- ProductVariantの新しい
barcodesコネクションで全バーコードを読み取れるほか、productSet、productVariantsBulkCreate、productVariantsBulkUpdateの各mutationにあるbarcodes入力で書き込みができます。各バーコードにはUPC、EAN、ISBN、GTIN、ASINのいずれかの型を指定でき、該当規格の文字数・長さ・プレフィックス・チェックデジットのルールに基づいて検証されます。 - 既存の
ProductVariant.barcodeフィールドは非推奨となりましたが、現時点では動作し続けます。ただし、barcodeのみを参照する連携では2つ目以降のバーコードの存在に気づけない「サイレントな切り捨て」が発生する可能性があるため、注意が必要です。
利用条件・制約
- 1つのバリアントに設定できるバーコードは最大20件、各バーコードは最大255文字までです。
- 最初に送信したバーコードが、既存の
barcodeフィールドが返す値となり、barcodesコネクションでも先頭にソートされます。 - 1つのバリアント入力で
barcodeとbarcodesの両方を同時に設定することはできません。 barcodesを送信すると、バリアントが持つバーコードの全セットが置き換えられます。そのため、保持したいバーコードもすべて含めて送信する必要があります。productsおよびproductVariantsクエリのbarcodeフィルタは、バリアントが持つ任意のバーコードと一致するようになりました。- バーコードに型を指定して送信した場合は、その規格のルールに基づいて検証されます。型を指定しない場合は、送信した値がそのまま保存され、型のないデータもこれまで通り動作します。
詳細
背景
販売者は同一のバリアントに対して、メーカーのUPCとプライベートブランドのEAN、GTIN、再発行されたISBN、マーケットプレイス出品用のASINなど、複数の識別子を割り当てて販売することがよくあります。これまでバリアントは単一のバーコード値しか保持できなかったため、追加の識別子はメタフィールドやタグ、あるいはShopifyの外部で管理されていました。
新機能の内容
ProductVariantの新しいbarcodesコネクションから、バリアントが持つ全バーコードを読み取れるようになりました。書き込みは、productSetmutation、productVariantsBulkCreatemutation、productVariantsBulkUpdatemutationにあるbarcodes入力を通じて行います。
各バーコードには、UPC、EAN、ISBN、GTIN、ASINのいずれかの型を宣言できます。型を宣言した場合、Shopifyはその規格の文字数・長さ・プレフィックス・チェックデジットのルールに照らして値を検証します。型を宣言しない場合は、送信された値がそのまま保存されるため、型のない既存データも従来通り動作します。
利用上の注意点
バリアントが受け付けるバーコードは最大20件で、1件あたり最大255文字です。最初に送信したバーコードが、既存のbarcodeフィールドの返す値となり、barcodesコネクションでも先頭にソートされます。1つのバリアント入力でbarcodeとbarcodesを同時に設定することはできません。barcodesを送信すると、バリアントの既存のバーコードセット全体が置き換えられるため、保持したいバーコードはすべて含めて送信する必要があります。
productsクエリおよびproductVariantsクエリのbarcodeフィルタは、バリアントが持つ任意のバーコードと一致するようになりました。型付きのバーコードを送信した場合はその規格のルールで検証され、型を宣言しない場合は送信値がそのまま保存されます。
既存のProductVariant.barcodeとの互換性
ProductVariant.barcodeは非推奨となりましたが、現時点では機能が壊れることはなく、引き続き動作します。具体的には以下の通りです。
barcodeを読み取ると、barcodesコネクションの先頭のエントリーが返されます。barcodeに書き込むと、barcodesコネクションの先頭のバーコードが更新され、他のバーコードには影響しません。- 空の値を送信すると先頭のバーコードがクリアされ、セット内の次のバーコードに置き換わります。これはバーコードがなくなるまで繰り返されます。
- 1つのバリアント入力で
barcodeとbarcodesを同時に設定することはできません。
コネクションの先頭位置にあるバーコードを追加・変更することで、まだ移行していない利用箇所の制御を保ちながら、複数バーコードの機能を利用できます。
サイレントな切り捨てへの注意
バリアントに2つ目のバーコードが追加されると、barcodeのみを参照する連携では、他のバーコードが存在するという兆候なしに、そのうちの1つだけが見える状態になります。アプリがERP、マーケットプレイス、POS、サプライヤーフィードなどに商品識別子を同期している場合は、読み取り処理をbarcodesコネクションに移行する必要があります。
Shopifyは、今後の投稿でbarcodeフィールドの廃止日を発表するとしており、フィールドが削除される前に完全なAPIバージョン分の通知期間を設けるとしています。
利用を開始するには、ProductVariant、ProductVariantBarcode、BarcodeInput、BarcodeTypeの各リファレンスを参照するよう案内されています。