商品發布
一、文件說明
本文檔物件導向為天貓/淘寶（不支援保險、飯店、門票&旅行）商品管理的第三方開發者或自研發商家；
二、背景介紹
##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
. SDK
使用新系統開發商品管理工具涉及兩部分SDK：
a. TOP API SDK－下載方式與舊有方式保持一致。
b. Schema SDK－ 開放平台將單獨提供用於解析商品規則xml和產生商品資訊xml的SDK，下載位址為雲端磁碟位址#http ://box.cloud.taobao.com/file/downloadFile.htm?shareLink=qUMsITX
PHP版本SDK感謝歡樂逛的同學共建。
3. 測試帳號
目前提供沙箱環境進行測試，所有開發者可使用沙箱測試帳號進行測試，沙箱測試帳號：mallb140（密碼： tmall1234），測試已尺寸庫類別目請使用類別目50008901，常規類別目請使用類別162116.
##4. 支援管道
開發者在閱讀仔細本文檔後，若有問題請加入旺旺群（836280177）諮詢
#四、 支援範圍
4.1 Schema體系涵蓋範圍
Schema系統能夠支援天貓全類目的商品管理，集市介面全量開放預計在6月前；
天貓開發者需要關注以下公告：//open.taobao.com/support/announcement_detail.htm? id=24939
4.2 Schema系統進行商品管理的注意
4.2.1 天貓商品上新
使用Schema系統進行更新不需要判斷是否達爾文系統。天貓商品上新的召喚基本流程如下：
1. 使用者判斷
由於Schema體系天貓/市集為兩組接口，需要使用taobao.user.seller.get判斷目前店舖是否屬於天貓才能呼叫天貓Schema接口。
2. 產品檢索
天貓所有的商品掛在一個特定產品上，因此使用者上新時需要先查詢目前天貓上是否有已有其他商家已經上傳產品訊息，如果無產品則需要上傳新產品後等待產品狀態可用者可發布新品。
呼叫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取得為空時，說明該類別目為無關鍵屬性類別目，直接去發布商品即可。
3. 商品發布
當配對的產品狀態為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介面完成補充即可
4.特別提示
開發者如果涉及需要取得某一類別目下的商品上新的所有規則，可以同時呼叫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） 商品標題等資訊更新
# Sch## 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 淘寶商品上新
# 淘寶商品上新的召喚基本流程如下：
# 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） 商品標題等資訊更新
# Sch## 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全量更新介面進行更新。呼叫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
六、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. 一個複雜規則 xml與資訊xml
規則xml:http://yunpan.taobao.com/s/1IcqnB2UBuF
## 入參資訊xml： http://yunpan.taobao.com/s/8cdLFtDxi2
七、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
底材質、外帳材質」屬性出錯:類目屬性在標準屬性中不存在:帳底材質, 外帳材質
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的入參範圍。
FAQ
- 關於此文件暫時還沒有FAQ
