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

文档中心 > 基础技术

一、文档说明

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

二、 背景介绍

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

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

三、 开放资源

    1. API

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

     //open.taobao.com/doc/api_cat_detail.htm?scope_id=11430&category_id=102

    2. SDK

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

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

 

    3. 测试账号

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

    4. 支持渠道

    开发者在阅读仔细完本文档后,如果有问题请加入钉钉群(21722793)咨询

四、 支持范围

4.1 Schema体系覆盖范围

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

    天猫开发者需要关注以下公告://open.taobao.com/support/announcement_detail.htm?id=24939

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

4.2.1 天猫商品上新

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

    1. 用户判断

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

    2.授权类目及品牌获取

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

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

    3. 产品检索

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

    调用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获取为空时,说明该类目为无关键属性类目,直接去发布商品即可。

    4. 商品发布

    当匹配的产品状态为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接口完成补充即可

    5.特别提示

    开发者如果涉及需要获取某一类目下的商品上新的所有规则,可以同时调用tmall.product.add.schema.get接口获取产品发布涉及的规则,然后入参需要注意product_id传入0、isv_init传入true调用tmall.item.add.schema.get获取商品发布的通用规则(非全部规则)。

4.2.2 天猫商品编辑

    1) 商品价格编辑

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

    2) 商品库存同步

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

    3) 商品标题等信息更新

        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获取当前商品所属类目支持增量更新的元素。

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

    4) 其他信息更新

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

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

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

    1. 用户判断

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

    2. 商品发布

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

4.2.4  淘宝商品更新

    1) 商品价格编辑

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

    2) 商品库存同步

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

    3) 商品标题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,整个完整模块统一进行增量校验。

    4) 其他信息更新(备注,淘宝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结构完整组成如下:

     

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

    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时,disableRule 为true 才成立。

      4. 有单位的Rule

       maxTargetSizeRule和minTargetSizeRule有个unit属性,表示规则的单位。这两个rule的单位主要有kb、mk、gb等,表示文件大小的单位。 
        maxLengthRule和minLengthRule也有unit属性,表示长度计量单位,有byte和character两种单位.比如 ”a汉字” 这个字符串,当单位为byte时,长度是5,当单位是character时,长度是3

六、 schema体系使用说明

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

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

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

  • 调用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
返回
顶部