微信公众号 Python-SDK

Автор: @jeff_kit

Данный SDK поддерживает отправку сообщений и OAuth интерфейс для публичных аккаунтов WeChat и корпоративных аккаунтов. В этом документе и SDK предполагается, что пользователь уже имеет базовые знания о разработке публичных аккаунтов WeChat, а также может использовать документацию публичных и корпоративных аккаунтов для поиска соответствующих деталей интерфейса.

1. Установка

pip

pip install wechat

Установка из исходного кода

git clone git@github.com:jeffkit/wechat.git
cd wechat
python setup.py install

2. Обработка сообщений от пользователей в рамках фреймворка

Для обработки сообщений, отправленных пользователями через публичные аккаунты WeChat, данный SDK предоставляет микрофреймворк. Разработчику необходимо унаследовать класс wechat.official.WxApplication, реализовать методы, соответствующие различным типам сообщений, и интегрировать этот класс с предпочитаемым веб-фреймворком.

WxApplication выполняет проверку легитимности запросов и распространение сообщений внутри системы, а также структурирует входящие сообщения. Разработчик может сосредоточиться на бизнес-логике.

Основные методы класса WxApplication:

WxApplication.process(params, xml, token=None, app_id=None, aes_key=None)

Метод process класса WxApplication принимает следующие параметры:

• params — словарь параметров URL, который необходимо проанализировать из строки запроса обратного вызова WeChat. Формат: {'nonce': 1232, 'signature': 'xsdfsdfsd'}
• xml — содержимое XML, полученное при обратном вызове WeChat.
• token — токен публичного аккаунта WeChat, опционально, позволяет настроить в подклассе.
• app_id — идентификатор приложения публичного аккаунта WeChat, опционально, позволяет настроить в подклассе.
• aes_key — секретный ключ шифрования публичного аккаунта WeChat, опционально, позволяет настроить в подклассе.

В конце метод process возвращает строку (xml или echoStr).

Сценарий использования 1: проверка легитимности URL

После настройки URL и токена в настройках публичного аккаунта WeChat сервер WeChat будет обращаться к этому URL методом GET. Разработчик должен вызвать метод app.process(query, xml=None), чтобы вернуть echoStr.

qs = 'nonce=1221&signature=19selKDJF&timestamp=12312'
query = dict([q.split('=') for q in qs.split('&')])
app = YourApplication()
echo_str = app.process(query, xml=None)
# Вернуть echo_str в WeChat

Сценарий использования 2: обработка сообщений

Когда пользователь отправляет сообщение публичному аккаунту WeChat, сервер WeChat вызывает URL обратного вызова. Разработчик должен проверить легитимность каждого запроса и обработать сообщение. Для этого нужно вызвать метод app.process.

qs = 'nonce=1221&signature=19selKDJF&timestamp=12312'
query = dict([q.split('=') for q in qs.split('&')])
body = '<xml> ..... </xml>'
app = YourApplication()
result = app.process(query, xml=body)
# Вернуть result в WeChat

Пример подкласса WxApplication

Рассмотрим пример кода подкласса WxApplication, который возвращает текст, полученный от пользователя:

from wechat.official import WxApplication, WxTextResponse, WxMusic,\
    WxMusicResponse

class WxApp(WxApplication):

    SECRET_TOKEN = 'test_token'
    WECHAT_APPID = 'wx1234556'
    WECHAT_APPSECRET = 'sevcs0j'

    def on_text(self, text):
        return WxTextResponse(text.Content, text)

Необходимо настроить несколько параметров класса, которые можно найти на странице разработчика в разделе управления публичными аккаунтами WeChat. Первые три параметра не обязательны, но их нужно передать при вызове метода process.

• SECRET_TOKEN: токен обратного вызова для публичного аккаунта WeChat.
• APP_ID: идентификатор приложения для публичного аккаунта WeChat.
• ENCODING_AES_KEY: (необязательно), секретный ключ для шифрования, если ваш публичный аккаунт WeChat не использует шифрование, то этот параметр можно не указывать.
• UNSUPPORT_TXT:(необязательно), автоматически отвечает пользователю сообщением определённого типа, когда получает неподдерживаемое сообщение.
• WELCOME_TXT:(необязательно), сообщение по умолчанию, которое отправляется новым подписчикам.

Затем разработчик должен реализовать каждый метод on_xxx класса WxApplication. Существует соответствующий метод для каждого типа сообщения и события.

Методы on_xxx

Все методы on_xxx перечислены ниже:

• on_text — отвечает на текстовые сообщения от пользователей.
• on_link — отвечает на ссылки, отправленные пользователями.
• on_image — отвечает на изображения, отправленные пользователями.
• on_voice — отвечает на голосовые сообщения, отправленные пользователями.
• on_video — отвечает на видеосообщения, отправленные пользователями.
• on_location — отвечает на сообщения о местоположении, отправленные пользователями.
• on_subscribe — отвечает на события подписки пользователей.
• on_unsubscribe — отвечает на события отмены подписки пользователями.
• on_click — отвечает на события кликов по пользовательским меню.
• on_scan — отвечает на события сканирования QR-кодов пользователями.
• on_location_update — отвечает на обновления местоположения пользователей.
• on_view — отвечает на события просмотра пользовательских меню.
• on_scancode_push
• on_scancode_waitmsg
• on_pic_sysphoto
• on_pic_photo_or_album
• on_pic_weixin
• on_location_select

Определение метода on_xxx:

def on_xxx(self, req):
    return WxResponse()

Метод on_xxx принимает параметр req, экземпляр класса WxRequest, представляющий сообщение от пользователя. Он возвращает экземпляр подкласса WxResponse.

WxRequest

req — это экземпляр класса WxRequest, который представляет сообщение от пользователя. Его атрибуты соответствуют атрибутам XML сообщения. Разные типы сообщений имеют несколько общих атрибутов:

• ToUserName
• FromUserName
• CreateTime
• MsgType
• MsgId

Разные типы сообщений имеют разные атрибуты. Имя атрибута соответствует имени тега XML. Например, у сообщения типа text есть атрибут Content, а у сообщения image есть атрибуты PicUrl и MediaId. Более подробную информацию о сообщениях можно найти в официальной документации WeChat для публичных аккаунтов (http://mp.weixin.qq.com/wiki/10/79502792eef98d6e0c6e1739da387346.html).

WxResponse

Метод on_xxx должен возвращать экземпляр подкласса класса WxResponse. Подклассы WxResponse и их конструкторы:

WxTextResponse — текстовое сообщение

WxTextResponse("hello", req)

WxImageResponse — изображение

WxImageResponse(WxImage(MediaId='xxyy'),req)

WxVoiceResponse — голос

WxVoiceResponse(WxVoice(MediaId='xxyy'),req)

WxVideoResponse — видео

WxVideoResponse(WxVideo(MediaId='xxyy', Title='video', Description='test'),req)

WxMusicResponse — музыка

WxMusicResponse(WxMusic(Title='hey jude', 
    Description='dont make it bad', 
    PicUrl='http://heyjude.com/logo.png', 
    Url='http://heyjude.com/mucis.mp3'), req)

WxNewsResponse — новости

WxNewsResponse(WxArticle(Title='test news', 
    Description='this is a test', 
    Picurl='http://smpic.com/pic.jpg', 
    Url='http://github.com/jeffkit'), req)

WxEmptyResponse — без ответа ### Использование WxApplication в Django

Ниже на примере Django объясняется, как реализовать функцию (view) для обработки обратного вызова от WeChat, используя пример кода из WxApp:

from django.http import HttpResponse

def wechat(request):
    app = WxApp()
    result = app.process(request.GET, request.body)
    return HttpResponse(result)

Конфигурация urls.py:

urlpatterns = patterns('',
    url(r'^wechat/', 'myapp.views.wechat'),
)

Использование WxApplication во Flask

from flask import request
from flask import Flask
app = Flask(__name__)

@app.route('/wechat')
def wechat():
    app = WxApp()
    return app.process(request.args, request.data)

Хорошо. Это всё. WxApplication не зависит от веб-фреймворка, и вы можете использовать его с любым фреймворком.

Что? Вам не нравится создавать подклассы WxApplication?!

Ладно, на самом деле, вы можете написать функцию ответа on_xxx в любом месте. Затем, перед использованием, сообщите WxApplication, какую функцию вы хотите использовать для ответа на соответствующее событие. Например, в Django:

# Напишите свою собственную функцию обработки сообщений в любом месте.
# @any_decorator   # Добавьте любой декоратор.
def my_text_handler(req):
    return WxTextResponse(req.Content, req)

# Используйте это в веб-приложении следующим образом:
def wechat_view(request):
    app = WxApplication()   # Просто создайте экземпляр базового класса.
    app.handlers = {'text': my_text_handler}  # Установите свой собственный обработчик
    result = app.process(request.GET, request.body, 
        token='xxxx', app_id='xxxx', aes_key='xxxx')
    return HttpResponse(result)

Да, можно настроить обработчики сообщений, а если вы хотите настроить обработчики событий, вам нужно изменить app.event_handlers. Формат данных такой же. Конкретные ключи для типов сообщений и событий можно найти непосредственно в исходном коде.