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