関数
- 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
- コンテキスト オプション
リストを返します。各リスト項目は、モデル インスタンスか
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 インスタンスを保存します。
引数
- entities
- Model インスタンスのシーケンス
- **ctx_options
- コンテキスト オプション
保存されたキーでリストを返します。
- ndb.put_multi_async(entities, **ctx_options)
- Model インスタンスのシーケンスを非同期で保存します。
引数
- entities
- Model インスタンスのシーケンス
- **ctx_options
- コンテキスト オプション
- 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 を非同期的に実行します。
引数
- 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 に設定するのは、返されたすべての結果に Datastore が変更を適用するまで待たずに、必ずしも最新ではない結果をいち早く取得する場合です。 |
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 では「ネストされたトランザクション」と呼ばれる、トランザクション内のトランザクションに対して限定的なサポートを提供しています。 伝播パラメータは、コードがネストされたトランザクションの開始を試行した場合に発生する動作を制御します。
伝播パラメータは次のいずれかの値が可能です。
|
retries | int
| トランザクションが失敗した場合に再試行を自動で何回行うかを指定します。「0」に設定すると、1 回試行した後、それ以上再試行は行いません。 |
キャッシュ保存のため、オプションが無視されることがあります。たとえば、インコンテキスト キャッシュから満たされる読み取りオペレーションの RPC 期限を指定した場合、その期限は無視されます。一方、認識できないオプションでは TypeError が生成されます。
異なるオプションを設定した演算は、自動バッチの適用時にグループ化されます。たとえば、put_async() を使用し、deadline = 5 を指定して期限を指定せずに複数のエンティティを書き込んだ場合で、かつ、すべてのエンティティが自動バッチ適用の対象である場合は、たとえデフォルトの RPC 期限も 5 であった場合でも、自動バッチャーにより 2 つの別々の RPC 呼び出し（deadline = 5 を指定したグループ エンティティ用と、別のグループ用）が作成されます。これは、指定したオプションが RPC オペレーションとは無関係である場合（ndb_should_cache など）でも、当てはまります。