注意:以下文档只适用于TOP接口,请谨慎使用!

文档中心 > 接入指南

一、文档说明


本文档面向对象为天猫/淘宝(不支持保险、酒店、门票&旅行)商品管理的第三方开发者或者自研发商家。


二、背景介绍


Schema体系是开放平台与天猫/淘宝商品团队共同定义的一套新的开放API规范,用以解决天猫/集市商品管理平台的频繁变动给开发者带来的开发维护成本。天猫/淘宝商品平台通过开放平台API将商品管理涉及的元素及规则使用更接近开发者的语言通过xml的方式返回,开发者解析xml后,根据xml中的规则及元素生成一个商品信息xml,调用开放平台API上传完成商品管理。


基于Schema体系开发商品管理工具时,建议的最优方案是开发者在应用中建立动态映射管理获取的xml与本地DB的数据关系,这样在当天猫/淘宝变化时,获取的xml也会随着变动,这个时候只需要在动态映射管理中设置好xml和本地DB的新映射关系,即可适应变化,从而改变原有天猫/淘宝一变化,开发者需要随着修改代码的状态。


三、开放资源

1. API


Schema体系完成商品管理将使用以下API(图片上传、价格、库存修改使用原有API)

tmall.item.schema.add


2. SDK


使用新体系开发商品管理工具涉及两部分SDK:

a.TOP API SDK——下载方式与旧有方式保持一致。

 

3. 测试账号


目前提供沙箱环境进行测试,所有开发者可以使用沙箱测试账号进行测试,沙箱测试账号:mallb140(密码: tmall1234),测试已尺码库类目请使用类目50008901,常规类目请使用类目162116。


四、支持范围

1. Schema体系覆盖范围


Schema体系能够支持天猫全类目的商品管理,集市接口开放还待评估;

天猫开发者需要关注以下公告:https://open.taobao.com/anno?spm=a219a.7386797.0.0.6927669aWSnRNt&source=search&docId=24931&docType=12


2. Schema体系进行商品管理的注意

1)天猫商品上新


使用Schema体系进行更新不需要判断是否达尔文体系。天猫商品上新的调用基本流程如下:


① 用户判断

由于Schema体系天猫/集市为两套接口,需要使用taobao.user.seller.get判断当前店铺是否属于天猫才能调用天猫Schema接口。


② 授权类目及品牌获取

天猫用户发布的商品类目及品牌需要天猫授权,因此在发布商品前需要先调用taobao.itemcats.authorize.get取得已授权的类目及品牌。

其中发布商品的类目需要叶子类目,因此在获取到类目id后需要再调用taobao.itemcats.get,获取发布商品的叶子类目cid 。


③ 产品检索

天猫所有的商品均挂靠在一个具体产品上,因此卖家上新时需要先查询目前在天猫上是否已上传产品信息,如果无产品则需要上传新产品后等待产品状态可用方可发布新品。

调用tmall.product.match.schema.get接口获取产品匹配的规则,根据规则生成产品匹配xml,调用

tmall.product.schema.match进行产品匹配,如果匹配到产品则调用tmall.product.schema.get查询产品状态,如果返回true则可以直接发布商品,否则需要等待;如果匹配为空,则说明当前需要发布的商品在天猫上还不存在可用产品信息,需要先发布一个新产品。通过调用tmall.product.add.schema.get接口获取产品发布涉及的规则,根据规则生成产品发布xml,调用tmall.product.schema.add发布产品,同样需要调用tmall.product.schema.get查询产品状态,如果返回true则可以直接发布商品,否则需要等待。需要注意的是如果tmall.product.add.schema.get获取为空时,说明该类目为无关键属性类目,直接去发布商品即可。


④ 商品发

当匹配的产品状态为true时,可以进行商品上新。调用tmall.item.add.schema.get获取商品发布的规则,根据规则生成商品上新xml,调用tmall.item.schema.add进行商品上新,涉及图片上传时请使用taobao.picture.upload接口。

当发布商品时,偶尔会遇到报[isv.item-service-error:ITEM_PROPERTIES_ERROR--“xxx”属性出错:类目属性在标准属性中不存在]这一类错误时,一般是由于行业小二对类目属性进行了调整,需要调用tmall.product.update.schema.get接口获取产品更新规则,检查是否有必填元素的value为空,重新生成产品更新信息xml调用tmall.product.schema.update接口完成补充即可。


⑤ 特别提示

开发者如果涉及需要获取某一类目下的商品上新的所有规则,可以同时调用tmall.product.add.schema.get

接口获取产品发布涉及的规则,然后入参需要注意product_id传入0、isv_init传入true调用tmall.item.add.schema.get获取商品发布的通用规则(非全部规则)。


2)天猫商品编辑


① 商品价格编辑

商品和sku的价格建议使用独立的商品价格更新接口tmall.item.price.update进行更新。


② 商品库存同步

商品和sku的库存同步建议使用独立的商品库存同步接口taobao.item.quantity.update/taobao.skus.quantity.update进行更新。


③ 商品标题等信息更新

Schema体系接口支持对部分元素(TITLE(标 题), SUBTITLE(子标题,即卖点),SHORT_TITLE(无线短标题),DESC(PC描述), WAP_DESC(无线描述),FENQIGOU(分期购),VERTICAL_IMAGE( 竖图) ,DRESS_ONLY_FOR_TMALL(天猫独家),SHOP_SAME_STYLE(商场同款 ))进行增量更新,支持增量的参数请以接口返回为准。

开发者调用tmall.item.increment.update.schema.get接口传入具体的商品id和需要更新的字段(这里也是一个xml,如果只修改标题,则xml中update_fields的value就只设置title;如果需要更新多个,则设置多个value)获取该商品更新该字段的规则,根据规则生成增量更新商品xml,调用tmall.item.schema.increment.update完成增量更新。生成更新商品xml时,获取的规则中的所有field都需要将default-value拼装上并回传回来

由于增量更新支持的元素可能会进行扩展,建议用户可以每天调用tmall.item.increment.update.schema.get接口仅入参item_id获取当前商品所属类目支持增量更新的元素。

建议开发者将增量接口支持的每个元素独立封装,这样性能上更优越,报错也会更少。


④ 其他信息更新

除上述信息外的其他商品信息的更新需要使用schema全量更新接口进行更新。调用tmall.item.update.schema.get获取商品全量更新规则,根据规则生成商品更新信息xml后(所有不需要修改的信息需要将default-value统一回传),调用tmall.item.schema.update进行更新。


3)淘宝商品schema上新 (备注,淘宝schema接口已下线,不再维护)

淘宝商品上新的调用基本流程如下:

① 用户判断

由于Schema体系天猫/集市为两套接口,需要使用taobao.user.seller.get判断当前店铺是否属于淘宝才能调用淘Schema接口。


② 商品发布

调用taobao.item.add.schema.get获取商品发布的规则,根据规则生成商品上新xml,调用taobao.item.schema.add进行商品上新,涉及图片上传时请使用taobao.picture.upload接口。


4)淘宝商品更新


① 商品价格编辑

商品和sku的价格建议使用独立的商品价格更新接口taobao.item.price.update进行更新。


② 商品库存同步

商品和sku的库存同步建议使用独立的商品库存同步接口taobao.item.quantity.update/taobao.skus.quantity.update进行更新。


③ 商品标题schema增量信息更新 (备注,淘宝schema接口已下线,不再维护)

Schema体系接口支持对部分元素(标题、热点、描述和无线描述)进行增量更新,支持增量的参数请以接口传入all或者不传获取到的返回为准。

开发者调用taobao.item.increment.update.schema.get接口传入具体的商品id和需要更新的字段(这里也是一个string,比如更新标题,只需要在)获取该商品更新该字段的规则,根据规则生成增量更新商品xml,调用taobao.item.schema.increment.update完成增量更新。生成更新商品xml时,获取的规则中的所有field都需要将default-value拼装上并回传回来

由于增量更新支持的元素可能会进行扩展,建议用户可以每天调用taobao.item.increment.update.schema.get接口仅入参item_id获取当前商品所属类目支持增量更新的元素。

建议开发者将增量接口支持的每个元素独立封装,这样性能上更优越,报错也会更少。需要关注的是增量接口并不保证所有场景下都能增量成功,对于一些运营规则强要求的数据会使增量接口被规则校验住报错。并且对于一些模块化的字段,如无线描述wl_description,整个完整模块统一进行增量校验。


④ 其他信息更新(备注,淘宝schema接口已下线,不再维护)

除上述信息外的其他商品信息的更新需要使用schema全量更新接口进行更新。调用taobao.item.update.schema.get获取商品全量更新规则,根据规则生成商品更新信息xml后(所有不需要修改的信息需要将default-value统一回传),调用taobao.item.schema.update进行更新。

 

五、Schema体系说明


一个商品的Schema结构是由多个field组成的。以下示例为通过商品增量规则获取接口(tmall.item.increment.update.schema.get)获取到规则xml的片段:


<field id="title" name="商品标题" type="input">
    <rules>
      <rule name="valueTypeRule" value="text"/>
      <rule name="requiredRule" value="true"/>
      <rule name="minLengthRule" value="1" exProperty="include"/>
      <rule name="maxLengthRule" value="30" exProperty="include"/>
    </rules>
    <default-value>韩版2014秋冬新款女装高领套头长款纯色毛衣TK4178</default-value>
  </field>


从上述片段可以看到商品的标题规则通过xml上的一个节点输出,可以看到一个schema结构下的field包含了id、name和type三个内容,同时还包含了多个rule及default-value,根据这个片段我们可以了解到的是商品的标题这个信息是一个input类型的字段,值的类型为文本型的、要求必填、字符长度不小于1个字符,并且不超过30个字符,并且现在商品标题为韩都衣舍韩版2014秋冬新款女装高领套头长款纯色毛衣TK4178婏


schema结构完整组成如下:

image.png


开发者需要特别注意的几个类型有:


1. TipRule

   

以价格为例:


<field id="price" name="商品价格" type="input">
    <rules>
      <rule name="valueTypeRule" value="decimal"/>
      <rule name="requiredRule" value="true"/>
      <rule name="tipRule" value="一口价 应在 销售属性表中所填 最高与最低价格 范围区间内。"/>
      <rule name="minValueRule" value="0.00" exProperty="not include"/>
      <rule name="maxValueRule" value="100000000.00" exProperty="not include"/>
      <rule name="383278799_1" value="商品价格必须在销售属性表中所填最高与最低价格范围区间内"/>
      <rule name="tipRule" value="为避免一口价变动引发的违规,请谨慎输入价格。" url="http://rule.tmall.com/tdetail-1168.htm?tag=self"/>
    </rules>
    <default-value>338.00</default-value>
  </field>


TipRule一般用于无法直接描述的复杂规则,isv需要将该规则在页面上透出给用户。


2. DevTipRule


以售后模板为例:


<field id="after_sale_id" name="售后说明模板ID" type="input">
    <rules>
      <rule name="valueTypeRule" value="long"/>
      <rule name="devTipRule" value="请使用taobao.aftersale.get接口获取售后说明模板信息" url="//open.taobao.com/apidoc/api.htm?path=cid:4-apiId:10448"/>
    </rules>


DevTipRule一般用于给开发者提示,不需要展示给用户,开发者可以通过此Rule获取特定的信息,如例子中的如何获取售后模板信息。


3. DisableRule


以开始时间为例:


<field id="item_status" name="商品状态" type="singleCheck">
    <rules>
      <rule name="requiredRule" value="true"/>
    </rules>
    <options>
      <option displayName="出售中" value="0"/>
      <option displayName="定时上架" value="1"/>
      <option displayName="仓库中" value="2"/>
    </options>
    <default-value>0</default-value>
  </field>
  <field id="start_time" name="开始时间" type="input">
    <rules>
      <rule name="valueTypeRule" value="time"/>
      <rule name="disableRule" value="true">
        <depend-group operator="and">
          <depend-express fieldId="item_status" value="1" symbol="!="/>
        </depend-group>
      </rule>
    </rules>
  </field>


DisableRule=true表示该field可忽略,一般与depend-group成组出现,用于描述多个field之间的依赖关系。如例子中的开始时间是依赖于商品状态的值为1(定时上架)时才需要设置值,可以理解为只有fieldId="item_status" 的值不等于1时,disableRuletrue才成立。


4. 有单位的Rule


maxTargetSizeRule和minTargetSizeRule有个unit属性,表示规则的单位。这两个rule的单位主要有kb、mk、gb等,表示文件大小的单位。 

maxLengthRule和minLengthRule也有unit属性,表示长度计量单位,有byte和character两种单位.比如 ”a汉字” 这个字符串,当单位为byte时,长度是5,当单位是character时,长度是3。


六、schema体系使用说明


 以增量更新商品标题为例,当商家进行商品标题编辑时,一般来说可以分成以下几个步骤:

1)获取商品增量更新时所有需要的规则xml;

2)使用Schema SDK读取规则xml,通过readXmlForList拿到一个List<Field>,然后调用readXmlForMap方法读取出一个map,map的key就是FieldId,然后调用sdk中setValue的方法给每一个Field设置Value,完成所有Field的数据组装后,通过writeParamXmlString方法生成商品信息xml;

3)调用schema增量更新接口传入商品信息xml及其他参数完成商品标题的更新。


1. 简单示例


针对商品40905418326增量更新商品标题为例:(JAVA伪代码,仅用于说明调用逻辑)


String sessionKey = “该商品对应卖家的sessionKey”;
    Long itemId = 40905418326L;
    String xmlData = '<?xml version="1.0" encoding="UTF-8"?><itemParam><field id="update_fields" name="更新字段列表" type="multiCheck"><values><value>title</value><value>title</value></values></field></itemParam>';
    TaobaoClient client=new DefaultTaobaoClient(url, appkey, secret);
    TmallItemIncrementUpdateSchemaGetRequest req=new TmallItemIncrementUpdateSchemaGetRequest();
    req.setItemId(itemId);
    req.setXmlData(xmlData);
    TmallItemIncrementUpdateSchemaGetResponse response = client.execute(req , sessionKey);
    String xmlStirng = response.getUpdateItemResult();
    List<Field> fieldList = SchemaReader.readXmlForList(xmlStirng);
        /**
         * 对fieldList进行各种修改操作数据组装
         */
    String addXml = SchemaWriter.writeParamXmlString(fieldList);
    TmallItemSchemaIncrementUpdateRequest addReq = new TmallItemSchemaIncrementUpdateRequest();
    addReq.setItemId(itemId);
    addReq.setXmlData(addXml);
    TmallItemSchemaIncrementUpdateResponse updateRes = client.execute(updateReq , sessionKey);
    Long itemId = Long.parseLong(updateRes.getUpdateItemResult());

 

2. 对fieldList进行操作数据组装的方法


InputField field1 = new InputField();
        field1.setValue("input值");
        
        SingleCheckField field2 = new SingleCheckField();
        field2.setValue("singleCheck值");
        
        MultiInputField field3 = new MultiInputField();
        List<String> values1 = new ArrayList<String>();
        values1.add("multiInput值");
        field3.setValues(values1);
        
        MultiCheckField field4 = new MultiCheckField();
        List<Value> values2 = new ArrayList<Value>();
        values2.add(new Value("multiInput值"));
        field4.setValues(values2);
        
        ComplexField field5 = new ComplexField();
        ComplexValue complexValue = new ComplexValue();
        complexValue.setInputFieldValue("inputId", "input值");
        complexValue.setSingleCheckFieldValue("checkId", new Value("input值"));
        field5.setComplexValue(complexValue);
        
        MultiComplexField field6 = new MultiComplexField();
        List<ComplexValue> values3 = new ArrayList<ComplexValue>();
        ComplexValue complexValue2 = new ComplexValue();
        complexValue2.setInputFieldValue("inputId", "input值");
        complexValue2.setSingleCheckFieldValue("checkId", new Value("input值"));
        values3.add(complexValue2);
        field6.setComplexValues(values3);
        
        LabelField field7 = new LabelField();
        LabelGroup labelGroup = new LabelGroup();
        Label label = new Label();
        label.setDesc("label描述");
        labelGroup.add(label);
        field7.setLabelGroup(labelGroup);


3. 一个完整增量更新标题的商品信息xml  


<xml version="1.0" encoding="utf-8">
    <itemRule>
      <field id="title" name="商品标题" type="input">
        <value>这是一个示例商品而已</value>
      </field>
      <field id="update_fields" name="更新字段列表" type="multiCheck">
        <values>
          <value>title</value>
        </values>
      </field>
    </itemRule>


4.存在父子属性需要使用 <complex-values>


<field id="sell_points" name="商品卖点" type="complex">
<complex-values>
<field id="sell_point_2" type="input">
<value>文艺</value>
</field>
<field id="sell_point_0" type="input">
<value>拼贴</value>
</field>
<field id="sell_point_1" type="input">
<value>棉质</value>
</field>
</complex-values>
</field>


5. 一个复杂规则xml和信息xml


规则xml:   文件下载

入参信息xml:文件下载

 

七、Schema体系对接思路


在schema体系的对接中需要调整以前的思路,需要关注三点:


1. 变更检测


由于业务的变化速度非常快,开发者实现一个变更检测的功能,对于天猫商家来说,每天定期拉取商家对应类目下规则,比较xml差异,根据差异进行业务处理的调整;


2. 动态映射


开发者需要针对每一个商家实现一个动态映射的能力,将本地数据与线上返回的xml结构的元素进行一一映射,改变以前的写死参数的方式,这是接入schema体系最重要的事情。


3. 关注field的type


开发者在实现时,应该考虑的是field的type和rule,关注不同type的field的处理方式和不同规则的前置校验和透出,而业务字段则由动态映射能力去处理。


八、FAQ


Q:使用增量接口更新卖点应该怎么提示更新字段列表不能为空?

A:检查传入的xml中的update_fields中是否传入了通过get接口获取的规则xml中的对应卖点的option,所有value的范围必须根据规则xml中进行获取。


Q:遇到以下类型错误:

    [msg] => Remote service error
   [sub_code] => isv.item-add-service-error:ITEM_PROPERTIES_ERROR
   [sub_msg] => “帐底材质、外帐材质”属性出错:类目属性在标准属性中不存在:帐底材质, 外帐材质。  

A:一般为行业小二对类目的属性进行了调整,不管在商品发布还是在更新的情况下遇到此情况时,如果是天猫商品,调用tmall.product.update.schema.get接口获取产品更新规则后,根据规则更新一下产品,再进行商品更新和商品发布;如果是集市商品,直接获取最新的规则xml后再进行商品更新或者发布。


Q:遇到以下错误:

{"error_response":{"code":15,"msg":"Remote service error","sub_code":"isv.invalid-parameter:cid","sub_msg":"商品类目未授权,请重新选择类目","request_id":"9wy7rnl2x7k7"}}。

A:一般出现于天猫商家,天猫对于商家能够发布的商品类目和品牌有管控,开发者可以通过调用tmall.brandcat.control.get接口去获取当前商家允许发布的类目,控制schema中接口的类目id的入参范围。

  

九、附件下载


top schema sdk : 文件下载



FAQ

关于此文档暂时还没有FAQ
返回
顶部