v3 API 签名机制

OpenSearch服务会对每个访问的请求进行身份验证，通过使用Access Key ID和Access Key Secret进行对称加密的方法来验证请求的发送者身份。

Access Key ID和Access Key Secret由阿里云官方颁发给访问者（可以通过阿里云官方网站申请和管理），其中Access Key ID用于标识访问者的身份。

Access Key Secret是用于加密签名字符串和服务器端验证签名字符串的密钥，必须严格保密，只有阿里云和用户知道。

支持应用类型

• 高级版
• 标准版

通信协议

只支持 HTTP 协议

请求对应方式

• 搜索数据必须使用：GET
• 推送数据必须使用：POST

Authorization 字段计算方法

需在 HTTP 请求 Header 头信息中，添加 Authorization（授权）来包含签名（Signature）信息，表明该请求已被授权。请求Header 中也需要包含文档下面“签名示例”部分中“请求Header”中提到的这些相关的请求Header。

请求 Header 中包含的参数都必须要参与签名（例如 Content-Md5，Content-Type，Date，Http专有 Header 等等）。

"Authorization: OPENSEARCH " + AccessKeyId + ":" + Signature
Signature = base64(hmac-sha1(AccessKeySecret,
            VERB + "\n"
            + Content-Md5 + "\n"
            + Content-Type + "\n"
            + Date + "\n"
            + CanonicalizedOpenSearchHeaders
            + CanonicalizedResource))

按照RFC2104的定义，使用上面的用于签名的字符串计算签名HMAC值

• 签名的方法用 RFC 2104 中定义的 HMAC-SHA1 方法
• 签名的字符串必须为UTF-8格式
• 含有中文字符的签名字符串必须先进行UTF-8编码，再与AccessKeySecret计算最终签名
• 签名参数先后顺序，必须和上面保持一致

查询请求

• Header 中的参数值必须要与对应签名方法中的参数值一致
• 建议将 Content-Md5，Content-Type，Date，CanonicalizedOpenSearchHeaders，Authorization 这些参数都添加到请求Header中，只包含必须参数可能会出现报错，需避免
• 请求 Header 中包含的参数都必须要参与签名

推送请求

• Header 中的参数值必须要与对应签名方法中的参数值一致
• 理论上 Content-Md5，Content-Type，Date，CanonicalizedOpenSearchHeaders，Authorization 这些参数都需要添加到请求Header中，只包含必须参数可能会出现报错，需避免
• 请求 Header 中包含的参数都必须要参与签名

构建CanonicalizedOpenSearchHeaders的方法

所有以 X-Opensearch- 为前缀的 Http专有 Header 被称为 CanonicalizedOpenSearchHeaders，其他非 Http专有 Header 将不被纳入验证

1. 将所有以 X-Opensearch- 为前缀的Http专有 Header 对应的内容补齐，例如X-Opensearch-Nonce : 1551089397451704（该Nonce参数值，可由10位时间戳+6位随机值(100000~999999)组合而成，例如1551089397451704），再去除所有值为空的Http专有 Header

2. 将这些有对应内容值的Http专有 Header 按照名称的字典序进行升序排序

3. 再将这些排序后的专有 Header名，全部转换成小写字母，例如将 X-Opensearch-Nonce : 1551089397451704 转换成 x-opensearch-nonce : 1551089397451704

4. 删除请求头和内容之间分隔符两端出现的任何空格。例如该 x-opensearch-nonce : 1551089397451704 参数，删除两端空格后为：x-opensearch-nonce:1551089397451704

5. 最后将每个请求头及对应内容作为一个单位项，再将每一项之间用 \n 连接拼成最后的 CanonicalizedOpenSearchHeaders，注意最后一个也要有 \n

注意:

• 若查询请求Header中不包含此处Http专有 Header，即该参数中一个Http专有 Header都没有，则无需 \n，只需在签名方法中去掉该CanonicalizedOpenSearchHeaders签名参数即可，该参数不参与签名计算。
• 将Http专有 Header添加到Header中时，不能是转换后的小写形式，需按原格式显示

构建CanonicalizedResource的方法

• 签名的字符串必须为UTF-8格式，且含有中文字符的签名字符串必须先进行 UTF-8 编码，再与 AccessKeySecret 计算最终签名
• 查询 CanonicalizedResource = path + ? + query
• 推送 CanonicalizedResource = path

构建 path 部分

对 path 进行urlencode后，再替换 %2F 为 /，下面的app_schema_demo需替换为自己应用名，常见 path 如下所示

• search查询path
  /v3/openapi/apps/app_schema_demo/search
  
• suggest查询path
  /v3/openapi/suggestions/suggestion_name/actions/search
  
• 最终查询指定应用信息查询请求串，下面“appid”需替换为待查询的应用ID，需包含Authorization授权签名参数（无需指定查询参数）
  /v3/openapi/apps/appid
  
• 推送数据path（tab 是要推送到应用中的某个具体表名，也需替换为自己应用表名）
  /v3/openapi/apps/app_schema_demo/tab/actions/bulk

构建 query 部分

query 部分由查询参数构成，参数为键值对形式

1. 为需要指定的查询参数设置对应的参数值，并去掉value为空的参数（value为空的参数不计算签名）
2. 再对每一个参数按照先比较参数名后比较参数值的顺序，按照字典升序
3. 再对每一部分的参数名和参数值进行 urlencode（指定RFC 3986模式），再将参数名和对应参数值之间通过=拼接
4. 再将各个查询参数之间用 & 分割拼接并存储到 query 字符串中
5. 最后按照 path + ? + query 方式拼接至CanonicalizedResource字符串中，即完成查询操作CanonicalizedResource参数构建，示例如下：
   /v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27&&sort%3Did&&config%3Dformat%3Afulljson
   • 以上请求串中主要包含的参数及参数值描述如下：
     • fetch_fields=name
   • 以上请求串中主要包含的query参数中各子句及参数值描述如下（第一个是query参数，第二个是query子句及其它相关子句）：
     • query=query=name:'文档'&&sort=id&&config=format:fulljson

注意:

• 在urlencode之前，query参数中各个查询子句之间必须要用 && 进行拼接
• 若为推送操作，则只需将 path 部分拼接至 CanonicalizedResource 字符串中即可

构建 Authorization 字段

构建方法参考开头部分描述，需添加到请求 Header 中。假如AccessKeyId 为LTAItQcybixtR9A0，Signature为 1P7tfEh+CU5kFYRXzZ14kkJUAMc=，则python3示例代码大致如下：

headers['Authorization'] = 'OPENSEARCH ' + 'LTAItQcybixtR9A0' + ':' + '1P7tfEh+CU5kFYRXzZ14kkJUAMc='

签名示例

假如参数值如下

• Authorization值为OPENSEARCH LTAItQcybixtR9A0:1P7tfEh+CU5kFYRXzZ14kkJUAMc=
• AccessKeySecret值为 R0OGKsMj0etgyA9nZM5ykhMqHXBfKG
• 请求方式为GET
• Content-MD5值为空，此处作为查询请求
• Content-Type值为application/json
• Date值为2019-02-25T10:09:57Z
• CanonicalizedOpenSearchHeaders值为x-opensearch-nonce:1551089397451704
• CanonicalizedResource值为/v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27&&sort%3Did&&config%3Dformat%3Afulljson

注意:

• 请求Header中参数值需与签名方法中对应参数值保持一致

可用以下方法计算签名(Signature)

• 以 hash_hmac 和 base64_encode 编码生成加密值作为Signature

python3 示例代码：

import hmac
import base64
signature_string = '\n'.join(['GET',
                              '',
                              'application/json',
                              '2019-02-25T10:09:57Z',
                              'x-opensearch-nonce:1551089397451704',
                              '/v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27&&sort%3Did&&config%3Dformat%3Afulljson'])
signature_hmac = hmac.new('R0OGKsMj0etgyA9nZM5ykhMqHXBfKG'.encode('utf-8'), signature_string.encode('utf-8'), 'sha1')
signature = base64.b64encode(signature_hmac.digest())

假如AccessKeySecret值为 R0OGKsMj0etgyA9nZM5ykhMqHXBfKG 那么通过上面的签名方法构造出来的签名值为 1P7tfEh+CU5kFYRXzZ14kkJUAMc=

构建请求串

请求串 = host + CanonicalizedResource

需在 HTTP 请求 Header 头信息中增加 Authorization（授权）来包含签名（Signature）信息，表明该请求已被授权，同时Header中也需要包含上面提到的这些相关的请求Header。（host为应用访问API地址）

• 最终search查询请求串
  http://host/v3/openapi/apps/app_schema_demo/search?fetch_fields=name&query=query%3Dname%3A%27%E6%96%87%E6%A1%A3%27&&sort%3Did&&config%3Dformat%3Afulljson

• 最终suggest查询请求串
  http://host/v3/openapi/apps/{appName}/suggest/{suggestName}/search?hits=10&query=%E6%A0%87%E9%A2%98

• 最终查询指定应用信息查询请求串，下面最后一部分为“appid”值，假设为120001234该值，替换后如下所示，该查询请求也需包含Authorization授权签名参数（无需指定查询参数）
  http://host/v3/openapi/apps/120001234
  

• 最终推送数据请求串，此处推送数据需放在body体中
  http://host/v3/openapi/apps/app_schema_demo/tab/actions/bulk

v3API签名Demo

目前已对外公开 v3版官方Java SDK 和 PHP SDK，且PHP SDK已包含v3API签名过程实现源码，直接调用这些方法即可使用，也可参考 PHP SDK 签名实现过程源码，或参考本文档v3API签名过程来实现其它语言SDK。

因目前OpenSearch官方，没有正式对外提供官方的 python版 和 C#版 SDK，为方便用户参考实现该文档描述签名过程，此处提供 python及C#版查询和推送签名Demo，以供用户参考实现本文档签名操作。

注意：

此处提供 Demo 仅供参考，后续用户参考此 Demo 实现的 SDK 由用户自己维护。

Python版Demo

• python2 searchDemo
• python2 pushDemo
• python2_getApp_demo

• python3 searchDemo
• python3 pushDemo
• python3_getApp_demo

C#版Demo

• C#_NET_4.0_Search_Push_Demo

应用结构模板

• 测试应用结构模板