微信小程序 服務端能力

后端 API

小程序還提供了一系列在后端服務器使用 HTTPS 請求調(diào)用的 API，幫助開發(fā)者在后臺完成各類數(shù)據(jù)分析、管理和查詢等操作。如 getAccessToken，code2Session 等。

access_token

access_token 是小程序全局唯一后臺接口調(diào)用憑據(jù)，調(diào)用絕大多數(shù)后臺接口時都需使用。開發(fā)者可以通過 getAccessToken 接口獲取并進行妥善保存。

為了 access_token 的安全性，后端 API 不能直接在小程序內(nèi)通過 wx.request 調(diào)用，即 api.weixin.qq.com 不能被配置為服務器域名。開發(fā)者應在后端服務器使用getAccessToken獲取 access_token，并調(diào)用相關(guān) API；

請求參數(shù)說明

• 對于 GET 請求，請求參數(shù)應以 QueryString 的形式寫在 URL 中。
• 對于 POST 請求，部分參數(shù)需以 QueryString 的形式寫在 URL 中（一般只有 access_token，如有額外參數(shù)會在文檔里的 URL 中體現(xiàn)），其他參數(shù)如無特殊說明均以 JSON 字符串格式寫在 POST 請求的 body 中。

返回參數(shù)說明

注意：當API調(diào)用成功時，部分接口不會返回 errcode 和 errmsg，只有調(diào)用失敗時才會返回。

消息推送

接入微信小程序消息推送服務，可以兩種方式選擇其一：

1. 開發(fā)者服務器接收消息推送
2. 云函數(shù)接收消息推送

開發(fā)者服務器接收消息推送

開發(fā)者需要按照如下步驟完成：

1. 填寫服務器配置
2. 驗證服務器地址的有效性
3. 據(jù)接口文檔實現(xiàn)業(yè)務邏輯，接收消息和事件

第一步：填寫服務器配置

登錄小程序后臺后，在「開發(fā)」-「開發(fā)設置」-「消息推送」中，管理員掃碼啟用消息服務，填寫服務器地址（URL）、令牌（Token） 和 消息加密密鑰（EncodingAESKey）等信息。

• URL: 開發(fā)者用來接收微信消息和事件的接口 URL。開發(fā)者所填寫的URL 必須以 http:// 或 https:// 開頭，分別支持 80 端口和 443 端口。
• Token: 可由開發(fā)者可以任意填寫，用作生成簽名（該 Token 會和接口 URL 中包含的 Token 進行比對，從而驗證安全性）。
• EncodingAESKey: 由開發(fā)者手動填寫或隨機生成，將用作消息體加解密密鑰。

同時，開發(fā)者可選擇消息加解密方式：明文模式（默認）、兼容模式和安全模式。可以選擇消息數(shù)據(jù)格式：XML 格式（默認）或 JSON 格式。

模式的選擇與服務器配置在提交后都會立即生效，請開發(fā)者謹慎填寫及選擇。切換加密方式和數(shù)據(jù)格式需要提前配置好相關(guān)代碼，詳情請參考 消息加解密說明。

第二步：驗證消息的確來自微信服務器

開發(fā)者提交信息后，微信服務器將發(fā)送GET請求到填寫的服務器地址URL上，GET請求攜帶參數(shù)如下表所示：

開發(fā)者通過檢驗 signature 對請求進行校驗（下面有校驗方式）。若確認此次 GET 請求來自微信服務器，請原樣返回 echostr 參數(shù)內(nèi)容，則接入生效，成為開發(fā)者成功，否則接入失敗。加密/校驗流程如下：

1. 將token、timestamp、nonce三個參數(shù)進行字典序排序
2. 將三個參數(shù)字符串拼接成一個字符串進行sha1加密
3. 開發(fā)者獲得加密后的字符串可與signature對比，標識該請求來源于微信

驗證URL有效性成功后即接入生效，成為開發(fā)者。

檢驗signature的PHP示例代碼：

private function checkSignature()
{
    $signature = $_GET["signature"];
    $timestamp = $_GET["timestamp"];
    $nonce = $_GET["nonce"];

    $token = TOKEN;
    $tmpArr = array($token, $timestamp, $nonce);
    sort($tmpArr, SORT_STRING);
    $tmpStr = implode( $tmpArr );
    $tmpStr = sha1( $tmpStr );

    if ($tmpStr == $signature ) {
        return true;
    } else {
        return false;
    }
}

PHP示例代碼下載：下載

第三步：接收消息和事件

當某些特定的用戶操作引發(fā)事件推送時（如用戶向小程序客服發(fā)送消息、或者進入會話等情況），微信服務器會將消息（或事件）的數(shù)據(jù)包以 POST 請求發(fā)送到開發(fā)者配置的 URL，開發(fā)者可以依據(jù)自身業(yè)務邏輯進行響應。

微信服務器在將用戶的消息發(fā)給開發(fā)者服務器地址后，微信服務器在五秒內(nèi)收不到響應會斷掉連接，并且重新發(fā)起請求，總共重試三次。如果在調(diào)試中，發(fā)現(xiàn)用戶無法收到響應的消息，可以檢查是否消息處理超時。關(guān)于重試的消息排重，有 msgid 的消息推薦使用 msgid 排重。事件類型消息推薦使用 FromUserName + CreateTime 排重。

服務器收到請求必須做出下述回復，這樣微信服務器才不會對此作任何處理，并且不會發(fā)起重試，否則，將出現(xiàn)嚴重的錯誤提示。詳見下面說明：

1. 直接回復success（推薦方式）
2. 直接回復空串（指字節(jié)長度為0的空字符串，而不是結(jié)構(gòu)體中content字段的內(nèi)容為空）
3. 若接口文檔有指定返回內(nèi)容，應按文檔說明返回

對于客服消息，一旦遇到以下情況，微信會在小程序會話中向用戶下發(fā)系統(tǒng)提示“該小程序客服暫時無法提供服務，請稍后再試”：

1. 開發(fā)者在5秒內(nèi)未回復任何內(nèi)容
2. 開發(fā)者回復了異常數(shù)據(jù)

如果開發(fā)者希望增強安全性，可以在開發(fā)者中心處開啟消息加密，這樣，用戶發(fā)給小程序的消息以及小程序被動回復用戶消息都會繼續(xù)加密，詳見消息加解密說明。

云函數(shù)接收消息推送

需開發(fā)者工具版本至少 1.02.1906252

開通了云開發(fā)的小程序可以使用云函數(shù)接收消息推送，目前僅支持客服消息推送。

接入步驟如下：

1. 開發(fā)者工具中填寫配置并上傳
2. 云函數(shù)中處理消息

第一步：開發(fā)者工具云開發(fā)控制臺中增加配置

打開云開發(fā)控制臺，到設置 tab 中選擇全局設置 - 添加消息推送配置。消息類型對應收包的 MsgType，事件類型對應收包的 Event，同一個 <消息類型, 事件類型> 二元組只能推到一個環(huán)境的一個云函數(shù)。例如客服消息文本消息對應的就是消息類型為 text，事件類型為空。具體值請查看各個消息的消息格式。

第二步：云函數(shù)中處理消息

云函數(shù)被觸發(fā)時，其 event 參數(shù)即是接口所定義的 JSON 結(jié)構(gòu)的對象（統(tǒng)一 JSON 格式，不支持 XML 格式）。

以客服消息為例，接收到客服消息推送時，event 結(jié)構(gòu)如下：

{
  "FromUserName": "ohl4L0Rnhq7vmmbT_DaNQa4ePaz0",
  "ToUserName": "wx3d289323f5900f8e",
  "Content": "測試",
  "CreateTime": 1555684067,
  "MsgId": "49d72d67b16d115e7935ac386f2f0fa41535298877_1555684067",
  "MsgType": "text"
}

此時可調(diào)用客服消息發(fā)送接口回復消息，一個簡單的接收到消息后統(tǒng)一回復 “收到” 的示例如下：

// 云函數(shù)入口文件
const cloud = require('wx-server-sdk')

cloud.init()

// 云函數(shù)入口函數(shù)
exports.main = async (event, context) => {
  const wxContext = cloud.getWXContext()
  
  await cloud.openapi.customerServiceMessage.send({
    touser: wxContext.OPENID,
    msgtype: 'text',
    text: {
      content: '收到',
    },
  })

  return 'success'
}