翻译反馈API

功能概述

• 云上曲率定期会对客户翻译数据进行性能评测&模型迭代
• 实际用户反馈问题沟通链路较长，翻译反馈API应运而生
• 应用内可集成翻译反馈API，支持用户对于翻译效果进行反馈评价，选择翻译效果 好/不好
• 云上会对用户反馈的数据进行逐条check&分析
• 同时用户反馈的数据统计会展示在对应项目的【数据统计】下

接入方式

请求 URL:

https://translate.ilivedata.com/api/v2/translate/feedback

HTTP 请求:

• 请求Header:

• 请求方法：POST

• 请求体JSON对象：

• 请求体示例

{
    "source":"en",
    "target":"zh-CN",
    "sourceText":"hello world",
    "targetText":"世界你好",
    "feedback":1,
    "userId":"119156631"
}

签名:

当用户请求Translation API时，可以使用appId和secretKey对请求做签名，当API收到带签名信息的请求之后，将使用相同的算法验证签名，如果发现签名不一致，API将会返回401给用户。如果API验证签名一致，且appId对应的用户有权限操作请求的资源，则请求成功，否则API返回401。

• 通过 HTTP 请求 Header 发送签名

方法: 在请求中加入名为 Authorization 的 Header，值为签名值。如下：

	Authorization: *****

• 签名计算方法

1. 构造规范化的请求字符串（Canonicalized Query String）:

   a. 由于签名要求唯一性，包括顺序，所以需要按照参数名称排序。

   b. 依据以下规则对参数名和参数值做URL编码。有关更多信息，请参见 RFC 3986

   * A-Z, a-z, 0-9, 减号 ( - ), 下划线 ( _ ), 点号 ( . ), 和 波浪号 ( ~ ) 不编码。
   * 其它字符编码成 %XY 的格式，其中 XY 是字符对应 ASCII 码的 16 进制表示，字母要大写。比如英文的双引号（”）对应的编码为 %22
   * 对于扩展的 UTF-8 字符，编码成 %XY%ZA… 的格式
   * 英文空格（ ）要编码成 %20，而不是加号（+）。
   

   c. 使用等号字符 (=) 将参数名称与参数值分离，即使参数值为空也如此。使用与字符 (&) 分隔参数和值对。将参数及其值连接组成一个长字符串，中间没有空格。允许参数值内有空格，但空格必须经 URL 编码成 %20。在连接后的字符串中，句点字符 (.) 未进行转义。RFC 3986 将句点字符视为非保留字符，因此未对其进行 URL 编码。

   d. 一般支持URL编码的库（比如 Java 中的 java.net.URLEncoder）都是按照 “application/x-www-form-urlencoded”的 MIME 类型的规则进行编码的。实现时可以直接使用这类方式进行编码，把编码后的字符串中加号（+）替换成 %20、星号（*）替换成 %2A、%7E 替换回波浪号（~），即可得到上述规则描述的编码字符串。

2. 构造被签名字符串 StringToSign ("\n" 代表ASCII里的换行符): StringToSign = HTTPMethod + “\n” + HostHeaderInLowercase + “\n” + HTTPRequestURI + “\n” + CanonicalizedQueryString <从上一步得到> HTTPRequestURI是请求URI的绝对路径，不包含请求串。如果HTTPRequestURI为空，也要保留一个正斜杠 ( / )

3. 使用 HMAC-SHA256 协议创建基于哈希的消息身份验证代码 (HMAC)，然后计算签名。 StringToSign作为签名字符串，secretKey作为秘钥，SHA256作为哈希算法

   有关 HMAC 的更多信息，请参阅 HMAC：用于消息身份验证的哈希密钥（https://tools.ietf.org/html/rfc2104）。

4. 将上一步的结果转换为BASE64串

5. 将BASE64串放入HTTP请求Header的Authorization

• 签名示例

1. 下面是appId & secretKey的示例

appId=***
secrectKey=***

2. 下面是示例请求

{
    "source":"en",
    "target":"zh-CN",
    "sourceText":"hello world",
    "targetText":"世界你好",
    "feedback":1,
    "userId":"119156631"
}

3. 生成CanonicalizedQueryString

b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118

4. 生成StringToSign

POST
translate.ilivedata.com
/api/v2/translate/feedback
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
X-AppId:1000
X-TimeStamp:2020-07-31T07:59:03Z

5. HMAC计算得到的签名

******

HTTP 响应:

• 返回JSON字段说明

• 响应示例

{
	"errorCode":0,
	"errorMessage":"OK"
}