v3 接入文档

一、 服务概述

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

二、 服务申请

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

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

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

三、 接入方式

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

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

  • 请求方法: GET/POST

  • 请求参数

参数 是否必传 描述
q 必传 需要翻译的原文文本。文本为不超过 1024 个字符的 UTF-8 编码字符串
source 可选 原文本的语种(下称“源语言”)。可设置为语言支持中列举的 ISO 639-1 标准的语言代码之一。未传该参数及 source 值为空或无效时,将自动进行语种检测。
target 必传 翻译的目标语言,同上需设置为语言支持文档中列举的 ISO 639-1 标准的语言代码之一。
appId 必传 项目或应用的唯一标识符。在官网注册账号及公司,并在控制台创建实时翻译项目后,即可得到项目的 appId
suggestedSource 可选 回退参考语种。自动语种检测失败时,可将该语种作为源语言。同上需设置为语言支持文档中列举的 ISO 639-1 标准的语言代码之一。
profanity 可选 敏感内容过滤功能。可选值为 censoroff ,分别对应开启和关闭,如未指定则默认关闭。此功能仅通过关键词屏蔽,如果您的业务对文本审核有更高要求或需定制,欢迎您接入云上曲率的多语言文本审核服务。
timeStamp 必传 请求的 UTC 时间戳。需要把时间戳按 W3C 标准格式化,例如: 2010-01-31T23:59:59Z.(格式标准详见:http://www.w3.org/TR/xmlschema-2/#dateTime)
  • 请求签名:

当用户请求 Translation API 时,可以使用 appIdsecretKey 对请求做签名,当 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/v3/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/v3/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 格式,请参考以下示例。