WebSocket鉴权使用说明

# WebSocket协议通用鉴权URL生成说明

### 1. 鉴权说明
---------------------

开发者需要自行先在控制台创建应用，利用应用中提供的appid，APIKey， APISecret进行鉴权，生成最终请求的鉴权url。鉴权方法见下方1.2。

### 1.2 鉴权参数
------------------------

| 参数          | 类型   | 必须 | 说明                                                | 示例                                                 |
| ------------- | ------ | ---- | --------------------------------------------------- | ---------------------------------------------------- |
| host          | string | 是   | 请求的主机                                          | aichat.xf-yun.com(使用时需替换为实际使用的接口地址） |
| date          | string | 是   | 当前时间戳，采用RFC1123格式，时间偏差需控制在300s内 | Fri, 05 May 2023 10:43:39 GMT                        |
| GET           | string | 是   | 请求方式                                            | /v1.1/chat HTTP/1.1                                  |
| authorization | string | 是   | base64编码的签名信息                                | 参考下方生成方式                                     |

最终url需要的参数如上，下方以Python为例进行鉴权参数的生成示例，开发者如果使用其它开发语言可以按照相同时间戳和apikey等常量来逐步生成参数和下方示例比对，确保鉴权步骤无误

####  1.2.1 date参数生成规则

```
from datetime import datetime
from time import mktime
from wsgiref.handlers import format_date_time

cur_time = datetime.now()
date = format_date_time(mktime(cur_time.timetuple()))
# 假使生成的date和下方使用的date = Fri, 05 May 2023 10:43:39 GMT

```

####  1.2.2 authorization参数生成规则

1）到控制台获取APIKey 和APISecret参数

2）利用上方的date动态拼接生成字符串tmp，这里以星火url为例，实际使用需要根据具体的请求url替换host和path。

```
tmp = "host: " + "spark-api.xf-yun.com" + "\n"
tmp += "date: " + date + "\n"
tmp += "GET " + "/v1.1/chat" + " HTTP/1.1"
"""上方拼接生成的tmp字符串如下
host: spark-api.xf-yun.com
date: Fri, 05 May 2023 10:43:39 GMT
GET /v1.1/chat HTTP/1.1
"""

```

3）利用hmac-sha256算法结合APISecret对上一步的tmp签名，获得签名后的摘要tmp\_sha。

```
import hmac
import hashlib
# 此处假设APISecret = MjlmNzkzNmZkMDQ2OTc0ZDdmNGE2ZTZi 
tmp_sha = hmac.new(self.APISecret.encode('utf-8'), tmp.encode('utf-8'), 						digestmod=hashlib.sha256).digest()
"""此时生成的tmp_sha结果如下
b'\xcf\x98\x07v\xed\xe9\xc5Ux\x0032\x93\x8e\xbb\xc0\xe5\x83C\xda\xba\x05\x0c\xd1\xdew\xccN7?\r\xa4'
"""

```

4）将上方的tmp\_sha进行base64编码生成signature

```
import base64
signature = base64.b64encode(tmp_sha).decode(encoding='utf-8')
"""此时生成的结果如下
z5gHdu3pxVV4ADMyk467wOWDQ9q6BQzR3nfMTjc/DaQ==
"""

```

5）利用上面生成的signature，拼接下方的字符串生成authorization\_origin

```
# 假设步骤1控制台获取的APIKey=addd2272b6d8b7c8abdd79531420ca3b
authorization_origin = f"api_key=\"{api_key}\", algorithm=\"hmac-sha256\", headers=\"host date request-line\", signature=\"{signature}\""
"""此时生成的authorization_origin字符串如下
api_key="addd2272b6d8b7c8abdd79531420ca3b", algorithm="hmac-sha256", headers="host date request-line", signature="z5gHdu3pxVV4ADMyk467wOWDQ9q6BQzR3nfMTjc/DaQ="
"""

```

6）最后再将上方的authorization\_origin进行base64编码,生成最终的authorization

```
authorization = base64.b64encode(authorization_origin.encode('utf-8')).decode(encoding='utf-8')
"""此时生成的authorization如下
YXBpX2tleT0iYWRkZDIyNzJiNmQ4YjdjOGFiZGQ3OTUzMTQyMGNhM2IiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iejVnSGR1M3B4VlY0QURNeWs0Njd3T1dEUTlxNkJRelIzbmZNVGpjL0RhUT0i
"""

```

####  1.2.3 生成最终url

将鉴权参数组合成最终的键值对，并urlencode生成最终的握手url。开发者可先根据上面的步骤一步步进行参数校验，确保生成的参数无误。

```
from urllib.parse import urlencode

v = {
		"authorization": authorization, # 上方鉴权生成的authorization
        "date": date,  # 步骤1生成的date
    	"host": "spark-api.xf-yun.com" # 请求的主机名，根据具体接口替换
}
url = "wss://spark-api.xf-yun.com/v1.1/chat?" + urlencode(v)
"""生成的最终url如下
wss://spark-api.xf-yun.com/v1.1/chat?authorization=YXBpX2tleT0iYWRkZDIyNzJiNmQ4YjdjOGFiZGQ3OTUzMTQyMGNhM2IiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iejVnSGR1M3B4VlY0QURNeWs0Njd3T1dEUTlxNkJRelIzbmZNVGpjL0RhUT0i&date=Fri%2C+05+May+2023+10%3A43%3A39+GMT&host=spark-api.xf-yun.com
"""

```