コンテンツにスキップ

キーと値のペアを書く

新しいキーと値のペアを作成するか、特定のキーの値を更新するには、あなたがWorkerコードにバインドした任意のKV名前空間のput()メソッドを呼び出します：

env.NAMESPACE.put(key, value);

例

Worker内からキーと値のペアを書く例：

export default {
  async fetch(request, env, ctx) {
    try {
      await env.NAMESPACE.put("first-key", "これはキーのための値です");


      return new Response("書き込み成功", {
        status: 201
      });
    }
    catch (e)
    {
      return new Response(e.message, {status: 500});
    }
  },
};

参考

KVに書き込むために提供されるメソッド：

put() メソッド

新しいキーと値のペアを作成するか、特定のキーの値を更新するには、あなたがWorkerコードにバインドした任意のKV名前空間のput()メソッドを呼び出します：

env.NAMESPACE.put(key, value, options?);

パラメータ

  • key: string

    • 値に関連付けるキー。キーは空であってはならず、.または..を含むことはできません。他のすべてのキーは有効です。キーの最大長は512バイトです。

  • value: string | ReadableStream | ArrayBuffer

    • 保存する値。型は推測されます。値の最大サイズは25 MiBです。

  • options: { expiration?: number, expirationTtl?: number, metadata?: object }

    • オプション。expiration（オプション）、expirationTtl（オプション）、およびmetadata（オプション）属性を含むオブジェクト。
      • expirationは、エポックからの秒数でキーと値のペアが期限切れになる時点を表す数値です。
      • expirationTtlは、現在からの秒数でキーと値のペアが期限切れになる時点を表す数値です。最小値は60です。
      • metadataはJSONにシリアライズ可能なオブジェクトです。メタデータオブジェクトのシリアライズされたJSON表現の最大サイズは1024バイトです。

レスポンス

  • response: Promise<void>
    • 更新が成功した場合に解決されるPromiseです。

put()メソッドは、成功した更新を確認するためにawaitすべきPromiseを返します。

ガイダンス

同じキーへの同時書き込み

KVの最終的に一貫性のある性質のため、同じキーへの同時書き込みは互いに上書きされる可能性があります。WranglerやAPIを使用して単一のプロセスからデータを書くことは一般的なパターンです。これにより、単一のストリームによる競合する同時書き込みを回避できます。すべてのデータは、名前空間にバインドされたすべてのWorker内で引き続き利用可能です。

同じキーに対して同時書き込みが行われた場合、最後の書き込みが優先されます。

書き込みは同じグローバルネットワーク位置内の他のリクエストに即座に表示されますが、他の地域で表示されるまでに最大60秒（またはget()またはgetWithMetadata()メソッドのcacheTtlパラメータの値）がかかる場合があります。

このトピックに関する詳細は、KVの仕組みを参照してください。

データを一括で書き込む

WranglerやAPI経由で一度に複数のキーと値のペアを書き込むことができます。

バルクAPIは、一度に最大10,000のKVペアを受け入れることができます。

各KVペアにはkeyとvalueが必要です。リクエスト全体のサイズは100メガバイト未満でなければなりません。バルク書き込みはKVバインディングを使用してはサポートされていません。

期限切れのキー

KVは自動的に期限切れになるキーを作成する機能を提供します。期限切れは、特定の時点で発生するように設定することも、キーが最後に変更されてから一定の時間が経過した後に発生するように設定することもできます。

期限切れのキーの期限が到達すると、それはシステムから削除されます。削除後、そのキーを読み取ろうとすると、キーが存在しないかのように振る舞います。削除されたキーは、請求目的のためにKV名前空間のストレージ使用量にカウントされません。

キーがいつ期限切れになるべきかを指定する方法は2つあります：

  • UNIXエポックからの秒数で指定された絶対時間を使用してキーの期限を設定します。たとえば、2019年4月1日午前12時UTCにキーが期限切れになるようにしたい場合、キーの期限を1554076800に設定します。

  • 現在の時間からの相対的な秒数を使用してキーの有効期限（TTL）を設定します。たとえば、作成後10分でキーが期限切れになるようにしたい場合、その有効期限TTLを600に設定します。

60秒未満の将来の期限切れターゲットはサポートされていません。これは両方の期限切れ方法に当てはまります。

期限切れのキーを作成する

期限切れのキーを作成するには、put()オプションのexpirationをエポックからの秒数を表す数値に設定するか、put()オプションのexpirationTtlを現在からの秒数を表す数値に設定します：

await env.NAMESPACE.put(key, value, {
  metadata: {expiration: secondsSinceEpoch},
});


await env.NAMESPACE.put(key, value, {
  metadata: {expirationTtl: secondsFromNow},
});

これらは、secondsSinceEpochとsecondsFromNowがあなたのWorkerコードの他の場所で定義された変数であることを前提としています。

メタデータ

キーと値のペアにメタデータを関連付けるには、put()オプションのmetadataをJSONにシリアライズ可能なオブジェクトに設定します：

await env.NAMESPACE.put(key, value, {
  metadata: { someMetadataKey: "someMetadataValue" },
});

KVにアクセスする他の方法

コマンドラインでWranglerを使用してキーと値のペアを書くことも、API経由でデータを書くこともできます。

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings