eBay CBT Translation API参考文档_新更新

eBay CBT Translation API参考文档

发布时间：2018-01-24 最近刷新时间：2018-11-07

eBay CBT Translation API接口（以下简称“本接口”）旨在为eBay卖家提供刊登翻译服务。本接口利用eBay 内部研发的机器学习 (Machine Learning) 及eBay 平台的优化技术实现对卖家在各大eBay网站上已有的英文刊登（以下简称“原刊登”）进行多语言翻译。本接口目前仅支持德文、法文、意大利文和西班牙文的翻译。对接本接口并对原刊登进行翻译后，用户必须通过本接口的调用向我们报告在eBay网站上新的刊登（以下简称“新刊登”）的item ID，否则将无法继续使用本接口。

现阶段，本接口仅开放给部分用户。如需申请使用，请发电邮到DL-eBay-CBT-API@ebay.com。

服务使用条款

1. 本接口免费使用，因此目前阶段仅开放给部分用户使用。eBay有权对于本接口的调用次数 (call) 和字数 (character) 进行部分限制。以一个月为周期，eBay有权对用户开放的范围及接口调用次数 (call) 和字数 (character) 的限制进行调整。

2. 本接口的翻译功能基于机器翻译，仅供用户参考，不构成明示或暗示的对用户操作的建议。eBay对于新刊登翻译的质量和准确性并没有作出明示或隐含的保证或担保。由于原刊登可能会进行修改，eBay不保证新刊登与原刊登内容的一致性。

3. 本接口用户需要在对元刊登进行翻译后，利用接口的指定调用报告新刊登的 item ID。对于不报告新刊登的item ID的用户，eBay有权单方面不继续向其开放本接口使用。

目前主要有4个调用，调用如下：

接口名称	简介	详细
TranslateListing	该调用根据用户输入的刊登编号、翻译原语言、目标语言和需要翻译的内容范围对刊登进行翻译。用户通过权限认证之后，系统会首先检查用户的call limit和character limit 限制，如果call limit或者character limit超过限制则不会继续处理。Call limit 和character limit 限制以月计算。	阅读
GetCurrentUsage	通过该调用可以查询当前账号的 call limit 和 character limit 以及两者的使用情况。	阅读
GetTranslationData	该调用回输出目前CBT Translation API所支持的语言、翻译的内容范围(scopes)以及一些有关的数据。	阅读
RecordTranslatedListing	通过该调用卖家可以把翻译后的内容所创建的新刊登的 item ID 回传到 Translation 服务。	阅读
GetCategorySuggestion	通过该调用可以查询刊登在新站点建议使用的类别 (Category ID)。	阅读

用户调用该服务的方式为需要使用OAuth2+Token的方式，下面是相关介绍。

请参照错误编码 (Error Code) 参考查看错误信息。

API 接口域名

生产环境
https://cbttranslation.ebay.com.hk
沙箱环境
https://sandbox.cbttranslation.ebay.com.hk

API认证和授权

● HTTP请求头

所有发送到 eBay REST 服务的请求都需要提供 Authorization 请求头以获取验证信息。 Authorization 请求头的格式为：Bearer + 空格 + Token。Content-Type请填写 application/x-www-form-urlencoded。具体详情请参考：HTTP request headers

● OAuth2请求域和Token

与eBay 新的Buy API 和 Sell API一样， CBT Translation API也是使用 OAuth2 Authentication 的。请注意，这和 Trading API 的 Token 是不兼容的，Trading API 的 Token 不能用于访问新的API。关于如何获取新的OAuth2 Token，请参考：Getting Access Tokens。

另一个需要注意的是：新的 Token 中授权了用户可以访问的范围，这个范围 eBay 称之为 scope (域)，用户只能访问 token 中指定 scope 的资源，否则会返回错误。参数 scope 在申请授权码的时候指定，用户登录授权之后，应用根据授权码拿到新的Token，此时这些 scopes 就隐藏在 Token 之中了。

https://signin.sandbox.ebay.com/authorize?

client_id=<client_id>&
redirect_uri=<your_redirect_uri>&
response_type=code&
state=<client-supplied-value>&
scope=https://api.ebay.com/oauth/api_scope/sell.inventory.readonly

访问 CBT Translation 服务，需要用户的 Token 至少包含这个域：
https://api.ebay.com/oauth/api_scope/sell.inventory.readonly

API服务调用

TranslateListing

本调用根据用户输入的刊登编号、翻译原语言、目标语言和需要翻译的内容范围对刊登进行翻译。翻译后，请把利用已翻译内容所创建的新刊登的 item ID 回传到 CBT Translation 服务。

资源路径

POST /translation/v1/translate_listing

请求格式

{
"itemId","string",
"source","string",
"target","string",
"scope","string",

"textlist": {

"key": "value",

...

}

请求参数

服务接受参数

参数名称	参数类型	参数是否必需	解释
itemId	String	必需	例如：130009977174
source	String	可选	默认为en
target	String	必需	例如：de-DE，目前只支持 de-DE, es-ES, fr-FR, it-IT 四种语言。
scope	String	必需	可以选 title, vari, spec 和 desc (或 text)。可输入多个 scope，以逗号分开。desc 和 text 不可同时使用。
textlist	Map	可选	当scope包含text 时适用。以 Map 的形式提交，Key和 value 的配对，不可包含超过20对key和value，所有value的字段必须在原刊登内容里出现。Key 可自定义，返回的翻译值会对应相同的key。 “textlist” : { "title_text": "Sample product title in English", "textblock01": "Compatible with that model of product", "textblock02": "Shipping policy paragraph", "copyrights_text": "All rights reserved 2018" }

运行逻辑

1.   校验call limit。用户通过权限认证之后，系统会首先检查用户的 call limit 和 character limi 限制，如果 call limit 或者 character limit 任意一个值超过限额则不会继续处理。Call limit 和character limit 限制以月计算。
2.   检查该刊登是否属于该用户。只有当前用户的刊登才允许被翻译。
3.   系统会根据对应的scope 翻译该刊登。
4.   返回内容数据。

输出

如果查询成功，将返对应刊登对应 scope 的翻译内容。

响应字段描述

输出字段	类型	出现频率	含义
ackValue	string	经常	SUCCESS 或 FAILURE
errorMessage	object	根据结果	如果发生异常或请求错误，就可能看到 errorMessage 字段。 "errorMessage": { "error": [ { "errorId": 300001, "domain": "translation", "category": "Application", "message": "Missing required parameter: itemId", "longMessage": "The required parameter item ID (itemId) is missing. The request cannot be fulfilled.", "actionToTake": "CORRECTINPUTDATA" } ] }
warningMessage	object	根据结果	如果发生异常，就可能看到 warningMessage 字段。 "warningMessage": { "error": [ { "errorId": 200001, "domain": "translation", "category": "REQUEST", "message": "The translated title is over the character limit of item title", "longMessage": "The translated title is over the 80-character limit of item title. You may not be able to create a listing with the translated title." } ] }
timestamp	string	经常	响应的服务器时间为 GMT 时间，格式为：YYYY-MM-DD HH:MM:SS
data	object	根据结果	请求成功，并且有数据，这个字段是个对象。否则返回 null。
statusCode	int	经常	请求响应码
extension	list	经常	补充字段

响应内容中字段解释

Key	Description
content	title	对应 scope 里的 title 翻译之后的内容
	vari	对应 scope 里的 vari 翻译之后的内容，所有的 variation 以 Map 的形式返回，variName 为 variation 的原名称，variNameTranslated 为 variation 的翻译后名称，variValue 为 variation 对应的原来值，variValueTranslated 为 variation 对应的翻译后值。 vari 响应格式: "vari": [{ "variName": "color", "variNameTranslated": "Farbe", "variValues": [{ "variValue": "red", "variValueTranslated": "XXX" }, { "variValue": "blue", "variValueTranslated": "XXX" } ] }]
	spec	对应 scope 里的 spec 翻译之后的内容，所有的 item specifics 以 Map 的形式返回，specName 为 item specifics的原名称，specNameTranslated 为 item specifics的翻译后名称，specValue 为 item specifics 对应的原来值，specValueTranslated 为 item specifics 对应的翻译后值。 spec 响应格式: "spec": [{ "specName": "XXX", "specNameTranslated": "XXX", "specValues": [{ "specValue": "XXX", "specValueTranslated": "XXX" }, { "specValue": "XXX", "specTranslated": "XXX" } ] }]
	desc	对应 scope 里的 desc 翻译之后的内容
	text	对应 scope 里的 text 翻译之后的内容， textlist 以 Map 的形式返回，返回的key和value中，key会和请求参数的key相同。 text 响应格式: “textlist”: { "title_text": "Título del producto de muestra en inglés", "textblock01": "Compatible con ese modelo de producto", "textblock02": "Póliza de envío", "copyrights_text": "Todos los derechos reservados 2018" }
itemId	刊登编号
tranlationId	翻译标识

errorMessage 字段解释

Key	Description
errorId	错误编号
domain	服务名称，值为 translation (翻译服务)
category	错误类别，值为 System (系统类别错误) Application (应用类别错误) Request (请求类别错误)
message	错误信息
longMessage	错误详细信息
actionToTake	纠正方式，值为 ConsultTechSupport (联系技术支持寻求帮助) CorrectInputData (修改请求参数) Retry (重试请求)

warningMessage 字段解释

Key	Description
warningId	警告编号
domain	服务名称，值为 translation (翻译服务)
category	警告类别，值为 System (系统类别警告) Application (应用类别警告) Request (请求类别警告)
message	警告信息
longMessage	警告详细信息

响应举例

{
    "ackValue": "SUCCESS",
    "data": {
        "content": {
            "desc": "Hola",
            "spec": "{\"spec\":[{\"specName\":\"Brand\",\"specNameTranslated\":\"Marca de fábrica\",\"specValues\":[{\"specValue\":\"Unbranded/Generic\",\"specValueTranslated\":\"Sin marca/genéricos\"}]},{\"specName\":\"Compatible Brand\",\"specNameTranslated\":\"Marca de fábrica compatible\",\"specValues\":[{\"specValue\":\"For Apple\",\"specValueTranslated\":\"Para Apple\"}]},{\"specName\":\"Country/Region of Manufacture\",\"specNameTranslated\":\"País de fabricación\",\"specValues\":[{\"specValue\":\"China\",\"specValueTranslated\":\"China\"}]},{\"specName\":\"Material\",\"specNameTranslated\":\"material\",\"specValues\":[{\"specValue\":\"Silicone/Gel/Rubber\",\"specValueTranslated\":\"Caucho de silicona de Gel\"}]},{\"specName\":\"MPN\",\"specNameTranslated\":\"MPN\",\"specValues\":[{\"specValue\":\"Does Not Apply\",\"specValueTranslated\":\"No se aplica\"}]},{\"specName\":\"UPC\",\"specNameTranslated\":\"UPC\",\"specValues\":[{\"specValue\":\"Does not apply\",\"specValueTranslated\":\"No se aplica\"}]}]}",
            "title": "Hallo",

  "vari": "{\"vari\":[{\"variName\":\"Color\",\"variNameTranslated\":\"Color\",\"variValues\":[{\"variValue\":\"lucency\",\"variValueTranslated\":\"lucencia\"},{\"variValue\":\"laser\",\"variValueTranslated\":\"Láser\"}]},{\"variName\":\"model\",\"variNameTranslated\":\"Modelo\",\"variValues\":[{\"variValue\":\"For iPhone 6S plus\",\"variValueTranslated\":\"Para iPhone 6S plus\"},{\"variValue\":\"For iPhone 6\",\"variValueTranslated\":\"Para el iPhone 6\"},{\"variValue\":\"For iPhone 6S\",\"variValueTranslated\":\"Para iPhone 6S\"},{\"variValue\":\"For iPhone 6 plus\",\"variValueTranslated\":\"Para el iPhone 6 plus\"}]}]}"
        },
        "itemId": 9500638888,
        "status": true,
        "tranlationId": 5100000001
    },
    "extension": [],
    "statusCode": 200,
    "timeStamp": 2018-01-01 00:01:01
}

GetCurrentUsage

通过本调用可以查询当前账号的 call limit 和 character limit 以及两者的使用情况。Call limit 和character limit 限制以月计算。

资源路径

GET /translation/v1/current_usage

运行逻辑

1. 用户通过 token 验证之后，查询该用户的 call limit 和 character limit 两者总量还有两者使用情况。

请求接受参数

没有

输出

如果查询成功，将返该用户的 call limit 和 character limit 两者总量还有两者使用情况。

响应字段描述

输出字段	类型	出现频率	含义
ackValue	String	经常	SUCCESS 或 FAILURE
errorMessage	object	根据结果	如果发生异常或请求错误，就可能看到errorMessage字段。 "errorMessage": { "error": [ { "errorId": 1001, "domain": "Application", "category": "translation", "message": "Parameter dateRange is missing", "longMessage": "Parameter dateRange is missing", "actionToTake": "CORRECTINPUTDATA" } ] }
timestamp	String	经常	响应的服务器时间为 GMT 时间，格式为：YYYY-MM-DD HH:MM:SS
data	object	根据结果	请求成功，并且有数据，这个字段是个对象。否则返回 null。
statusCode	int	经常	请求响应码 null
extension	List	经常	补充字段

响应内容中字段解释：

Key	Description
callLimit	这个月 call limit 的总数
callUsage	这个月 call limit 的使用量
characterLimit	这个月 character limit 的总量
characterUsage	这个月 character limit 的使用量

errorMessage总字段解释：

Key	Description
errorId	错误编号
domain	服务名称，值为translation (翻译服务)
category	错误类别，值为 System (系统类别错误) Application (应用类别错误) Request (请求类别错误)
message	错误信息
longMessage	错误详细信息
actionToTake	纠正方式，值为 ConsultTechSupport (联系技术支持寻求帮助) CorrectInputData (修改请求参数) Retry (重试请求)

响应举例

{
  "ackValue": "SUCCESS",
   "data": {
         "callLimit": 10000,
         "callUsage": 9061,
         "characterLimit": 100000000,
         "characterUsage": 99999984
   },
   "extension": [],
   "statusCode": 200,
   "timeStamp": 2018-01-01 00:01:01
}

GetTranslationData

本调用输出目前CBT Translation API所支持的语言、翻译的内容范围(scopes)以及一些有关的数据。

资源路径

GET /translation/v1/translation_data

运行逻辑

1. 查询支持的刊登翻译范围，支持的原始语言和目标语言。

请求接受参数

没有

输出

如果查询成功，将返支持的刊登翻译范围，支持的原始语言和目标语言

响应字段描述

输出字段	类型	出现频率	含义
ackValue	String	经常	SUCCESS 或 FAILURE
errorMessage	object	根据结果	如果发生异常或请求错误，就可能看到errorMessage字段。 "errorMessage": { "error": [ { "errorId": 1001, "domain": "translation", "category": "Application", "message": "Parameter dateRange is missing", "longMessage": "Parameter dateRange is missing", "actionToTake": "CORRECTINPUTDATA" } ] }
timestamp	long	经常	响应的服务器时间
data	String	经常	响应的服务器时间为 GMT 时间，格式为：YYYY-MM-DD HH:MM:SS 。
statusCode	int	经常	请求响应码 null
extension	List	经常	补充字段

响应内容中字段解释：

Key	类型	Description
scopes	List	支持翻译内容范围 (scope) 的集合。 code 为属性值，description 为属性值的描述
sources	List	支持翻译原始语言的集合。 code 为属性值，description 为属性值的描述
targets	List	支持翻译目标语言的集合。 code 为属性值，description 为属性值的描述

errorMessage总字段解释：

Key	Description
errorId	错误编号
domain	服务名称，值为translation (翻译服务)
category	错误类别，值为 System (系统类别错误) Application (应用类别错误) Request (请求类别错误)
message	错误信息
longMessage	错误详细信息
actionToTake	纠正方式，值为 ConsultTechSupport (联系技术支持寻求帮助) CorrectInputData (修改请求参数) Retry (重试请求)

响应举例

{
  "ackValue": "SUCCESS",
  "data": {
    "scopes": [
    {
        "code": "desc",
        "description": "Item description"
    },
    {
        "code": "spec",
        "description": "Item specifics"
      },
    {
        "code": "title",
        "description": "Item title"
      }
       ],
    } "sources": [
     {
         "code": "en",
        "description": "eBay English"
      }
       ],
     "targets": [
     {
         "code": "de-DE",
         "description": "eBay Germany"
     },
    {
         "code": "fr-FR",
         "description": "eBay France"
     },
     {
         "code": "es-ES",
         "description": "eBay Spain"
     },
     {
          "code": "it-IT",
          "description": "eBay Italy"
     }
     ]
     },
   "extension": [],
   "statusCode": 200,
   "timeStamp": "2018-01-01 00:01:01"
}

GetCategorySuggestion

通过本调用可以查询刊登在新站点建议使用的类别 (Category ID)。

资源路径

GET /translation/v1/category_suggestion

运行逻辑

1. 本调用根据原刊登的 Item ID 找出原站点的类别，然后提供在新站点建议使用的类别 (Category ID)。

请求接受参数

服务接受以下参数：

参数名称

参数类型

参数是否必需

解释

sourceItemId

String

必需

原刊登编号 (Item ID)

targetSiteId

String

必需

新刊登将会创建到的站点 (site ID)

现在只支持以下站点：

法国 71

意大利 101

西班牙 186

德国 77

输出

如果查询成功，将提供在新站点建议使用的类别 (Category ID) 及有关信息。

响应字段描述

输出字段	类型	出现频率	含义
ackValue	String	经常	SUCCESS 或 FAILURE
errorMessage	object	根据结果	如果发生异常或请求错误，就可能看到errorMessage字段。 "errorMessage": { "error": [ { "errorId": 300116, "domain": "translation", "category": "Application", "message": "Invalid sourceItemId", "longMessage": "The sourceItemId {sourceItemId} provided is invalid. Please make sure that the item exists and belongs to the current user ({user ID}).", "actionToTake": "CORRECTINPUTDATA" } ] }
timestamp	long	经常	响应的服务器时间
data	String	经常	响应的服务器时间为 GMT 时间，格式为：YYYY-MM-DD HH:MM:SS 。
statusCode	int	经常	请求响应码 null
extension	List	经常	补充字段

响应内容中字段解释：

Key	类型	Description
sourceCategoryId	String	原刊登类别 (Category ID)
sourceSiteId	String	原刊登所在的站点 (Site ID)
targetCategoryId	String	新站点建议使用的类别 (Category ID)
targetSiteId	String	新刊登将会创建到的站点 (site ID)

errorMessage总字段解释：

Key	Description
errorId	错误编号
domain	服务名称，值为translation (翻译服务)
category	错误类别，值为 System (系统类别错误) Application (应用类别错误) Request (请求类别错误)
message	错误信息
longMessage	错误详细信息
actionToTake	纠正方式，值为 ConsultTechSupport (联系技术支持寻求帮助) CorrectInputData (修改请求参数) Retry (重试请求)

响应举例

{
"ackValue": "SUCCESS",
"data": {
"sourceCategoryId": 79682,
"sourceSiteId": 0,
"targetCategoryId": 16038,
"targetSiteId": 101
},
"extension": [],
"statusCode": 200,
"timeStamp": "2018-11-01 00:01:01"
}

RecordTranslatedListing

通过这调用卖家可以把翻译后的内容所创建的新刊登的 item ID 回传到 CBT Translation 服务。CBT Translation API 的用家必须通过本调用向我们报告新刊登的item ID，否则将无法继续使用本接口。

资源路径

POST /translation/v1/record_translated_listing

运行逻辑

1. 输入 TranslateListing 调用返回的 translationId 和新刊登编号 itemId，以作统计。

请求格式

{
"itemId","string",
"translationId","string"
}

请求参数

服务接受以下参数：

参数名称	参数类型	参数是否必需	解释
itemId	String	必需	根据翻译后内容创建的新刊登编号 (Item ID)。
translationId	String	必需	使用 TranslateListing 调用时返回的 translationId。

响应字段描述

没有

errorMessage总字段解释：

Key	Description
errorId	错误编号
domain	服务名称，值为translation (翻译服务)
category	错误类别，值为 System (系统类别错误) Application (应用类别错误) Request (请求类别错误)
message	错误信息
longMessage	错误详细信息
actionToTake	纠正方式，值为 ConsultTechSupport (联系技术支持寻求帮助) CorrectInputData (修改请求参数) Retry (重试请求)

错误编码 (Error Code) 参考

Error Code	Message	Long Message
300001	Missing required parameter: itemId	The required parameter item ID (itemId) is missing. The request cannot be fulfilled.
300002	Missing required parameter: translationId	The required parameter translation ID (translationId) is missing. The request cannot be fulfilled.
300003	Missing required parameter: target	The required parameter target language (target) is missing. The request cannot be fulfilled.
300101	Invalid source value	The value of source parameter "{incorrect value}" is invalid. Please check make the call with a correct value.
300102	Invalid target value	The value of target parameter "{incorrect value}" is invalid. Please check make the call with a correct value.
300103	Invalid scope value	The value of scope parameter "{incorrect value}" is invalid. Please check make the call with a correct value.
300104	Invalid itemId	The itemId {itemId} provided is invalid. Please make sure that the item exists and belongs to the current user ({user ID}).
300105	Invalid translationId	The translationId {translationId} provided is invalid. Please make sure that the translation ID exists and belongs to the current user ({user ID}).
300106	Invalid translated listing	The translated listing provided is invalid. The translated listing cannot be created earlier than the source listing.
300107	The listing to be translated must be active.	The listing to be translated is not currently active. Please make sure the listing is still active.
300108	The translated listing to be recorded must be active.	The translated listing to be recorded is not currently active. Please make sure the listing is still active.
300109	Invalid text to translate	The text to translate ({textlist.name, textlist.name, …}) cannot be found in the source listing. Please make sure that you are translating contents from the source listing.
300110	Too many text elements to translate	There are too many text elements to translate in textlist. You cannot have more than 20 elements to translate at a time.
300111	Duplicated translated listing	You cannot record the same translated listing item ID for two source listings.
300201	Your call limit has been reached.	Your call limit has been reached. Your {monthly number of calls/monthly number of characters} has exceeded the limit. Please try again next month.
300202	You are not authorized to make the call.	You are not authorized to make the call. Please contact eBay to request for access.
300300	This item does not belong to the current user.	The item (Item ID {item ID}) does not belong to the current user ({user ID}). The request cannot be fulfilled.
300400	Translation service is not available. Please try again later.	Translation service is not available. Please try again later. If the problem persists, please contact eBay.
300500	Translation service is not able to provide normal results. Please try again later.	Translation service returned errors while fulfilling the request. Please try again later. If the problem persists, please contact eBay.

警告编码 (Warning Code) 参考

Warning Code	Message	Long Message
200001	The translated title is over the character limit of item title	The translated title is over the 80-character limit of item title. You may not be able to create a listing with the translated title.

Note: Curly brackets { } in the messages are placeholders.

更新时间： 2018-11-06

开发者专区

警告编码 (Warning Code) 参考

警告编码 (Warning Code) 参考