> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-add-new-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 永続ストレージ

> 組み込みのキーバリューデータベースを使用して、Difyプラグインで永続ストレージを実装し、インタラクション間で状態を維持する方法を学びます。

<Note> ⚠️ このドキュメントはAIによって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/develop-plugin/features-and-specs/plugin-types/persistent-storage-kv)を参照してください。</Note>

## 概要

ほとんどのプラグインツールとエンドポイントは、ステートレスな単一ラウンドのインタラクションモデルで動作します：

1. リクエストを受信
2. データを処理
3. レスポンスを返却
4. インタラクションを終了

しかし、多くの実際のアプリケーションでは、複数のインタラクション間で状態を維持する必要があります。ここで**永続ストレージ**が不可欠になります。

<Info>
  永続ストレージメカニズムにより、プラグインは同じワークスペース内でデータを永続的に保存でき、ステートフルなアプリケーションやメモリ機能を実現できます。
</Info>

Difyは現在、プラグイン用のキーバリュー（KV）ストレージシステムを提供しており、開発者のニーズに基づいて、将来的にはより柔軟で強力なストレージインターフェースを導入する予定です。

## ストレージへのアクセス

すべてのストレージ操作は、プラグインのセッションで利用可能な`storage`オブジェクトを通じて実行されます：

```python theme={null}
# Access the storage interface
storage = self.session.storage
```

## ストレージ操作

### データの保存

`set`メソッドでデータを保存します：

```python theme={null}
def set(self, key: str, val: bytes) -> None:
    """
    Store data in persistent storage
    
    Parameters:
        key: Unique identifier for your data
        val: Binary data to store (bytes)
    """
    pass
```

<Warning>
  値は`bytes`形式である必要があります。これにより、ファイルを含むさまざまな種類のデータを柔軟に保存できます。
</Warning>

#### 例：さまざまなデータ型の保存

```python theme={null}
# String data (must convert to bytes)
storage.set("user_name", "John Doe".encode('utf-8'))

# JSON data
import json
user_data = {"name": "John", "age": 30, "preferences": ["AI", "NLP"]}
storage.set("user_data", json.dumps(user_data).encode('utf-8'))

# File data
with open("image.jpg", "rb") as f:
    image_data = f.read()
    storage.set("profile_image", image_data)
```

### データの取得

`get`メソッドで保存されたデータを取得します：

```python theme={null}
def get(self, key: str) -> bytes:
    """
    Retrieve data from persistent storage
    
    Parameters:
        key: Unique identifier for your data
        
    Returns:
        The stored data as bytes, or None if key doesn't exist
    """
    pass
```

#### 例：データの取得と変換

```python theme={null}
# Retrieving string data
name_bytes = storage.get("user_name")
if name_bytes:
    name = name_bytes.decode('utf-8')
    print(f"Retrieved name: {name}")

# Retrieving JSON data
import json
user_data_bytes = storage.get("user_data")
if user_data_bytes:
    user_data = json.loads(user_data_bytes.decode('utf-8'))
    print(f"User preferences: {user_data['preferences']}")
```

### データの削除

`delete`メソッドで保存されたデータを削除します：

```python theme={null}
def delete(self, key: str) -> None:
    """
    Delete data from persistent storage
    
    Parameters:
        key: Unique identifier for the data to delete
    """
    pass
```

## ベストプラクティス

<CardGroup cols={2}>
  <Card title="説明的なキーを使用する" icon="key">
    競合を避け、コードをより保守しやすくするために、キーに一貫した命名規則を作成してください。
  </Card>

  <Card title="欠損キーを処理する" icon="triangle-exclamation">
    キーが見つからない可能性があるため、処理前にデータが存在するかどうかを常に確認してください。
  </Card>

  <Card title="複雑なデータをシリアライズする" icon="code">
    保存前に複雑なオブジェクトをJSONまたは他のシリアライズ形式に変換してください。
  </Card>

  <Card title="エラーハンドリングを実装する" icon="shield">
    潜在的なエラーを適切に処理するために、ストレージ操作をtry/exceptブロックでラップしてください。
  </Card>
</CardGroup>

## 一般的なユースケース

* **ユーザー設定**：セッション間でユーザーの設定やプリファレンスを保存
* **会話履歴**：以前の会話からのコンテキストを維持
* **APIトークン**：認証トークンを安全に保存
* **キャッシュデータ**：API呼び出しを減らすために頻繁にアクセスされるデータを保存
* **ファイルストレージ**：ユーザーがアップロードしたファイルや生成されたコンテンツを保存

***

[このページを編集する](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/features-and-specs/plugin-types/persistent-storage-kv.mdx) | [問題を報告する](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)