本節介紹如何創建簽名并將其添加到請求中。
## **主題**
* 簽名的工作原理
* 請求中的簽署過程是什么樣
* 簽名步驟的摘要
* [任務 1:創建規范請求](create-canonical-request.md)
* [任務 2:創建待簽字符串](create-string-to-sign.md)
* [任務 3:為 GSDATA Signature 計算簽名](calculate-signature.md)
* [任務 4:將簽名信息添加到請求](add-signature-to-request.md)
#### **簽名的工作原理**
1. 您創建一個規范請求。
2. 您使用規范請求和一些其他信息來創建要簽署的字符串。
3. 您使用自己的 gsdata api appkey 來生成一個簽名密鑰,并使用該簽名密鑰以及要簽署的字符串來創建簽名。
4. 您將生成的簽名添加到 HTTP 請求的標頭中或者作為查詢字符串參數添加。
清博開放平臺 收到請求后,將執行您完成的相同步驟來計算簽名。之后 GSDATA接口服務器 會將計算得到的簽名與您在請求中發送的簽名進行比較。如果簽名匹配,則處理請求。如果簽名不匹配,則拒絕請求。
#### **請求中的簽署過程是什么樣**
以下示例演示了 HTTP 請求(不帶任何簽名信息)從您的客戶端發送到 GSDATA 時可能的樣子。
~~~
GET http://api.gsdata.cn/weixin/v1/users?wx_name=rmrbwx&page=1&per-page=20 HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: api.gsdata.cn
x-gsdata-date: 20150830T123600Z
~~~
在完成簽名任務之后,請將身份驗證信息添加到請求中。您可通過兩種方式添加身份驗證信息:
#### **Authorization 標頭**
您可使用 Authorization 標頭將身份驗證信息添加到請求中。盡管該 HTTP 標頭名為 Authorization,但簽名信息實際上是用于身份驗證的,目的是確定請求方。
Authorization 標頭包含以下信息:
* 用于簽名的算法 (GSDATA-HMAC-SHA256)
* 憑證范圍(包含您的訪問密鑰 ID)
* 已簽名標頭的列表
* 計算簽名。該簽名基于您的請求信息,由您使用 gsdata 密鑰生成。該簽名用于向 gsdata 確認您的身份。
下面的示例說明在您創建簽名信息并將它添加到請求的 Authorization 標頭之后,前面的請求看起來是什么樣。
~~~
POST http://api.gsdata.cn/weixin/v1/users?wx_name=rmrbwx&page=1&per-page=20 HTTP/1.1
Authorization: GSDATA-HMAC-SHA256 SignedHeaders=content-type;host;x-gsdata-date, Signature=d37af66cc90dc26bb2e27d2a97316b729b82589b5e4648f1ae34cb83a3f546cd
content-type: application/x-www-form-urlencoded; charset=utf-8
host: api.gsdata.cn
x-gsdata-date: 20150830T123600Z
~~~
### **簽名步驟的摘要**
要創建已簽名的請求,請完成以下操作:
* 任務 1:創建規范請求
將請求的內容(主機、操作、標頭等)組織為標準(規范)格式。規范請求是用于創建待簽字符串的輸入之一。
* 任務 2:創建待簽字符串
使用規范請求和額外信息(例如算法、請求日期、憑證范圍和規范請求的摘要(哈希))創建待簽字符串。
* 任務 3:為 GSDATA Signature 計算簽名
使用 GSDATA 秘密訪問密鑰作為初始哈希操作的密鑰,對請求日期、服務執行一系列加密哈希操作(HMAC 操作),從而派生簽名密鑰。在派生簽名密鑰后,通過對待簽字符串執行加密哈希操作來計算簽名。使用派生的簽名密鑰作為此操作的哈希密鑰。
* 任務 4:將簽名信息添加到請求
在計算簽名后,將其添加到請求的 HTTP 標頭或查詢字符串中。