Client 类

Memcache API 提供一个基于类的接口，以便与其他 Memcache API 兼容。另请参阅提供相同功能的函数接口。

Client 类由 google.appengine.api.memcache 模块提供。

• 简介
• Client()
• 实例方法：
  • set()
  • set_multi()
  • get()
  • get_multi()
  • delete()
  • delete_multi()
  • add()
  • add_multi()
  • replace()
  • replace_multi()
  • incr()
  • decr()
  • flush_all()
  • get_stats()
• Memcached 兼容性

简介

作为开发人员，您要通过 Memcache 客户端对象调用所有 Memcache 操作。

有些方法为 no-op，而有些方法值则会被忽略以便维持与现有常用 Python Memcache 库在源级别上的兼容性。例如，Google App Engine 透明地处理分片，但仍允许任何采用 [key] 参数的方法，接受该键作为字符串或 (哈希值, 字符串) 格式的元组。通常该哈希值用于分片为 Memcache 实例，但如果采用 App Engine，则该值将被忽略。有关详细信息，请参阅 Memcached 兼容性。

构造函数

class Client()

与 Memcache 服务通信的客户端。

实例方法

Client 实例有以下方法：

set(key, value, time=0, min_compress_len=0)

设置键的值，与先前缓存中的内容无关。

参数：

key

要设置的键。Key 可以是字符串或 (哈希值, 字符串) 格式的元组，其中哈希值（通常用于分片为 Memcache 实例）会被忽略，因为 Google App Engine 会透明地处理分片。

value

要设置的值。

time

可选的过期时间，可以是相对当前时间的秒数（最多 1 个月），也可以是绝对 Unix 时间戳时间。默认情况下，项目永不过期，虽然项目可能由于内存压力而被去除。浮点值将四舍五入为最接近的整秒。

min_compress_len

为了兼容性而忽略的选项。

如果设置的话，则返回值为 True，如果错误，则返回值为 False。

set_multi(mapping, time=0, key_prefix='', min_compress_len=0)

同时设置多个键的值。减少连续执行多个请求时的网络延迟。

参数：

mapping

键到值的参照表。

time

可选的过期时间，可以是相对当前时间的秒数（最多 1 个月），也可以是绝对 Unix 时间戳时间。默认情况下，项目永不过期，虽然项目可能由于内存压力而被去除。浮点值将四舍五入为最接近的整秒。

key_prefix

用于预置所有键的前缀。

min_compress_len

为了兼容性而忽略的选项。

返回值是未设置值的键的列表。全部成功时，该列表应为空。

get(key)

在 Memcache 中查找一个键。

参数：

key

要在 Memcache 中查找的键。Key 可以是字符串或 (哈希值, 字符串) 格式的元组，其中哈希值（通常用于分片为 Memcache 实例）会被忽略，因为 Google App Engine 会透明地处理分片。

如果在 Memcache 中找到键，则返回值为该键的值，否则为 None。

get_multi(keys, key_prefix='')

通过一个操作从 Memcache 中查找多个键。

参数：

keys

要查找的键的列表。Key 可以是字符串或 (哈希值, 字符串) 格式的元组，其中哈希值（通常用于分片为 Memcache 实例）会被忽略，因为 Google App Engine 会透明地处理分片。

key_prefix

与服务器通讯期间用于预置所有键的前缀，不包含在返回的参照表中。

返回的值是曾存在于 Memcache 中的键和值的参照表。即使指定了 key_prefix，在返回的参照表中，键也不会包含 key_prefix。

delete(key, seconds=0)

从 Memcache 删除键。

参数：

key

要删除的键。Key 可以是字符串或 (哈希值, 字符串) 格式的元组，其中哈希值（通常用于分片为 Memcache 实例）会被忽略，因为 Google App Engine 会透明地处理分片。

seconds

使删除的项目对 [添加] 操作 [锁定] 的可选秒数。值可以是从当前时间开始的增量（最多 1 个月），也可以是绝对 Unix 时间戳时间。默认值为 0，表示可以立即添加项目。无论是否有此选项，[设置] 操作都始终有效。浮点值将四舍五入为最接近的整秒。

网络故障时返回值为 0 (DELETE_NETWORK_FAILURE)，如果服务器尝试删除项目但其实并没有项目，则返回值为 1 (DELETE_ITEM_MISSING)；如果确实删除了项目，则返回值为 2 (DELETE_SUCCESSFUL)。这可以用作布尔值，其中网络故障是唯一的不良状况。

delete_multi(keys, seconds=0, key_prefix='')

同时删除多个键。

参数：

keys

要删除的键的列表。Key 可以是字符串或 (哈希值, 字符串) 格式的元组，其中哈希值（通常用于分片为 Memcache 实例）会被忽略，因为 Google App Engine 会透明地处理分片。

seconds

使删除的项目对 [添加] 操作 [锁定] 的可选秒数。值可以是从当前时间开始的增量（最多 1 个月），也可以是绝对 Unix 时间戳时间。默认值为 0，表示可以立即添加项目。无论是否有此选项，[设置] 操作都始终有效。浮点值将四舍五入为最接近的整秒。

key_prefix

当向 Memcache 发送指定的键时要添加到所有键的前缀。请参阅 get_multi() 和 set_multi() 的文档。

如果所有操作成功完成，则返回值为 True。如果一个或多个操作没有完成，则返回 False。

add(key, value, time=0, min_compress_len=0)

仅当项目尚未在 Memcache 中时，才设置键的值。

参数：

key

要设置的键。Key 可以是字符串或 (哈希值, 字符串) 格式的元组，其中哈希值（通常用于分片为 Memcache 实例）会被忽略，因为 Google App Engine 会透明地处理分片。

value

要设置的值。

time

可选的过期时间，可以是相对当前时间的秒数（最多 1 个月），也可以是绝对 Unix 时间戳时间。默认情况下，项目永不过期，虽然项目可能由于内存压力而被去除。浮点值将四舍五入为最接近的整秒。

min_compress_len

为了兼容性而忽略的选项。

如果已添加，则返回值为 True，如果错误，则返回值为 False。

add_multi(mapping, time=0, key_prefix='', min_compress_len=0)

同时添加多个值，对于已经在 Memcache 中的键没有影响。

参数：

mapping

键到值的映射。

time

可选的过期时间，可以是相对当前时间的秒数（最多 1 个月），也可以是绝对 Unix 时间戳时间。默认情况下，项目永不过期，虽然项目可能由于内存压力而被去除。浮点值将四舍五入为最接近的整秒。

key_prefix

当向 Memcache 发送指定的键时要添加到所有键的前缀。请参阅 get_multi()。

min_compress_len

为了兼容性而忽略的选项。

返回值是键的列表，这些键的值未设置，因为它们已在 Memcache 中设置；返回值也可能是空列表。

replace(key, value, time=0, min_compress_len=0)

替换键的值，如果项目尚未在 Memcache 中，则会失败。

参数：

key

要设置的键。Key 可以是字符串或 (哈希值, 字符串) 格式的元组，其中哈希值（通常用于分片为 Memcache 实例）会被忽略，因为 Google App Engine 会透明地处理分片。

value

要设置的值。

time

可选的过期时间，可以是相对当前时间的秒数（最多 1 个月），也可以是绝对 Unix 时间戳时间。默认情况下，项目永不过期，虽然项目可能由于内存压力而被去除。浮点值将四舍五入为最接近的整秒。

min_compress_len

为了兼容性而忽略的选项。

如果替换掉，则返回值为 True。如果出现错误或者缓存未命中，则返回值为 False。

replace_multi(mapping, time=0, key_prefix='', min_compress_len=0)

同时替换多个值，对于不在 Memcache 中的键没有影响。

参数：

mapping

键到值的映射。

time

可选的过期时间，可以是相对当前时间的秒数（最多 1 个月），也可以是绝对 Unix 时间戳时间。默认情况下，项目永不过期，虽然项目可能由于内存压力而被去除。浮点值将四舍五入为最接近的整秒。

key_prefix

当向 Memcache 发送指定的键时要添加到所有键的前缀。请参阅 get_multi()。

min_compress_len

为了兼容性而忽略的选项。

返回值是键的列表，这些键的值未设置，因为它们未在 Memcache 中设置；返回值也可能是空列表。

incr(key, delta=1)

自动增加键的值。在内部，值是无符号 64 位整数。Memcache 不检查 64 位溢出。值如果过大则会换行。

键必须已存在于缓存中才能增加值。要初始化计数器，请使用 set() 将其设置为初始值，如 ASCII 十进制整数。将来，在增加以后，使用 get() 获取的键将仍是 ASCII 十进制值。

参数：

key

要增加的键。Key 可以是字符串或 (哈希值, 字符串) 格式的元组，其中哈希值（通常用于分片为 Memcache 实例）会被忽略，因为 Google App Engine 会透明地处理分片。

delta

作为键的增加量的非负整数值（整型或长整型），默认为 1。

返回值为新的长整型整数值，或者是 None（如果键不在缓存中或因任何其他原因无法增加）。

decr(key, delta=1)

自动减少键的值。在内部，值是无符号 64 位整数。Memcache 不检查 64 位溢出。值如果过大则会换行。

键必须已存在于缓存中才能减少值。要初始化计数器，请使用 set() 将其设置为初始值，如 ASCII 十进制整数。将来，在减少以后，使用 get() 获取的键将仍是 ASCII 十进制值。

参数：

key

要减少的键。Key 可以是字符串或 (哈希值, 字符串) 格式的元组，其中哈希值（通常用于分片为 Memcache 实例）会被忽略，因为 Google App Engine 会透明地处理分片。

delta

作为键的减少量的非负整数值（整型或长整型），默认为 1。

返回值为新的长整型整数值，或者是 None（如果键不在缓存中或因任何其他原因无法减少）。

flush_all()

删除 Memcache 中的所有内容。

如果成功，则返回值为 True，如果是 RPC 或服务器错误，则返回值为 False。

get_stats()

获取该应用程序的 Memcache 统计信息。所有这些统计信息都可以根据不同的临时条件而重设。它们会提供在被调用时可用的最佳信息。

返回值是将统计信息名称映射到相关值的参照表。统计信息及其相关意义：

hits：导致缓存命中的缓存 get 请求的次数。

misses：导致缓存未命中的缓存 get 请求的次数。

byte_hits：get 请求时转移的总字节。溢出时转为零。

items：缓存中键/值对的数量。

bytes：缓存中所有项目的总大小。

oldest_item_age：从访问缓存中最早的项目起过了多少秒。实际上，这表示新项目在不被访问的情况下在缓存中继续有效的时间。这并不是从项目创建开始后经过的时间量。

Memcached 兼容性

Client 类包含一些方法和参数以便与 Memcached API 兼容。由于这些方法和参数中有的不适用于 App Engine Memcache 服务，所以它们不起作用。

为了兼容性而提供，但对 App Engine Memcache API 不起作用的方法包括：

• disconnect_all()
• set_servers(...)