商品發(fā)布
一、文檔說明
本文檔面向?qū)ο鬄樘熵?淘寶（不支持保險、酒店、門票&旅行）商品管理的第三方開發(fā)者或者自研發(fā)商家；
二、 背景介紹
Schema體系是開放平臺與天貓/淘寶商品團(tuán)隊(duì)共同定義的一套新的開放API規(guī)范，用以解決天貓/集市商品管理平臺的頻繁變動給開發(fā)者帶來的開發(fā)維護(hù)成本。天貓/淘寶商品平臺通過開放平臺API將商品管理涉及的元素及規(guī)則使用更接近開發(fā)者的語言通過xml的方式返回，開發(fā)者解析xml后，根據(jù)xml中的規(guī)則及元素生成一個商品信息xml，調(diào)用開放平臺API上傳完成商品管理。
基于Schema體系開發(fā)商品管理工具時，建議的最優(yōu)方案是開發(fā)者在應(yīng)用中建立動態(tài)映射管理獲取的xml與本地DB的數(shù)據(jù)關(guān)系，這樣在當(dāng)天貓/淘寶變化時，獲取的xml也會隨著變動，這個時候只需要在動態(tài)映射管理中設(shè)置好xml和本地DB的新映射關(guān)系，即可適應(yīng)變化，從而改變原有天貓/淘寶一變化，開發(fā)者需要隨著修改代碼的狀態(tài)。
三、 開放資源
1. API
Schema體系完成商品管理將使用以下API（圖片上傳、價格、庫存修改使用原有API）
//open.taobao.com/doc/api_cat_detail.htm?scope_id=11430&category_id=102
2. SDK
使用新體系開發(fā)商品管理工具涉及兩部分SDK：
a. TOP API SDK——下載方式與舊有方式保持一致。
b. Schema SDK—— 開放平臺將單獨(dú)提供用于解析商品規(guī)則xml和生成商品信息xml的SDK，下載地址為云盤地址http://box.cloud.taobao.com/file/downloadFile.htm?shareLink=qUMsITX
PHP版本SDK感謝歡樂逛的同學(xué)共建。
3. 測試賬號
目前提供沙箱環(huán)境進(jìn)行測試，所有開發(fā)者可以使用沙箱測試賬號進(jìn)行測試，沙箱測試賬號：mallb140（密碼： tmall1234），測試已尺碼庫類目請使用類目50008901，常規(guī)類目請使用類目162116.
4. 支持渠道
開發(fā)者在閱讀仔細(xì)完本文檔后，如果有問題請加入旺旺群（836280177）咨詢
四、 支持范圍
4.1 Schema體系覆蓋范圍
Schema體系能夠支持天貓全類目的商品管理，集市接口全量開放預(yù)計(jì)在6月前；
天貓開發(fā)者需要關(guān)注以下公告：//open.taobao.com/support/announcement_detail.htm?id=24939
4.2 Schema體系進(jìn)行商品管理的注意
4.2.1 天貓商品上新
使用Schema體系進(jìn)行更新不需要判斷是否達(dá)爾文體系。天貓商品上新的調(diào)用基本流程如下：
1. 用戶判斷
由于Schema體系天貓/集市為兩套接口，需要使用taobao.user.seller.get判斷當(dāng)前店鋪是否屬于天貓才能調(diào)用天貓Schema接口。
2. 產(chǎn)品檢索
天貓所有的商品均掛靠在一個具體產(chǎn)品上，因此用戶上新時需要先查詢目前天貓上是否有已有其他商家已經(jīng)上傳產(chǎn)品信息，如果無產(chǎn)品則需要上傳新產(chǎn)品后等待產(chǎn)品狀態(tài)可用方可發(fā)布新品。
調(diào)用tmall.product.match.schema.get接口獲取產(chǎn)品匹配的規(guī)則，根據(jù)規(guī)則生成產(chǎn)品匹配xml，調(diào)用
tmall.product.schema.match進(jìn)行產(chǎn)品匹配，如果匹配到產(chǎn)品則調(diào)用tmall.product.schema.get查詢產(chǎn)品狀態(tài)，如果返回true則可以直接發(fā)布商品，否則需要等待；如果匹配為空，則說明當(dāng)前需要發(fā)布的商品在天貓上還不存在可用產(chǎn)品信息，需要先發(fā)布一個新產(chǎn)品。通過調(diào)用tmall.product.add.schema.get接口獲取產(chǎn)品發(fā)布涉及的規(guī)則，根據(jù)規(guī)則生成產(chǎn)品發(fā)布xml，調(diào)用tmall.product.schema.add發(fā)布產(chǎn)品，同樣需要調(diào)用tmall.product.schema.get查詢產(chǎn)品狀態(tài)，如果返回true則可以直接發(fā)布商品，否則需要等待。需要注意的是如果tmall.product.add.schema.get獲取為空時，說明該類目為無關(guān)鍵屬性類目，直接去發(fā)布商品即可。
3. 商品發(fā)布
當(dāng)匹配的產(chǎn)品狀態(tài)為true時，可以進(jìn)行商品上新。調(diào)用tmall.item.add.schema.get獲取商品發(fā)布的規(guī)則，根據(jù)規(guī)則生成商品上新xml，調(diào)用tmall.item.schema.add進(jìn)行商品上新，涉及圖片上傳時請使用taobao.picture.upload接口。
當(dāng)發(fā)布商品時，偶爾會遇到報(bào)[isv.item-service-error:ITEM_PROPERTIES_ERROR--“xxx”屬性出錯:類目屬性在標(biāo)準(zhǔn)屬性中不存在]這一類錯誤時，一般是由于行業(yè)小二對類目屬性進(jìn)行了調(diào)整，需要調(diào)用tmall.product.update.schema.get接口獲取產(chǎn)品更新規(guī)則，檢查是否有必填元素的value為空，重新生成產(chǎn)品更新信息xml調(diào)用tmall.product.schema.update接口完成補(bǔ)充即可
4.特別提示
開發(fā)者如果涉及需要獲取某一類目下的商品上新的所有規(guī)則，可以同時調(diào)用tmall.product.add.schema.get接口獲取產(chǎn)品發(fā)布涉及的規(guī)則，然后入?yún)⑿枰⒁鈖roduct_id傳入0、isv_init傳入true調(diào)用tmall.item.add.schema.get獲取商品發(fā)布的通用規(guī)則（非全部規(guī)則）。
4.2.2 天貓商品編輯
1） 商品價格編輯
商品和sku的價格建議使用獨(dú)立的商品價格更新接口tmall.item.price.update進(jìn)行更新。
2） 商品庫存同步
商品和sku的庫存同步建議使用獨(dú)立的商品庫存同步接口taobao.item.quantity.update/taobao.skus.quantity.update進(jìn)行更新
3） 商品標(biāo)題等信息更新
Schema體系接口支持對部分元素（TITLE（標(biāo) 題）， SUBTITLE（子標(biāo)題，即賣點(diǎn)），SHORT_TITLE（無線短標(biāo)題），DESC（PC描述）， WAP_DESC（無線描述），F(xiàn)ENQIGOU（分期購），VERTICAL_IMAGE（ 豎圖） ，DRESS_ONLY_FOR_TMALL（天貓獨(dú)家），SHOP_SAME_STYLE（商場同款 ））進(jìn)行增量更新，支持增量的參數(shù)請以接口返回為準(zhǔn)。
開發(fā)者調(diào)用tmall.item.increment.update.schema.get接口傳入具體的商品id和需要更新的字段（這里也是一個xml，如果只修改標(biāo)題，則xml中update_fields的value就只設(shè)置title；如果需要更新多個，則設(shè)置多個value）獲取該商品更新該字段的規(guī)則，根據(jù)規(guī)則生成增量更新商品xml，調(diào)用tmall.item.schema.increment.update完成增量更新。生成更新商品xml時，獲取的規(guī)則中的所有field都需要將default-value拼裝上并回傳回來。
由于增量更新支持的元素可能會進(jìn)行擴(kuò)展，建議用戶可以每天調(diào)用tmall.item.increment.update.schema.get接口僅入?yún)tem_id獲取當(dāng)前商品所屬類目支持增量更新的元素。
建議開發(fā)者將增量接口支持的每個元素獨(dú)立封裝，這樣性能上更優(yōu)越，報(bào)錯也會更少。
4） 其他信息更新
除上述信息外的其他商品信息的更新需要使用schema全量更新接口進(jìn)行更新。調(diào)用tmall.item.update.schema.get獲取商品全量更新規(guī)則，根據(jù)規(guī)則生成商品更新信息xml后（所有不需要修改的信息需要將default-value統(tǒng)一回傳），調(diào)用tmall.item.schema.update進(jìn)行更新。
4.2.3 淘寶商品上新
淘寶商品上新的調(diào)用基本流程如下：
1. 用戶判斷
由于Schema體系天貓/集市為兩套接口，需要使用taobao.user.seller.get判斷當(dāng)前店鋪是否屬于淘寶才能調(diào)用淘Schema接口。
2. 商品發(fā)布
調(diào)用taobao.item.add.schema.get獲取商品發(fā)布的規(guī)則，根據(jù)規(guī)則生成商品上新xml，調(diào)用taobao.item.schema.add進(jìn)行商品上新，涉及圖片上傳時請使用taobao.picture.upload接口。
4.2.4 淘寶商品更新
1） 商品價格編輯
商品和sku的價格建議使用獨(dú)立的商品價格更新接口taobao.item.price.update進(jìn)行更新。
2） 商品庫存同步
商品和sku的庫存同步建議使用獨(dú)立的商品庫存同步接口taobao.item.quantity.update/taobao.skus.quantity.update進(jìn)行更新
3） 商品標(biāo)題等信息更新
Schema體系接口支持對部分元素（標(biāo)題、熱點(diǎn)、描述和無線描述）進(jìn)行增量更新，支持增量的參數(shù)請以接口傳入all或者不傳獲取到的返回為準(zhǔn)。
開發(fā)者調(diào)用taobao.item.increment.update.schema.get接口傳入具體的商品id和需要更新的字段（這里也是一個string，比如更新標(biāo)題，只需要在）獲取該商品更新該字段的規(guī)則，根據(jù)規(guī)則生成增量更新商品xml，調(diào)用taobao.item.schema.increment.update完成增量更新。生成更新商品xml時，獲取的規(guī)則中的所有field都需要將default-value拼裝上并回傳回來。
由于增量更新支持的元素可能會進(jìn)行擴(kuò)展，建議用戶可以每天調(diào)用taobao.item.increment.update.schema.get接口僅入?yún)tem_id獲取當(dāng)前商品所屬類目支持增量更新的元素。
建議開發(fā)者將增量接口支持的每個元素獨(dú)立封裝，這樣性能上更優(yōu)越，報(bào)錯也會更少。需要關(guān)注的是增量接口并不保證所有場景下都能增量成功，對于一些運(yùn)營規(guī)則強(qiáng)要求的數(shù)據(jù)會使增量接口被規(guī)則校驗(yàn)住報(bào)錯。并且對于一些模塊化的字段，如無線描述wl_description，整個完整模塊統(tǒng)一進(jìn)行增量校驗(yàn)。
4） 其他信息更新
除上述信息外的其他商品信息的更新需要使用schema全量更新接口進(jìn)行更新。調(diào)用taobao.item.update.schema.get獲取商品全量更新規(guī)則，根據(jù)規(guī)則生成商品更新信息xml后（所有不需要修改的信息需要將default-value統(tǒng)一回傳），調(diào)用taobao.item.schema.update進(jìn)行更新。
五、Schema體系說明
一個商品的Schema結(jié)構(gòu)是由多個field組成的。以下示例為通過商品增量規(guī)則獲取接口（tmall.item.increment.update.schema.get）獲取到規(guī)則xml的片段：
<field id="title" name="商品標(biāo)題" 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秋冬新款女裝高領(lǐng)套頭長款純色毛衣TK4178</default-value> </field>
從上述片段可以看到商品的標(biāo)題規(guī)則通過xml上的一個節(jié)點(diǎn)輸出，可以看到一個schema結(jié)構(gòu)下的field包含了id、name和type三個內(nèi)容，同時還包含了多個rule及default-value，根據(jù)這個片段我們可以了解到的是商品的標(biāo)題這個信息是一個input類型的字段，值的類型為文本型的、要求必填、字符長度不小于1個字符，并且不超過30個字符，并且現(xiàn)在商品標(biāo)題為韓都衣舍韓版2014秋冬新款女裝高領(lǐng)套頭長款純色毛衣TK4178婏。
schema結(jié)構(gòu)完整組成如下：
開發(fā)者需要特別注意的幾個類型有：
1. TipRule
以價格為例：
<field id="price" name="商品價格" type="input"> <rules> <rule name="valueTypeRule" value="decimal"/> <rule name="requiredRule" value="true"/> <rule name="tipRule" value="一口價 應(yīng)在 銷售屬性表中所填 最高與最低價格 范圍區(qū)間內(nèi)。"/> <rule name="minValueRule" value="0.00" exProperty="not include"/> <rule name="maxValueRule" value="100000000.00" exProperty="not include"/> <rule name="383278799_1" value="商品價格必須在銷售屬性表中所填最高與最低價格范圍區(qū)間內(nèi)"/> <rule name="tipRule" value="為避免一口價變動引發(fā)的違規(guī)，請謹(jǐn)慎輸入價格。" url="http://rule.tmall.com/tdetail-1168.htm?tag=self"/> </rules> <default-value>338.00</default-value> </field>
TipRule一般用于無法直接描述的復(fù)雜規(guī)則，isv需要將該規(guī)則在頁面上透出給用戶
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一般用于給開發(fā)者提示，不需要展示給用戶，開發(fā)者可以通過此Rule獲取特定的信息，如例子中的如何獲取售后模板信息。
3.DisableRule
以開始時間為例：
<field id="item_status" name="商品狀態(tài)" 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成組出現(xiàn)，用于描述多個field之間的依賴關(guān)系。如例子中的開始時間是依賴于商品狀態(tài)的值為1（定時上架）時才需要設(shè)置值，可以理解為只有fieldId="item_status" 的值不等于1時，disableRule 為true 才成立。
4. 有單位的Rule
六、 schema體系使用說明
以增量更新商品標(biāo)題為例，當(dāng)商家進(jìn)行商品標(biāo)題編輯時，一般來說可以分成以下幾個步驟：
獲取商品增量更新時所有需要的規(guī)則xml
使用Schema SDK讀取規(guī)則xml，通過readXmlForList拿到一個List<Field>，然后調(diào)用readXmlForMap方法讀取出一個map，map的key就是FieldId，然后調(diào)用sdk中setValue的方法給每一個Field設(shè)置Value,完成所有Field的數(shù)據(jù)組裝后，通過writeParamXmlString方法生成商品信息xml
調(diào)用schema增量更新接口傳入商品信息xml及其他參數(shù)完成商品標(biāo)題的更新
1. 簡單示例
針對商品40905418326增量更新商品標(biāo)題為例：（JAVA偽代碼，僅用于說明調(diào)用邏輯）
String sessionKey = “該商品對應(yīng)賣家的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進(jìn)行各種修改操作數(shù)據(jù)組裝 */ 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進(jìn)行操作數(shù)據(jù)組裝的方法
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. 一個完整增量更新標(biāo)題的商品信息xml
<?xml version="1.0" encoding="utf-8"?> <itemRule> <field id="title" name="商品標(biāo)題" type="input"> <value>這是一個示例商品而已</value> </field> <field id="update_fields" name="更新字段列表" type="multiCheck"> <values> <value>title</value> </values> </field> </itemRule>
4. 一個復(fù)雜規(guī)則xml和信息xml
規(guī)則xml:http://yunpan.taobao.com/s/1IcqnB2UBuF
入?yún)⑿畔ml：http://yunpan.taobao.com/s/8cdLFtDxi2
七、Schema體系對接思路
在schema體系的對接中需要調(diào)整以前的思路，需要關(guān)注三點(diǎn)：
1. 變更檢測
由于業(yè)務(wù)的變化速度非常快，開發(fā)者實(shí)現(xiàn)一個變更檢測的功能，對于天貓商家來說，每天定期拉取商家對應(yīng)類目下規(guī)則，比較xml差異，根據(jù)差異進(jìn)行業(yè)務(wù)處理的調(diào)整；
2. 動態(tài)映射
開發(fā)者需要針對每一個商家實(shí)現(xiàn)一個動態(tài)映射的能力，將本地?cái)?shù)據(jù)與線上返回的xml結(jié)構(gòu)的元素進(jìn)行一一映射，改變以前的寫死參數(shù)的方式，這是接入schema體系最重要的事情
3. 關(guān)注field的type
開發(fā)者在實(shí)現(xiàn)時，應(yīng)該考慮的是field的type和rule，關(guān)注不同type的field的處理方式和不同規(guī)則的前置校驗(yàn)和透出，而業(yè)務(wù)字段則由動態(tài)映射能力去處理
八、FAQ
Q:使用增量接口更新賣點(diǎn)應(yīng)該怎么提示更新字段列表不能為空
A:檢查傳入的xml中的update_fields中是否傳入了通過get接口獲取的規(guī)則xml中的對應(yīng)賣點(diǎn)的option，所有value的范圍必須根據(jù)規(guī)則xml中進(jìn)行獲取
Q: 遇到以下類型錯誤：
[msg] => Remote service error
[sub_code] => isv.item-add-service-error:ITEM_PROPERTIES_ERROR
[sub_msg] => “帳底材質(zhì)、外帳材質(zhì)”屬性出錯:類目屬性在標(biāo)準(zhǔn)屬性中不存在:帳底材質(zhì), 外帳材質(zhì)
A:一般為行業(yè)小二對類目的屬性進(jìn)行了調(diào)整，不管在商品發(fā)布還是在更新的情況下遇到此情況時，如果是天貓商品，調(diào)用tmall.product.update.schema.get接口獲取產(chǎn)品更新規(guī)則后，根據(jù)規(guī)則更新一下產(chǎn)品，再進(jìn)行商品更新和商品發(fā)布；如果是集市商品，直接獲取最新的規(guī)則xml后再進(jìn)行商品更新或者發(fā)布。
Q:遇到以下錯誤：
{"error_response":{"code":15,"msg":"Remote service error","sub_code":"isv.invalid-parameter:cid","sub_msg":"商品類目未授權(quán)，請重新選擇類目","request_id":"9wy7rnl2x7k7"}}
A:一般出現(xiàn)于天貓商家，天貓對于商家能夠發(fā)布的商品類目和品牌有管控，開發(fā)者可以通過調(diào)用tmall.brandcat.control.get接口去獲取當(dāng)前商家允許發(fā)布的類目，控制schema中接口的類目id的入?yún)⒎秶?/span>
FAQ
- 關(guān)于此文檔暫時還沒有FAQ