一括インポートに使用する CSV ファイルのフォーマット

import メソッドでは CSV ファイルを使用して、参照画像を伴う商品セットや商品のリストを同時に作成できます。このページでは、CSV ファイルのフォーマット方法について説明します。

参照画像の作成

参照画像は、商品のさまざまなビューを含む画像です。次の推奨事項が適用されます。

• ファイルの大きさが最大サイズ（20 MB）を超えないようにしてください。
• 商品を論理的に強調して、関連するビジュアル情報が含まれるような視点を考慮してください。
• 欠けている視点を補うような参照画像を作成します。たとえば、右足の靴の画像しかない場合は、その画像ファイルの鏡像バージョンを左足の靴として提供します。
• 解像度の最も高い画像をアップロードします。
• 商品の背景を白にします。
• 背景が透明の PNG は単色の背景に変換します。

画像は、Cloud Storage バケットに保存する必要があります。API キーを使用して画像作成呼び出しを認証する場合は、バケットが公開されている必要があります。サービス アカウントを使用して認証する場合は、そのサービス アカウントにバケットの読み取りアクセス権が必要です。

CSV のフォーマット ガイドライン

import メソッドを使用するには、CSV ファイルとファイル内で参照されている画像の両方を Cloud Storage バケットに保存する必要があります。CSV ファイルには最大で 20,000 行まで入力できます。各行の最大文字数は 2,048 文字です。それ以上の画像をインポートする場合は、複数の CSV ファイルに分割します。

CSV ファイルでは 1 行に 1 つの画像を含め、各行を次の列で構成する必要があります。

1. image-uri: 参照画像の Cloud Storage URI。
2. image-id: 省略可。指定する場合、一意の値にします。指定しない場合、システムによって一意の値が割り当てられます。
3. product-set-id: 画像をインポートする商品セットの、一意の識別子。

4. product-id: 参照画像によって特定する商品のユーザー定義 ID。1 つの product-id を複数の参照画像に関連付けることができます。

   注: 1 つの商品が複数の商品セットに属することもあります。一括インポートに product-id がすでに存在する場合、その行エントリの product-category、product-display、labels は無視されます。

5. product-category: 使用可能な値は homegoods-v2、apparel-v2、toys-v2、packagedgoods-v1、general-v1 *、参照画像によって特定される商品のカテゴリです。作成リクエストで指定されていない場合、システムによって推測されます。使用可能な値のリストは、productCategory リファレンス ドキュメントにも記載されています。

   * 以前の productCategory コード: 以前のカテゴリ（homegoods、apparel、toys）もまだサポート対象ですが、新しい商品には更新された -v2 カテゴリを使用してください。

6. product-display-name: 省略可。商品の名前を指定しない場合、displayName は " " に設定されます。この値は後から更新できます。

7. labels: 省略可。参照画像内の商品を説明する Key-Value ペアの文字列（引用符を併用）。例:

   • "category=shoes"

   • "color=black,style=formal"

     Vision API Product Search では、1 つのキーに複数の値を指定することもできます。例:

   • "category=shoes,category=heels"

   • "color=black,style=formal,style=mens"

8. bounding-poly: 省略可。参照画像内の対象領域を指定します。境界ボックスが指定されていない場合、次のようになります。

   1. 画像の境界ボックスは、Vision API によって推測されます。複数の商品が API によって検出された場合、1 つの画像内の複数の領域がインデックス登録されることがあります。
   2. 行はカンマで終わる必要があります。

   境界ポリゴンが指定されていない商品については、下記の例をご覧ください。

   境界ボックスを指定する場合、boundingPoly 列に偶数個の値をカンマで区切って p1_x,p1_y,p2_x,p2_y,...,pn_x,pn_y の形式で含める必要があります。たとえば、0.1,0.1,0.9,0.1,0.9,0.9,0.1,0.9 のように含めます。

   画像の実際のピクセル値で境界ボックスを定義するには、負でない整数を使用します。したがって、1,000 ピクセル x 1,000 ピクセルの画像を使用する場合、境界ボックスを次のように表現できます。

   gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-123,tan summer bag,apparel-v2,"style=womens,color=tan",100,150,450,150,450,550,100,550
   gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-456,blue summer bag,apparel-v2,"style=womens,color=blue",670,790,980,790,980,920,670,920
   gs://example-reference-images/10002-002/10002-002_B.jpg,img002,sample-set-summer,sample-product-123,apparel-v2,,,
   

   注: Vision API の Object Localizer 機能を使用すると、画像内で一般化されたオブジェクトの境界ボックス座標を取得できます。

   Vision API Product Search では、境界ボックスに正規化された値を使用することもできます。[0, 1] の浮動小数点値を持つ正規化された値を使用して、境界ボックスを定義します。

   正規化された値を使用すると、上記の参照画像の行は次のようになります。

   gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-123,tan summer bag,apparel-v2,"style=womens,color=tan",0.10,0.15,0.45,0.15,0.45,0.55,0.10,0.55
   gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-456,blue summer bag,apparel-v2,"style=womens,color=blue",0.67,0.79,0.98,0.79,0.98,0.92,0.67,0.92
   gs://example-reference-images/10002-002/10002-002_B.jpg,img002,sample-set-summer,sample-product-123,apparel-v2,,,