コンテンツにスキップ

トランザクショナルストレージ

トランザクショナルストレージAPIを使用すると、一貫したキー-バリューのストレージを実現できます。

ダーベルオブジェクトは、ダーベルオブジェクトコンストラクタに渡される最初のパラメータであるstateを介して、永続的なトランザクショナルストレージAPIにアクセスします。

ダーベルオブジェクトインスタンスへのアクセスはシングルスレッドですが、リクエストの実行は、永続ストレージメソッドやfetch()リクエストから返されるプロミスを待っているときに、互いにインターリーブすることがあります。

以下のコードスニペットは、トランザクショナルストレージAPIを使用してデータを保存および取得する方法を示しています。

export class Counter {
  constructor(ctx, env) {
    this.ctx = ctx;
  }


  async fetch(request) {
    let url = new URL(request.url);


    // データを取得
    let value = (await this.ctx.storage.get("value")) || 0;


    // カウンターをインクリメントし、新しい値を取得
    value += 1;


    // データを保存
    await this.ctx.storage.put("value", value);


    return new Response(value);
  }
}

メソッド

トランザクショナルストレージAPIには、いくつかのメソッドがあります。

各メソッドは暗黙的にトランザクション内にラップされており、その結果は原子性があり、他のすべてのストレージ操作から隔離されています。複数のキー-バリューのペアにアクセスする場合でも同様です。

get

  • get(keystring, optionsObjectoptional) : Promise<any>

    • 指定されたキーに関連付けられた値を取得します。返される値の型は、キーに対して以前に書き込まれたものであり、キーが存在しない場合はundefinedになります。

  • get(keysArray<string>, optionsObjectoptional) : Promise<Map<string, any>>

    • 提供された各キーに関連付けられた値を取得します。Map ↗内の各返される値の型は、対応するキーに対して以前に書き込まれたものであり、存在しないキーは省略されます。最大128キーを同時にサポートします。

サポートされているオプション

  • allowConcurrencyboolean

    • デフォルトでは、ストレージ操作が進行中の間、I/Oイベントの配信がオブジェクトに対して一時停止され、予期しない競合状態を回避します。この動作をオプトアウトするには、allowConcurrency: trueを渡して、同時イベントの配信を許可します。

  • noCacheboolean

    • trueの場合、キー/バリューはメモリキャッシュに挿入されません。キーがすでにキャッシュにある場合、キャッシュされた値が返されますが、その最終使用時間は更新されません。このキーが近い将来に再度使用されないと予想される場合に使用します。このフラグはあくまでヒントです。このフラグはコードの意味を変更することはありませんが、パフォーマンスに影響を与える可能性があります。

put

  • put(keystring, valueany, optionsObjectoptional) : Promise

    • 値を保存し、指定されたキーに関連付けます。値は構造化クローンアルゴリズム ↗によってサポートされる任意の型である必要があります。キーは最大サイズ2,048バイトに制限され、値は128 KiB（131,072バイト）に制限されます。

  • put(entriesObject, optionsObjectoptional) : Promise

    • オブジェクトを受け取り、その各キーと値をストレージに保存します。
    • 各値は構造化クローンアルゴリズム ↗によってサポートされる任意の型である必要があります。
    • 最大128のキー-バリューのペアを同時にサポートします。各キーは最大サイズ2,048バイトに制限され、各値は128 KiB（131,072バイト）に制限されます。

delete

  • delete(keystring, optionsObjectoptional) : Promise<boolean>

    • キーと関連付けられた値を削除します。キーが存在した場合はtrueを返し、存在しなかった場合はfalseを返します。

  • delete(keysArray<string>, optionsObjectoptional) : Promise<number>

    • 提供されたキーとその関連付けられた値を削除します。最大128キーを同時にサポートします。削除されたキー-バリューのペアの数を返します。

deleteAll

  • deleteAll(optionsObjectoptional) : Promise

    • すべてのキーと関連付けられた値を削除し、ダーベルオブジェクトによって使用されるすべてのストレージを効果的に解放します。deleteAll()操作がまだ進行中の間に失敗した場合、データのサブセットのみが正しく削除される可能性があります。deleteAll()はアラームを積極的に削除しません。アラームを削除するにはdeleteAlarm()を使用します。

サポートされているオプション

  • put(), delete()およびdeleteAll()は、以下のオプションをサポートします：

  • allowUnconfirmedboolean

    • デフォルトでは、システムはすべての以前の書き込みがディスクにフラッシュされるまで、ダーベルオブジェクトからの送信ネットワークメッセージを一時停止します。書き込みが失敗した場合、システムはオブジェクトをリセットし、すべての送信メッセージを破棄し、クライアントにエラーで応答します。

    • このようにして、ダーベルオブジェクトは書き込み操作と並行して実行を続けることができ、書き込みを早期に確認することを心配する必要がありません。書き込みが実際に成功しない限り、外部の誰もオブジェクトのアクションを観察することはできません。

    • いずれかの書き込みの後、後続のネットワークメッセージはわずかに遅延する可能性があります。一部のアプリケーションは、未確認の書き込みに基づいて通信することを許容する場合があります。一部のプログラムは、ネットワークトラフィックを直ちに許可することを好む場合があります。この場合、デフォルトの動作をオプトアウトするためにallowUnconfirmedをtrueに設定します。

    • 一部の送信ネットワークメッセージを直ちに進行させたいが、他のメッセージはそうしたくない場合、allowUnconfirmedオプションを使用して進行させたいメッセージをブロックせずに、次にsync()メソッドを呼び出すことができます。このメソッドは、すべての以前の書き込みがディスクに正常に永続化されるまで解決されないプロミスを返します。

  • noCacheboolean

    • trueの場合、キー/バリューはディスクへの書き込みが完了するとすぐにメモリから破棄されます。

    • 近い将来に再度使用されないキーの場合はnoCacheを使用します。noCacheはコードの意味を変更することはありませんが、パフォーマンスに影響を与える可能性があります。

    • 書き込みが完了する前にget()を使用してキーを取得すると、書き込みバッファからのコピーが返され、最新のput()呼び出しとの一貫性が保証されます。

list

  • list(optionsObjectoptional) : Promise<Map<string, any>>

    • 現在のダーベルオブジェクトに関連付けられたすべてのキーと値を、キーのUTF-8エンコーディングに基づいて昇順で返します。

    • Map ↗内の各返される値の型は、対応するキーに対して以前に書き込まれたものである必要があります。

    • オプションなしでこのバージョンのlistを呼び出す前に、ダーベルオブジェクトにどれだけのデータが保存される可能性があるかを考慮してください。すべてのデータがダーベルオブジェクトのメモリにロードされ、制限に達する可能性があります。それが懸念される場合は、以下に記載されているようにlistにオプションを渡してください。

サポートされているオプション

  • startstring

    • リスト結果が開始すべきキー（含む）。

  • startAfterstring

    • リスト結果が開始すべきキー（除外）。startと同時に使用することはできません。

  • endstring

    • リスト結果が終了すべきキー（除外）。

  • prefixstring

    • 結果を、キーがプレフィックスで始まるキー-バリューのペアのみに制限します。

  • reverseboolean

    • trueの場合、結果をデフォルトの昇順ではなく降順で返します。
    • reverseを有効にしても、start、startKey、またはendKeyの意味は変わりません。startは、返される可能性のある最小のキーを定義し（含む）、実質的に逆順リストのエンドポイントとして機能します。endは、リストが考慮すべき最大のキーを定義し（除外）、実質的に逆順リストの開始点として機能します。

  • limitnumber

    • 返すキー-バリューのペアの最大数。

  • allowConcurrencyboolean

    • 上記のget()オプションと同じです。

  • noCacheboolean

    • 上記のget()オプションと同じです。

transaction

  • transaction(closureFunction(txn)) : Promise

    • txnで呼び出されたストレージ操作のシーケンスを、成功裏にコミットされるか中止される単一のトランザクションで実行します。

    • 明示的なトランザクションはもはや必要ありません。介在するawaitがない書き込み操作の一連の操作は自動的に原子性で提出され、システムは読み取り操作をawaitしている間、同時イベントの実行を防ぎます（allowConcurrency: trueを使用しない限り）。したがって、一連の読み取りの後に一連の書き込み（他のI/Oが介在しない場合）は自動的に原子性を持ち、トランザクションのように動作します。

  • txn
    • 現在のトランザクションコンテキスト内で実行するために、上記で文書化されたput()、get()、delete()およびlist()メソッドへのアクセスを提供します。トランザクションクロージャ内でトランザクショナルな動作を得るには、トップレベルのstate.storageオブジェクトではなく、txnオブジェクトでメソッドを呼び出す必要があります。

      また、トランザクション中に行われた変更がコミットされるのではなくロールバックされることを保証するrollback()関数もサポートしています。rollback()が呼び出されると、txnオブジェクトに対するその後の操作は例外で失敗します。rollback()はパラメータを取らず、呼び出し元に何も返しません。

sync

  • sync() : Promise

    • 保留中の書き込みをディスクに同期します。

    • これは、自動書き込みコアレッシングからの通常の動作に似ています。書き込みバッファに保留中の書き込みがある場合（allowUnconfirmedオプションで提出されたものを含む）、返されるプロミスはそれらが完了すると解決されます。保留中の書き込みがない場合、返されるプロミスはすでに解決されています。

getAlarm

  • getAlarm(optionsObjectoptional) : Promise<Number | null>

    • 現在のアラーム時間（設定されている場合）をエポックからのミリ秒として整数で取得します。アラームは、開始されていない場合、または失敗し、再試行が開始されていない場合に設定されていると見なされます。アラームが設定されていない場合、getAlarm()はnullを返します。

サポートされているオプション

  • get()と同じオプションですが、noCacheは含まれません。

setAlarm

  • setAlarm(scheduledTimeDate | number, optionsObjectoptional) : Promise

    • 現在のアラーム時間を設定します。JavaScriptのDateまたはエポックからのミリ秒を受け入れます。


      setAlarm()がDate.now()と等しいかそれ以前の時間で呼び出されると、アラームは即時に非同期実行のためにスケジュールされます。この場合、アラームハンドラーが現在実行中であれば、キャンセルされません。アラームはミリ秒単位で設定でき、通常は設定された時間の数ミリ秒後に実行されますが、メンテナンスやフェイルオーバー中の障害により最大1分遅れる可能性があります。

deleteAlarm

  • deleteAlarm(optionsObjectoptional) : Promise

    • アラームが存在する場合は削除します。現在実行中のアラームハンドラーはキャンセルされません。

サポートされているオプション

  • setAlarm() と deleteAlarm() は put() と同じオプションをサポートしていますが、noCache は含まれていません。

関連リソース

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings