Schema体系是开放平台与天猫/淘宝商品团队共同定义的一套新的开放API规范,用以解决天猫/淘宝商品管理平台的频繁变动给开发者带来的开发维护成本。天猫/淘宝商品平台通过开放平台API将商品管理涉及的元素及规则使用更接近开发者的语言通过xml的方式返回,开发者解析xml后,根据xml中的规则及元素生成一个商品信息xml,调用开放平台API上传完成商品管理。
使用Schema接口必须先理解schema体系的结构。一个完整的schemaxml会由若干个field组成,每一个field都是用来描述规则和元素。schema结构针对field定义了以下组成部分。
段名称
说明
id
用于描述唯一主键,以商品的标题为例,id=“title”。
name
用于描述field的显示名,以商品的标题为例,name=“商品标题”。
type
用于描述field的值的数据输入类型,schema结构对于field定义了七种类型,分别为input、multiInput、singleCheck、multiCheck、complex、multiComplex和label。详见3.1说明。
values
用于描述multiInput和multiCheck类型的field的value的集合。
complex-value
用于描述complex类型的field的多数据值的集合。
complex-values
用于描述multiComplex类型的field的多数据值的集合。
value
用于描述field的值,上一层级一般为values或者complex-values。
option
用于描述field的值的可选值,与html中select元素中的option标签类似。(1)displayName,用于描述可选值的展示名。(2)value,用于描述可选值主键。
label-group
用于描述label的聚合,label主要用于描述说明信息。
rule
用于描述field的各类系统或者业务规则。详见3.2说明。
depend-group
用于描述依赖关系的集合。
operator
用于描述集合中多个依赖关系的关系,包括‘and’(与关系)和’or’(或关系)。
depend-express
用于描述依赖关系,上层为depend-group,与Rule中的disableRule是成组出现的。一般可以理解为当满足依赖关系时,disableRule为true才成立depend-express中会包含fieldId、value和symbol。目前支持的symbol见3.3说明。
type用于描述field的值的数据输入类型,schema结构对于field定义了七种类型,分别为input、multiInput、singleCheck、multiCheck、complex、multiComplex和label。
类型
类型说明
input
当前field的值为文本输入
multiInput
当前field的值为多行文本输入型
singleCheck
当前field的值为单选输入型,类似于radio
multiCheck
当前field的值为多选输入型,类似于checkbox
complex
当前field的值为复合结构,表示数据的聚合
multiComplex
当前field的值为复合结构,与complex有差别的在于multiComplex的field是可以有多份数据实例样本
rule用于描述field的各类系统或者业务规则。
rule类型
valueTypeRule
用于描述field值需要满足数据类型,包括了text(文本型)/decimal(小数型)/integer(整数型)/date(日期型)/long(长整数型)/url(超链接)/textarea(多行文本)/html(支持html标记语法的文本)
requiredRule
是否必填,默认为false,true/false
disableRule
是否忽略此field,为true时,将不对rule进行check,同时他的value也将无效。默认为false,值范围包含true/false
maxLengthRule
最大长度
minLengthRule
最小长度
maxValueRule
最大值(数值类型时有效)
minValueRule
最小值(数值类型时有效)
maxInputNumRule
最多可选数(多选时有效)
minInputNumRule
至少要选数(多选时有效)
maxTargetSizeRule
最大目标文件大小
minTargetSizeRule
最小目标文件大小
readOnlyRule
只读,用户无法修改返回值,值范围为true/false
regxRule
正则表达式匹配
tipRule
Field中展示的tip信息,用于一些无法直接用语法描述或者过于复杂的规则,或者提示信息,需要给用户透出。
maxImageSizeRule
最大图片大小,指的是分辨率,如800*800
minImageSizeRule
最小图片大小
devTipRule
一般用于给开发者提示,不需要展示给用户,开发者可以通过此Rule获取特定的信息,如例子中的如何获取售后模板信息
symbol
isnull
fieldId指向的字段的值为空
==
fieldId指向的字段的值等于value
!=
fieldId指向的字段的值不等于value
>
fieldId指向的字段的值大于value
<
fieldId指向的字段的值小于value
>=
fieldId指向的字段的值大于等于value
<=
fieldId指向的字段的值小于等于value
contains
fieldId指向的字段的值中包含有value
notcontains
fieldId指向的字段的值中不包含有value
thisfield’svalueinfieldOptions
fieldId指向的字段的值中在fieldId对应的value列表中
thisfield’svaluenotinfieldOptions
fieldId指向的字段的值中不在fieldId对应的value列表中
multiComple
√
TipRule一般用于无法直接描述的复杂规则,isv需要将该规则在页面上透出给用户。以价格为例。
DevTipRule一般用于给开发者提示,不需要展示给用户,开发者可以通过此Rule获取特定的信息,如例子中的如何获取售后模板信息。以售后模板为例。
在区间rule里面,都有一个exProperty属性,表示开闭区。当exProperty=include时,为闭区间,大小比较时,包含rule的value指定的值;当exProperty=notinclude时,为开区间,大小比较时,不包含rule的value指定的值。
例如:
maxValueRule中value=2且exProperty=include时,表示返回值必须小于等于2;
maxValueRule中value=2且exProperty=notinclude时,表示返回值必须小于2。
maxTargetSizeRule和minTargetSizeRule有个unit属性,表示规则的单位。这两个rule的单位主要有kb、mk、gb等,表示文件大小的单位。maxLengthRule和minLengthRule也有unit属性,表示长度计量单位,有byte和character两种单位。
例如:“a汉字”这个字符串,当单位为byte时,长度是5,当单位是character时,长度是3。
由于业务的变化速度非常快,开发者实现一个变更检测的功能,对于天猫商家来说,每天定期拉取商家对应类目下规则,比较xml差异,根据差异进行业务处理的调整。
开发者需要针对每一个商家实现一个动态映射的能力,将本地数据与线上返回的xml结构的元素进行一一映射,改变以前的写死参数的方式,这是接入schema体系最重要的事情。
增量更新的字段有限,按需提交filed的value(s)即可,新版中不需要update_fields字段。
涉及接口:
说明:天猫商品需要挂靠产品,所以产品发布仅支持天猫店铺;淘宝和特价版商品无需挂靠产品,不需要产品发布,直接按照“步骤三”发布商品即可。
类目:女装/女士精品>>POLO衫(类目id:201241307)为例说明产品发布步骤;
涉及API:tmall.product.match.schema.get;
入参:category_id=201241307;
出参:规则xml;
如果没有返回产品匹配规则,说明该类目不需要发布产品,直接到"步骤三:发布商品"。
涉及API:tmall.product.schema.match;
入参:category_id=201241307;propvalues=xml_data(示例XML如下);
出参:产品id;product_id=1459669507;
调用tmall.product.schema.get查询产品状态【
产品状态(true)如果返回true则可以直接发布商品(直接到"步骤三:发布商品"。);
产品状态(false)如果返回false则需要等待。
注意:如果上一步(产品匹配)没有匹配到产品,需要自己添加。
涉及API:tmall.product.add.schema.get;
入参:category_id=201241307;brand_id=10000497;
出参:规则xml。
涉及API:tmall.product.schema.add;
入参:category_id=201241307;brand_id=10000497;xml_data;
出参:产品idproduct_id;
注意:部分产品发布后需要审核通过后才可使用,所以需要等待产品状态可用后再发布商品。
备注:
1)如果获取产品规则tmall.product.add.schema.get获取为空时,说明该类目为无关键属性类目,直接去发布商品即可。
2)产品schema接口继续使用老的schemaSDK协议;
新老schema协议差异
1)
字段
老协议
新协议
是否变动
ComplexField
是
MultiComplexField
否
2)所有field的default-complex-values/default-values/default-complex-value/default-value都已取消,统一用field的值取代。
当第二步的产品可用后,即可发布商品
1)商品规则获取调用alibaba.item.publish.schema.get获取类目和属性规则
2)商品级联属性信息获取调用alibaba.item.publish.props.get,当alibaba.item.publish.schema.get接口返回的某些属性的值特别多时,会提示使用此接口。根据入参获取商品级联属性信息(基本很少用到),比如alibaba.item.publish.schema.get返回如下结果是:
3)商品发布alibaba.item.publish.submit进行商品上新(注意涉及图片上传时请使用taobao.picture.upload接口)。
①当发布天猫商品时,偶尔会遇到报[isv.item-service-error:ITEM_PROPERTIES_ERROR–“xxx”属性出错:类目属性在标准属性中不存在]这一类错误时,一般是由于行业小二对类目属性进行了调整,(需要去第二步编辑产品)需要调用。②tmall.product.update.schema.get接口获取产品更新规则,检查是否有必填元素的value为空,重新生成产品更新信息xml调用tmall.product.schema.update接口完成补充即可。
alibaba.item.publish.schema.get
alibaba.item.publish.props.get
alibaba.item.publish.submit
TIPS:开发者如果涉及需要获取某一类目下的商品上新的所有规则,可以同时调用tmall.product.add.schema.get接口获取产品发布涉及的规则,然后入参需要注意spu_id传入0调用alibaba.item.publish.schema.get获取商品发布的通用规则(非全部规则)
涉及接口
更新分类
1)全量更新(除局部更新外的均需要走全量更新);
2)局部更新(局部更新API)。
涉及API:alibaba.item.edit.schema.get;
说明:全量和增量编辑的规则都使用接口alibaba.item.edit.schema.get获取;
增量编辑规则获取还需入参fields,比如传入fields=title,接口alibaba.item.edit.schema.get只获取title的编辑规则。
涉及API:alibaba.item.edit.submit;
涉及API:alibaba.item.edit.fastupdate;
说明:
catId,bizIdentity,id,price,quantity,title,wirelessDesc,desc,barcode,outerId,video,images,recommendReason,imageVideo,sellPromise,taobaoFoodPrdLicense,taobaoFoodDesignCode,taobaoFoodFactoryName,taobaoFoodFactorySite,taobaoFoodFactoryContact,taobaoFoodPrdLicense,taobaoFoodDesignCode,taobaoFoodFactoryName,taobaoFoodFactorySite,taobaoFoodFactoryContact,taobaoFoodMix,taobaoFoodPlanStorage,taobaoFoodPeriod,taobaoFoodAdditive,taobaoFoodSupplier,taobaoFoodProduceDate,taobaoFoodStockDate,sku,descRepublicOfSell,shopcat;
i)sku信息支持修改已有sku的图片、价格、数量、商家编码、条形码,但不能新增(删除)sku;
ii)新增sku要用全量接口。
title(标题)
subtitle(子标题,即卖点)
show_title(展示标题)
short_title(无线短标题)
description(商品描述)
wireless_desc(旺铺无线详情描述)
vertical_image(竖图)
white_bg_image(白底图)
large_screen_image(电子大屏图)
shop_category(店铺类目)
item_image(主图)
item_wireless_images(无线主图)
image_video_type(主图视频比例类型)
main_video(主图视频)
three_to_four_item_images(3:4商品图片)
备注:关于主图视频,目前商品已经支持3:4主图视频,并且支持3:4商品主图图片更新,建议三个字段为一个组件来使用;
1)如果image_video_type选择1:1或者16:9类型,那么main_video需要传值1:1或者16:9类型的视频,此时three_to_four_item_images这个字段,不管你传值与否,都不会生效。
2)如果image_video_type选择3:4类型,那么main_video需要传值3:4类型视频,且需要同时传three_to_four_item_images这个字段。
title(宝贝标题)
catProp(类目属性)支持修改枚举类型字段,不支持修改input类型的字段;
sku(宝贝销售规格)支持修改已有sku的价格、库存、商家编码等信息,但不能新增sku;新增sku要用全量接口alibaba.item.edit.submit,并且先设置销售属性;
price(特价)需与marketPrice同时修改;
marketPrice(划线价)需与price同时修改;
quantity(总数量)
outerId(商家编码)
images(宝贝图片)
clearImage(非牛皮癣图)
imageVideo(主图视频)
verticalImage(宝贝长图)
desc(商品描述)
subStock(库存计数)
tbDeliveryTime(发货时效)
tbExtractWay(运费)
invoice(提供发票)
warranty(保修服务)
sellPromise(退换货承诺)
sevenDaySupport、sevenDayOptional(七天退货)
TIPS:建议开发者将增量接口支持的每个元素独立封装,这样性能上更优越,报错也会更少。