设置批量导入 CSV 的格式

通过 CSV 文件,您可以使用 import 方法同时创建带有参考图片的商品集和商品。本页面介绍如何设置 CSV 文件的格式。

创建参考图片

参考图片是包含商品各种视图的图片。请采用下列建议:

  • 确保文件大小不超过上限 (20MB)。
  • 考虑逻辑上突出显示商品并包含相关视觉信息的视角。
  • 创建可以补充缺失视角的参考图片。例如,如果您只有一些右脚鞋子的图片,请提供这些文件的镜像版本作为左角鞋子。
  • 上传分辨率最高的可用图片。
  • 以白色为背景显示商品。
  • 将具有透明背景的 PNG 格式图片转换为纯色背景。

图片必须存储在 Cloud Storage 存储分区中。如果您使用 API 密钥对图片创建调用进行身份验证,则该存储分区必须是公开的。如果您使用服务账号进行身份验证,则该服务账号必须对此存储分区具有读取权限。

CSV 格式设置准则

若要使用 import 方法,CSV 文件及其指向的图片都必须位于 Cloud Storage 存储分区中。CSV 文件最大行数限制为 20,000;每行最多包含 2,048 个字符。要导入更多图片,请将其拆分为多个 CSV 文件。

CSV 文件中的每行都必须包含一张图片,并且 CSV 文件必须包含以下列:

  1. image-uri:参考图片的 Cloud Storage URI。
  2. image-id可选。如果您要提供,请确保提供一个唯一值。否则,系统会分配一个唯一值。
  3. product-set-id:要向其中导入图片的商品集的唯一标识符。
  4. product-id:由参考图片标识的商品的 ID(由用户定义)。一个 product-id 可与多张参考图片相关联。

  5. product-category:允许的值为 homegoods-v2apparel-v2toys-v2packagedgoods-v1general-v1*;参考图片标识的商品所属的类别。如果未在创建请求中指定,则系统会进行推断。productCategory 参考文档中也列出了允许的值。

  6. product-display-name可选。如果您未对此商品提供名称,displayName 会设为“.”。之后您可以更新该值。

  7. labels可选。它是用于描述参考图片中的商品的键值对字符串(带引号)。例如:

    • "category=shoes"
    • "color=black,style=formal"

      借助 Vision API Product Search 您还可为单个键提供多个值。例如:

    • "category=shoes,category=heels"

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

  8. bounding-poly可选。用于指定参考图片中需要关注的区域。如果指定边界框:

    1. Vision API 会推断出图片的边界框;如果 API 检测到多个商品,则可能会将单张图片中的多个区域编入索引。
    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

    要使用图片的实际像素值定义边界框,请使用非负整数。因此,您可以通过以下方式来表示 1000 像素 × 1000 像素图片中的边界框:

    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 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,,,