NDB 函数

函数

本页面介绍如何使用旧版捆绑服务及其 API。此 API 只能在 App Engine 标准环境的第一代运行时中运行。如果要更新到 App Engine Python 3 运行时，请参阅迁移指南以了解旧版捆绑服务的迁移选项。

ndb.add_flow_exception(exc)

指定某个异常不应被记录，而只是正常程序流的一部分。（通常情况下，如果引发异常，系统会将警告消息写入应用的日志中。）

参数

exc

不应记录的异常类。

默认情况下，不会记录以下异常：

• webob.exc.HTTPException（及其子类）
• ndb.Rollback

ndb.delete_multi(keys, **ctx_options)

删除由传递的键序列标识的实体。

参数

keys

键序列

**ctx_options

上下文选项

ndb.delete_multi_async(keys, **ctx_options)

异步删除由传递的键序列标识的实体。

参数

keys

键序列

**ctx_options

上下文选项

返回 Future 对象的列表。每个 future 的结果都将是 None。

ndb.get_multi(keys, **ctx_options)

提取由传递的键序列标识的实体。

参数

keys

键序列

**ctx_options

上下文选项

返回一个列表。每个列表项要么是 Model 实例，要么是 None（如果未找到键）。

ndb.get_multi_async(keys, **ctx_options)

异步提取由传递的键序列标识的实体。

参数

keys

键序列

**ctx_options

上下文选项

返回 Future 对象的列表。每个 future 的结果要么是 Model 实例，要么是 None（如果未找到键）。

ndb.in_transaction()

返回布尔值，指出事务当前是否处于活跃状态。

@ndb.non_transactional
@ndb.non_transactional(allow_existing=True)

使用修饰器以确保函数在事务外运行。

参数：

allow_existing

如果为 True（默认值）并且事务中的代码调用修饰函数，则该函数独立于事务运行。如果为 False 并且事务中的代码调用修饰函数，则会引发异常。

ndb.put_multi(entities, **ctx_options)

存储一系列 Model 实例。

参数

实体

Model 实例序列

**ctx_options

上下文选项

返回包含已存储的键的列表。

ndb.put_multi_async(entities, **ctx_options)

异步存储一系列 Model 实例。

参数

实体

Model 实例序列

**ctx_options

上下文选项

返回 Future 对象的列表。每个 future 的结果都将是存储的键。

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(**ctx_options)

使用修饰器使函数自动在事务中运行。

参数：

此修饰器可以包含事务选项。

上下文选项、事务选项

上下文选项允许您使用不同的配置运行特定的数据存储区操作。例如，您可能想要针对各个请求更改读取政策或 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 参数可控制在代码尝试启动嵌套事务时发生的情况。 @ndb.transactional 的传播政策默认为 ALLOWED。 ndb.transaction() 的传播政策默认为 NESTED。 NDB 不支持 NESTED 政策，因此代码将抛出 BadRequestError 异常。在本例中，NDB 设置了不受支持的默认值，以便程序员明确了解嵌套事务的限制。 propagation 参数可以是以下值之一： ndb.TransactionOptions.NESTED 提交外部政策时，NESTED 传播政策将提交外部和内部事务中的所有更改。不过，如果在内部事务中抛出异常，那么所有更改都将被抛出，但允许选择性地恢复并继续外部事务。不支持 NESTED 政策。如果您使用此政策，您的代码将抛出 BadRequestError 异常。 ndb.TransactionOptions.MANDATORY 始终传播现有事务；如果没有现有事务，则抛出异常。如果使用此政策的函数抛出异常，则捕获异常并提交外部事务可能不安全；该函数可能会使外部事务处于错误状态。 ndb.TransactionOptions.ALLOWED 如果存在现有事务，则传播该事务。 如果使用此政策的函数抛出异常，则捕获异常并提交外部事务可能不安全；该函数可能会使外部事务处于错误状态。 ndb.TransactionOptions.INDEPENDENT 始终使用新事务，“暂停”所有现有事务。 使用此政策的函数不应返回在新事务中读取的任何实体，因为这些实体在事务方面与调用者的事务不一致。
retries	int	事务失败时自动重试的次数。 零表示尝试一次，但不会重试。

在某些情况下，选项会因缓存而被忽略。 例如，如果某项读取操作能够从上下文缓存中被满足，那么当您为该读取操作指定 RPC 截止时间时，该截止时间将会被忽略。 另一方面，无法识别的选项会导致引发 TypeError。

应用自动批处理时，系统会将具有不同选项的操作组合在一起。例如，如果您使用 put_async() 写入一些具有 deadline = 5 的实体和一些未指定截止时间的实体，并且所有实体都符合自动批处理条件，那么自动批处理程序将执行两个单独的 RPC 调用（一个调用针对具有 deadline = 5 的实体组，另一个调用针对另一个实体组），即便默认的 RPC 截止时间也是 5，仍然如此！这同样适用于指定选项与 RPC 操作不相关的情况（例如 ndb_should_cache）。