tamar-message-gateway 0.1.4
用于与 Tamar 消息网关交互的 Python SDK
Requires Python: >=3.8
Keywords: message gateway, tamar, websocket

# Tamar Message Gateway SDK 使用手册

本 SDK 提供了与 Tamar 消息网关交互的功能，包括发送实时消息、可靠消息和命令消息。

## 安装

```bash
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`，以确保资源能够被正确释放。

```python
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`)

用于向特定在线用户发送实时消息，不保证送达，用户不在线则消息丢失。

```python
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)。如果用户在线，会尝试实时推送；如果用户离线，消息会暂存，待用户上线后补偿推送。

```python
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`)

用于向特定用户发送命令，并可等待客户端执行后的响应。此方法会阻塞当前线程，直到收到响应或超时。

```python
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`)