接入文档

一、 服务概述

云上曲率翻译开放平台是面向游戏行业广大开发者提供开放服务的平台。

二、 服务申请

翻译API采用全流程自助申请的模式。

点击云上曲率官网(https://www.ilivedata.com/) 右上方的“免费试用”按钮,按照提示信息“注册账号-创建企业”后,在控制台选择“实时翻译”服务并创建应用,即可获得pid和服务密钥。

如需开通更多服务,可在管理控制台-总览页面开通其他服务。

三、 接入方式

  • 请求 URL: 从云上曲率“控制台-服务配置”中获取

  • HTTP 请求Header: Accept: application/json;charset=UTF-8

  • 请求方法: GET/POST

  • 请求参数

参数 必需 描述
q 必需 要翻译的输入文本。 此文本为不超过512个字符的UTF-8编码字符串
source 必需 输入文本的语言,设置为<语言支持>中列举的ISO 639-1标准的语言代码之一。API总是会尝试检测输入文本的语言,如果检测失败会使用此处设置的语言来翻译
target 必需 翻译的目标语言,设置为<语言支持>中列举的ISO 639-1标准的语言代码之一。
appId 必需 项目或应用的唯一标识符。
profanity 可选 敏感语过滤。设置为以下2项之一: off, censor。如果这个参数没有设置则默认为off。(1) off: 不过滤敏感语。(2) censor: 如果翻译后的文本包含敏感语,敏感语在翻译结果中会被若干星号(*)替换。
textType 可选 可选值为chat或mail。如未指定,则默认使用’chat’。如果希望文本中的\t \n 和空格符在译文中保持不变,则推荐使用’mail’模式,如游戏内的信件。
timeStamp 必需 请求的UTC时间戳。需要把时间戳按W3C标准格式化,例如: 2010-01-31T23:59:59Z. (http://www.w3.org/TR/xmlschema-2/#dateTime).
  • 请求签名:

当用户请求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. 下面是示例请求

     https://translate.ilivedata.com/api/v2/translate?source=en&target=zh-CN&q=hello%20world&appId=***&timeStamp=2015-09-23T04%3A55%3A07Z
    
  3. 生成StringToSign

     POST\n
     translate.ilivedata.com\n
     /api/v2/translate\n
     appId=***&q=hello%20world&source=en&target=zh-CN&timeStamp=2015-09-23T04%3A55%3A07Z
    
  4. HMAC计算得到的签名

     ******
    
  • HTTP响应:

Content-Type: application/json;charset=UTF-8

结果为JSON格式,请参考以下示例。