函数
- ndb.add_flow_exception(exc)
- 指定某个异常不应被记录,而只是正常程序流的一部分。(通常情况下,如果引发异常,系统会将警告消息写入应用的日志中。)
参数
- exc
- 不应记录的异常类。
默认情况下,不会记录以下异常:
webob.exc.HTTPException
(及其子类)ndb.Rollback
- ndb.delete_multi(keys, **ctx_options)
- 删除由传递的键序列标识的实体。
参数
- ndb.delete_multi_async(keys, **ctx_options)
- 异步删除由传递的键序列标识的实体。
参数
- ndb.get_multi(keys, **ctx_options)
- 提取由传递的键序列标识的实体。
参数
- ndb.get_multi_async(keys, **ctx_options)
- 异步提取由传递的键序列标识的实体。
参数
- ndb.in_transaction()
- 返回布尔值,指出事务当前是否处于活跃状态。
- @ndb.non_transactional
@ndb.non_transactional - 使用修饰器以确保函数在事务外运行。
参数:
- allow_existing
- 如果为
True
(默认值)并且事务中的代码调用修饰函数,则该函数独立于事务运行。如果为False
并且事务中的代码调用修饰函数,则会引发异常。
- ndb.put_multi(entities, **ctx_options)
- 存储一系列 Model 实例。
参数
- ndb.put_multi_async(entities, **ctx_options)
- 异步存储一系列 Model 实例。
参数
- ndb.transaction(callback, **ctx_options)
- 在事务中运行回调。
参数
- callback
- 要调用的函数或 tasklet
- **ctx_options
- 事务选项
返回回调返回的任何结果。 抛出回调抛出的任何结果;如果事务失败,则抛出
TransactionFailedError
异常。要将参数传递给回调函数,请使用 lambda。例如,
def my_callback(key, inc): ... transaction(lambda: my_callback(Key(...), 1))
- ndb.transaction_async(callback, **ctx_options)
- 在事务中异步运行回调。
参数
- callback
- 要调用的函数或 tasklet
- **ctx_options
- 事务选项
返回
Future
。 此 future 返回回调返回的任何结果;或者抛出回调抛出的任何结果;如果事务失败,则抛出TransactionFailedError
。要将参数传递给回调函数,请使用 lambda。例如,
def my_callback(key, inc): ... transaction(lambda: my_callback(Key(...), 1))
- @ndb.transactional
@ndb.transactional - 使用修饰器使函数自动在事务中运行。
参数:
此修饰器可以包含事务选项。
上下文选项、事务选项
上下文选项允许您使用不同的配置运行特定的数据存储区操作。例如,您可能想要针对各个请求更改读取政策或 RPC 截止时间。 您几乎可以将上下文选项传递给任何操作,并可借此实现上述目的。 某些事务相关函数会采用事务选项,其中,除一组上下文选项外,还包含其他选项。
以下是使用上下文选项的几个示例。要将读取实体时的 RPC 截止时间设置为 1 秒,可以使用以下方法:
key.get(deadline=1)
要将写入实体时的 Memcache 超时设置为 30 秒,可以使用以下方法:
ent.put(ndb_memcache_timeout=30)
要删除已缓存的项目并强制重新加载该项目,可以使用以下方法:
key.delete(use_datastore=False)
特殊关键字参数 options
和 config
(由于历史原因具有相同的含义)允许将多个选项指定为 Configuration 对象。这可以是 ndb.ContextOptions
对象或(对于事务函数和装饰器)ndb.TransactionOptions
对象。
例如,key.get(options=ndb.ContextOptions(use_cache=True))
等同于 key.get(use_cache=True)
。在此类选项对象中设置的选项可能会被关键字参数所覆盖。
可以使用以下上下文选项:
选项 | 类型 | 说明 |
---|---|---|
deadline | float
| Datastore 调用截止时间,指定为几秒。 (默认情况下,只有请求处理程序截止时间会导致调用中断。) |
read_policy
| ndb.EVENTUAL_CONSISTENCY
| 如果将其设置为 ndb.EVENTUAL_CONSISTENCY ,则不会等待 Datastore 对返回的所有结果应用更改,而会更快地获得可能不是最新的结果。 |
force_writes
| bool
| 指定写入请求是否应该成功(即使当应用处于只读模式时)。 (这仅适用于用户控制的只读周期。) |
use_cache | bool | 指定是否在进程内缓存中存储实体;覆盖此操作的进程内缓存政策。 |
use_memcache | bool | 指定是否在 Memcache 中存储实体;覆盖此操作的 Memcache 政策。 |
use_datastore | bool | 指定是否在 Datastore 中存储实体;覆盖此操作的 Datastore 政策。 |
memcache_timeout | int | 实体在 Memcache 中的最长有效期;覆盖此操作的 Memcache 超时政策。 |
max_memcache_items | int
| Context Memcache 方法的自动批处理功能的最大批量大小。
例如,如果使用 max_memcache_items 的默认大小 100,则最多可将 100 个 Memcache Set 操作组合成单个 set_multi 操作。 |
对于某些事务相关函数,可以使用以下事务选项(以及上面列出的继承上下文选项): | ||
选项 | 类型 | 说明 |
xg | bool
| 允许跨组 (XG ) 事务。
默认为 False 。
|
propagation | int
| NDB 为事务内的事务(称为“嵌套事务”)提供有限支持。 propagation 参数可控制在代码尝试启动嵌套事务时发生的情况。
propagation 参数可以是以下值之一:
|
retries | int
| 事务失败时自动重试的次数。 零表示尝试一次,但不会重试。 |
在某些情况下,选项会因缓存而被忽略。
例如,如果某项读取操作能够从上下文缓存中被满足,那么当您为该读取操作指定 RPC 截止时间时,该截止时间将会被忽略。
另一方面,无法识别的选项会导致引发 TypeError
。
应用自动批处理时,系统会将具有不同选项的操作组合在一起。例如,如果您使用 put_async()
写入一些具有 deadline = 5
的实体和一些未指定截止时间的实体,并且所有实体都符合自动批处理条件,那么自动批处理程序将执行两个单独的 RPC 调用(一个调用针对具有 deadline = 5
的实体组,另一个调用针对另一个实体组),即便默认的 RPC 截止时间也是 5,仍然如此!这同样适用于指定选项与 RPC 操作不相关的情况(例如 ndb_should_cache
)。