Tamar Message Gateway SDK 使用手册

本 SDK 提供了与 Tamar 消息网关交互的功能，包括发送实时消息、可靠消息和命令消息。

安装

pip install tamar-message-gateway

配置

SDK 通过环境变量加载必要的配置信息。需要定义以下变量：

# Redis 配置
MSG_REDIS_USER="xxx"
MSG_REDIS_PASSWORD="xxx"
MSG_REDIS_HOST="xxx"
MSG_REDIS_DB="0"

# MySQL 配置
MSG_MYSQL_HOST="xxx"
MSG_MYSQL_USER="xxx"
MSG_MYSQL_PASSWORD="xxx"
MSG_MYSQL_DB="xxx"

# RabbitMQ 配置
MSG_RABBITMQ_HOST="xxx"
MSG_RABBITMQ_USERNAME="xxx"
MSG_RABBITMQ_PASSWORD="xxx"

基本用法

推荐使用 with 语句来初始化和使用 MessageGatewaySDK，以确保资源能够被正确释放。

from tamar_message_gateway import MessageGatewaySDK
# 确保环境变量已加载

try:
    with MessageGatewaySDK() as client:
        # 在这里调用 SDK 方法
        print("SDK 初始化成功")
        # ... 调用 client.send_... 方法 ...

except Exception as e:
    print(f"初始化或使用 SDK 时出错: {e}")

API 参考

1. 发送实时消息 (send_realtime_message)

用于向特定在线用户发送实时消息，不保证送达，用户不在线则消息丢失。

try:
    with MessageGatewaySDK() as client:
        client.send_realtime_message(
            target_user_id="user_123", 
            payload={
                "type": "test-realtime",
                "target_user_id": user_id,
                "data": {"text": "Hello, Realtime World!"},
                "timestamp": int(datetime.now().timestamp() * 1000),
                "nonce": str(uuid.uuid4()),
            }
            # payload 结构按业务场景自行约定
        )
        print("实时消息已发送")
except Exception as e:
    print(f"发送实时消息失败: {e}")

参数说明：

• target_user_id (str): 目标用户 ID

• payload (Dict[str, Any]): 要发送的消息内容，通常包含消息类型和数据，具体结构自行约定

2. 发送可靠消息 (send_reliable_message)

用于向特定用户发送消息，确保至少一次送达 (At Least Once Delivery)。如果用户在线，会尝试实时推送；如果用户离线，消息会暂存，待用户上线后补偿推送。

try:
    with MessageGatewaySDK() as client:
        message_id = client.send_reliable_message(
            target_user_id="user_123",
            payload={
                "type": "test-reliable",
                "target_user_id": user_id,
                "data": {"text": "Hello, Reliable World!"},
                "timestamp": int(datetime.now().timestamp() * 1000),
                "nonce": str(uuid.uuid4()),
            },
            sender_type="server",  # 可选，默认 server
            sender_id="backend_1"  # 可选，发送者标识
        )
        print(f"可靠消息已发送，消息 ID: {message_id}")
except Exception as e:
    print(f"发送可靠消息失败: {e}")

参数说明：

• target_user_id (str): 目标用户 ID

• payload (Dict[str, Any]): 要发送的消息内容，通常包含消息类型和数据，具体结构自行约定

• sender_type (str, 可选): 发送者的类型，可选值：server、client，默认 server

• sender_id (str, 可选): 发送者的具体标识符，建议填写服务的唯一标识

返回值：消息 ID (str)

3. 发送命令消息 (send_command_message)

用于向特定用户发送命令，并可等待客户端执行后的响应。此方法会阻塞当前线程，直到收到响应或超时。

try:
    with MessageGatewaySDK() as client:
        response = client.send_command_message(
            target_user_id="user_123",
            type="CLIENT_SERVER:CREATE_CANVAS",
            data={"text": "Hello, Command World!"},
            sender_type="server",  # 可选，默认 server
            sender_id="backend_1"  # 可选，发送者标识
            wait_for_response=True  # 可选，是否需要阻塞等待直到拿到响应或超时。默认为 True
            timeout=1800  # 可选，等待响应的超时时间（秒）。默认为 30 分钟
        )
        print(f"收到命令响应: {response}")
except Exception as e:
    print(f"发送命令消息或接收响应失败: {e}")

参数说明：

• target_user_id (str): 目标用户 ID

• type (str): 命令的类型标识符

• data (Dict[str, Any]): 命令需要携带的数据

• sender_type (str, 可选): 发送者的类型，可选值：server、client，默认 server

• sender_id (str, 可选): 发送者的具体标识符，建议填写服务的唯一标识

• wait_for_response (bool, 可选): 是否需要阻塞等待直到拿到响应或超时。默认为 True

• timeout (int, 可选): 等待响应的超时时间（秒）。默认为 30 分钟

返回值：

• 当 wait_for_response 为 True 时：客户端返回的响应数据 (Dict[str, Any])

• 当 wait_for_response 为 False 时：消息 ID (str)