指令碼開發 / 聯結器物件 `DFF.CONN` / Redis

Redis 聯結器操作物件主要提供 Redis 的操作方法。

DFF.CONN(...) 引數如下：

引數	型別	必須 / 預設值	說明
`connector_id`	str	必須	聯結器 ID
`database`	str	`None`	覆蓋聯結器配置的資料庫編號
`client_name`	str	`None`	設定本次連線的客戶端名稱

Redis Cluster 不支援選擇邏輯資料庫，因此叢集連線會忽略 database。

訊息訂閱

有關在聯結器中進行訊息訂閱，請參考指令碼開發 / 聯結器訂閱

`.query(...)`

直接呼叫 Redis 的 execute_command(...) 執行命令，引數如下：

引數	型別	必須 / 預設值	說明
`command`	str	必須	Redis 命令
`*args`	-	-	Redis 命令引數
`**kwargs`	-	-	傳給 redis-py 的引數

示例
db.query('SET', 'myKey', 'myValue', 'nx')
result = db.query('GET', 'myKey')
# b'myValue'

.query(...) 不轉換 redis-py 的返回值，字串結果通常為 bytes。實際操作時可以按資料格式轉換：

Python
import json

result = db.query('GET', 'intValue')
print(int(result))

result = db.query('GET', 'strValue')
print(result.decode('utf-8'))

result = db.query('GET', 'jsonValue')
print(json.loads(result.decode('utf-8')))

`.run(...)`

按 redis-py 的方法名呼叫客戶端方法，簽名為 .run(command, *args, **kwargs)。例如：

示例
result = db.run('set', 'myKey', 'myValue', nx=True)

command 是區分大小寫的 redis-py 方法名，通常使用小寫。返回值與對應 redis-py 方法一致。

常用便捷方法

聯結器提供下列便捷方法。讀取類方法會在相應實現中將 bytes 遞迴解碼為 UTF-8 字串，因此與 .query(...) 的原始返回值可能不同。

資料庫和鍵

方法	說明
`.ping()`	檢查連線
`.info()`	獲取 Redis 資訊
`.dbsize()`	獲取當前資料庫的鍵數量
`.type(key)`	獲取鍵型別；鍵不存在時返回 `None`
`.memory_usage(key, samples=0)`	獲取鍵佔用的記憶體
`.keys(pattern='*', limit=None)`	使用 `SCAN` 獲取匹配鍵，可限制返回數量
`.exists(key)`	判斷鍵是否存在，返回 `bool`
`.expire(key, expires)`	設定秒級過期時間
`.expireat(key, timestamp)`	設定絕對過期時間
`.ttl(key)` / `.pttl(key)`	獲取秒級 / 毫秒級剩餘時間
`.rename(key, new_key)`	重新命名鍵
`.renamenx(key, new_key)`	僅在新鍵不存在時重新命名
`.delete(keys)`	刪除一個鍵或鍵列表，返回刪除數量

字串和雜湊

方法	說明
`.set(key, value, expires=None, not_exists=False, exists=False, get_old_value=False)`	設定值，並可設定過期時間及 NX、XX、GET 選項
`.mset(key_values)`	批次設定字典中的鍵值
`.get(key)`	獲取並解碼單個值
`.mget(keys)`	批次獲取，返回 `{key: value}`
`.getset(key, value)`	設定新值並返回舊值
`.incr(key)` / `.incrby(key, step=1)` / `.incrbyfloat(key, step=1)`	遞增數值
`.hkeys(key, pattern='*', with_values=False)`	使用 `HSCAN` 獲取欄位；可同時返回值
`.hset(key, field=None, value=None, field_values=None)`	設定一個欄位或欄位對映
`.hmset(key, field_values)`	批次設定欄位
`.hsetnx(key, field, value)`	僅在欄位不存在時設定
`.hget(key, field)` / `.hgetall(key)`	獲取並解碼欄位值
`.hmget(key, fields)`	批次獲取，返回 `{field: value}`
`.hstrlen(key, field)` / `.hstrlenall(key)`	獲取一個或全部欄位值的位元組長度
`.hincr(key, field)` / `.hincrby(key, field, step=1)` / `.hincrbyfloat(key, field, step=1)`	遞增欄位數值
`.hdel(key, field)`	刪除一個欄位或欄位列表

列表、集合和有序集合

方法	說明
`.lpush(key, value)` / `.rpush(key, value)`	從左側 / 右側壓入一個值或值列表
`.lpop(key, count=None)` / `.rpop(key, count=None)`	從左側 / 右側彈出一個或多個值
`.blpop(key, timeout=0)` / `.brpop(key, timeout=0)`	阻塞彈出
`.rpoplpush(key, dest_key=None)`	彈出後壓入另一列表
`.brpoplpush(key, dest_key=None, timeout=0)`	阻塞執行彈出並壓入
`.llen(key)` / `.lrange(key, start=0, stop=-1)`	獲取列表長度 / 範圍
`.ltrim(key, start, stop)`	裁剪列表
`.push(...)` / `.pop(...)` / `.bpop(...)`	`.lpush(...)` / `.rpop(...)` / `.brpop(...)` 的別名
`.sadd(key, member)` / `.srem(key, member)`	新增 / 刪除一個成員或成員列表
`.scard(key)` / `.smembers(key)` / `.sismember(key, member)`	獲取集合數量、成員或判斷成員
`.zadd(key, member_scores)` / `.zrem(key, member)`	新增 / 刪除有序集合成員
`.zcard(key)`	獲取有序集合成員數
`.zrange(key, start=0, stop=-1, with_scores=False)`	按位置獲取成員
`.zrangebyscore(key, min_score='-inf', max_score='+inf', with_scores=False)`	按分數獲取成員

`.publish(...)`

向 Redis 頻道釋出訊息，返回接收到訊息的訂閱者數量。.pub(...) 是其別名。

示例
subscriber_count = db.publish('events', 'hello')

擴充套件方法

方法	說明
`.eval(lua_script, key_count, *args)`	執行 Lua 指令碼並解碼返回值
`.push_limit(key, value, limit)`	從左側壓入後將列表限制為指定長度
`.get_pattern(pattern)`	獲取匹配鍵值，返回 `{key: value}`
`.delete_pattern(pattern)`	刪除所有匹配鍵
`.hget_pattern(key, pattern)`	獲取匹配的雜湊欄位和值
`.lock(lock_key, lock_value, max_lock_time)`	使用 `SET EX NX` 獲取鎖
`.extend_lock_time(lock_key, lock_value, max_lock_time)`	校驗鎖持有者後延長過期時間
`.unlock(lock_key, lock_value)`	僅在鎖值匹配時釋放鎖

指令碼開發 / 聯結器物件 DFF.CONN / Redis