设置批量导入 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-v2、apparel-v2、toys-v2、packagedgoods-v1 和 general-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,,,