NDB 関数

関数

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 オブジェクトのリストを返します。各フューチャーの結果は、None になります。

ndb.get_multi(keys, **ctx_options)
渡されたキー シーケンスによって識別されるエンティティを取得します。

引数

keys
キー シーケンス
**ctx_options
コンテキスト オプション

リストを返します。各リスト項目は、モデル インスタンスか None(キーが見つからない場合)です。

ndb.get_multi_async(keys, **ctx_options)
渡されたキー シーケンスによって識別されるエンティティを非同期的に取得します。

引数

keys
キー シーケンス
**ctx_options
コンテキスト オプション

Future オブジェクトのリストを返します。各フューチャーの結果はモデル インスタンスか None(キーが見つからなかった場合)です。

ndb.in_transaction()
トランザクションが現在アクティブかどうかを示すブール値を返します。
@ndb.non_transactional
@ndb.non_transactional(allow_existing=True)
関数がトランザクション外で実行されるようにするデコレータ。

引数:

allow_existing
True(デフォルト)であり、かつ、装飾関数がトランザクション内のコードで呼び出される場合、その関数はトランザクションとは独立して実行されます。False であり、かつ、装飾関数がトランザクション内のコードで呼び出される場合、例外が発生します。
ndb.put_multi(entities, **ctx_options)
モデル インスタンス シーケンスを保存します。

引数

entities
モデル インスタンス シーケンス
**ctx_options
コンテキスト オプション

保存されたキーでリストを返します。

ndb.put_multi_async(entities, **ctx_options)
モデル インスタンス シーケンスを非同期で保存します。

引数

entities
モデル インスタンス シーケンス
**ctx_options
コンテキスト オプション

Future オブジェクトのリストを返します。各フューチャーの結果は、保存されたキーです。

ndb.transaction(callback, **ctx_options)
トランザクション内でコールバックを実行します。

引数

callback
呼び出される関数/タスクレット
**ctx_options
トランザクション オプション

callback が返したものを返します。トランザクションが失敗した場合は、callback で生成された例外がそのまま生成されるか、または TransactionFailedError 例外が生成されます。

コールバック関数に引数を渡すには、ラムダを使用します。たとえば、次のとおりです:

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
ndb.transaction_async(callback, **ctx_options)
トランザクション内でコールバックを非同期的に実行します。

引数

callback
呼び出される関数/タスクレット
**ctx_options
トランザクション オプション

Future を返します。フューチャーは callback が返したものを返します。トランザクションが失敗した場合は、callback で生成された例外がそのまま生成されるか、または TransactionFailedError 例外が生成されます。

コールバック関数に引数を渡すには、ラムダを使用します。たとえば、次のとおりです:

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(時系列的な理由から同じ意味を持つ引数です)を使用すると、複数のオプションを構成オブジェクトとして指定できます。これは、ndb.ContextOptions オブジェクトまたは(トランザクション関数およびデコレータの場合は)ndb.TransactionOptions オブジェクトになります。たとえば、key.get(options=ndb.ContextOptions(use_cache=True))key.get(use_cache=True) と等価です。こうしたオプション オブジェクトに設定されたオプションは、キーワード パラメータによって上書きできます。

利用可能なコンテキスト オプションは次のとおりです。

オプション種類説明
deadline float データストア呼び出し期限です。秒数で指定します。(デフォルトでは、呼び出しはリクエスト ハンドラ期限によってのみ、中断されます。)
read_policy ndb.EVENTUAL_CONSISTENCY このオプションを ndb.EVENTUAL_CONSISTENCY に設定するのは、データストアが返されたすべての結果に変更を適用するのを待つ代わりに、必ずしも最新ではない結果をいち早く取得する場合です。
force_writes bool アプリが読み取り専用の場合でも、書き込みリクエストを続行するかどうかを指定します。(これは、ユーザー制御の読み取り専用期間にのみ適用されます。)
use_cache bool エンティティをインプロセス キャッシュに保存するかどうかを指定します。この演算のインプロセス キャッシュ ポリシーをオーバーライドします。
use_memcache bool エンティティを memcache に保存するかどうかを指定します。この演算の memcache ポリシーをオーバーライドします。
use_datastore bool エンティティをデータストアに保存するかどうかを指定します。この演算のデータストア ポリシーをオーバーライドします。
memcache_timeout int memcache 内のエンティティの最大保存期間です。この演算の memcache タイムアウト ポリシーをオーバーライドします。
max_memcache_items int Context memcache メソッドの自動バッチ機能の最大バッチサイズ。 たとえば、デフォルトのバッチサイズ max_memcache_items(100) では、最大 100 の memcache セット演算が単一の set_multi 演算に結合されます。

一部のトランザクション関連関数の場合、次のトランザクション オプションを使用できます(上記にリストされた固有のコンテキスト オプションのほかに)。

オプション種類説明
xg bool クロスグループ(XG)トランザクションを許可します。 デフォルトは、False です。
propagation int

NDB では「ネストされたトランザクション」と呼ばれる、トランザクション内のトランザクションに対して限定的なサポートを提供しています。

伝播パラメータは、コードがネストされたトランザクションの開始を試行した場合に発生する動作を制御します。

@ndb.transactional の伝播ポリシーのデフォルトは ALLOWED です。

ndb.transaction() の伝播ポリシーのデフォルトは、NESTED です。NESTED ポリシーは NDB でサポートされておらず、コードは BadRequestError 例外をスローします。その場合、NDB はサポートされていないデフォルト値を設定し、プログラマがネストされたトランザクションの制限について明確に意識できるようにします。

伝播パラメータは次のいずれかの値が可能です。

ndb.TransactionOptions.NESTED
NESTED 伝播ポリシーは、外部ポリシーがコミットしたときに外部トランザクションと内部トランザクションのすべての変更をコミットします。ただし、内部トランザクションで例外がスローされると、すべての変更が廃棄されますが、外部トランザクションはオプションによって復元され、続行することができます。NESTED ポリシーはサポートされていません。このポリシーを使用した場合は、コードで BadRequestError 例外がスローされます。
ndb.TransactionOptions.MANDATORY
常に既存のトランザクションを伝播します。既存のトランザクションがない場合は例外をスローします。このポリシーを使用する関数が例外をスローした場合、例外を取得して外部トランザクションを commit することは安全ではないことがあります。この関数によって外部トランザクションが不適切な状態に置かれている可能性があります。
ndb.TransactionOptions.ALLOWED
既存のトランザクションが存在する場合に、伝播します。このポリシーを使用する関数が例外をスローした場合、例外を取得して外部トランザクションを commit することは安全ではないことがあります。この関数によって外部トランザクションが不適切な状態に置かれている可能性があります。
ndb.TransactionOptions.INDEPENDENT
既存のトランザクションを「一時停止」して、常に新しいトランザクションを使用します。このポリシーを使用する関数では、新しいトランザクション内で読み取ったエンティティを返さないようにしてください。これは、新しいトランザクション内で読み取ったエンティティと呼び出し側のトランザクションとの間に一貫性がないためです。
retries int トランザクションが失敗した場合に再試行を自動で何回行うかを指定します。「0」に設定すると、1 回の試行の後、再試行は行いません。

場合によっては、キャッシングのために、オプションが無視されることがあります。たとえば、インコンテキスト キャッシュから満たされる読み取りオペレーションの RPC 期限を指定した場合、その期限は無視されます。一方、認識できないオプションでは TypeError が生成されます。

異なるオプションを設定した演算は、自動バッチの適用時にグループ化されます。たとえば、put_async() を使用し、deadline = 5 を指定して期限を指定せずに複数のエンティティを書き込んだ場合で、かつ、すべてのエンティティが自動バッチ適用の対象である場合は、たとえデフォルトの RPC 期限も 5 であった場合でも、自動バッチャーにより 2 つの別々の RPC 呼び出し(deadline = 5 を指定したグループ エンティティ用と、別のグループ用)が作成されます。これは、指定したオプションが RPC オペレーションとは無関係である場合(ndb_should_cache など)でも、当てはまります。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Python 2 の App Engine スタンダード環境