# Ruby SDK

<figure><img src="/files/XAokBMJxqCFiOHcYj3QE" alt=""><figcaption></figcaption></figure>

## ダウンロードとインストール

### インストール

Ruby SDKでは、Ruby 3.1以降がサポートされています。詳細については[こちらのウェブサイト](https://rubygems.org/gems/keeper_secrets_manager)をご参照ください。

#### gemを使用してインストールする場合

```
gem install keeper_secrets_manager -v 17.1.0
```

#### Gemfileに追加する場合

```bash
gem 'keeper_secrets_manager', '~> 17.1'
```

次に以下を実行します。

```
bundle install
```

### ソースコード

Rubyのソースコードは[GitHubリポジトリ](https://github.com/Keeper-Security/secrets-manager/tree/master/sdk/ruby)で公開されています。

## SDKの使用

### ストレージの初期化

KeeperシークレットマネージャーSDKでは、クライアントデバイス上にストレージを初期化するためにワンタイムアクセストークンが必要です。初期化後は、SDKが構成を保存し、以降の利用時に再読み込みします。

{% code overflow="wrap" %}

```ruby
KeeperSecretsManager.new(token: token, config: storage, hostname: hostname, verify_ssl_certs: verify_ssl_certs)
```

{% endcode %}

| パラメータ              | 型                 | 必須 | デフォルト                  | 説明                                             |
| ------------------ | ----------------- | -- | ---------------------- | ---------------------------------------------- |
| `token`            | `String`          | 任意 | `nil`                  | 初期バインディングに使用するワンタイムアクセストークン                    |
| `config`           | `KeyValueStorage` | 必須 | なし                     | 構成を永続化するためのストレージ実装                             |
| `hostname`         | `String`          | 任意 | `'keepersecurity.com'` | APIホスト名 (例: EUデータセンターの場合は 'keepersecurity.eu') |
| `verify_ssl_certs` | `Boolean`         | 任意 | `true`                 | SSL証明書検証の有効/無効の設定                              |

{% hint style="info" %}
ワンタイムアクセストークンを使用する場合、トークンを紐付けて構成を完全に取得するために**最低1つの読み取り操作**が必要です。
{% endhint %}

### 使用例

#### ワンタイムアクセストークンを使用する場合

```ruby
require 'keeper_secrets_manager'

token = "US:ONE_TIME_TOKEN_HERE"

# 初回セットアップ - トークンの紐付け
storage = KeeperSecretsManager::Storage::FileStorage.new('keeper_config.json')
secrets_manager = KeeperSecretsManager.new(token: token, config: storage)

# 少なくとも1回の操作が必要（構成の取得）
records = secrets_manager.get_secrets

# 構成ファイルが保存されたことを確認
File.exist?('keeper_config.json')  # true を返す
```

#### ファイルベースのストレージを使用する場合

アプリケーション再起動後も構成を永続的に保持する場合

```ruby
require 'keeper_secrets_manager'

# 初回の紐付け後、構成ファイルから読み込む
secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')
```

ボルトで生成されたBase64構成ファイルを使用する場合

```ruby
require 'keeper_secrets_manager'

base64_config = File.read('config.base64').strip
storage = KeeperSecretsManager::Storage::InMemoryStorage.new(base64_config)
secrets_manager = KeeperSecretsManager.new(config: storage)
```

#### 環境変数を使用する場合

環境変数から読み取り専用の構成をロードする方法

```ruby
require 'keeper_secrets_manager'

# 事前に環境変数を設定:
# export KSM_HOSTNAME=keepersecurity.com
# export KSM_CLIENT_ID=your-client-id
# export KSM_PRIVATE_KEY=your-private-key
# export KSM_APP_KEY=your-app-key
# export KSM_SERVER_PUBLIC_KEY_ID=10

# 環境変数から構成をロード
config = KeeperSecretsManager::Storage::EnvironmentStorage.new('KSM_')
secrets_manager = KeeperSecretsManager.new(config: config)
```

## シークレットの取得

### シークレットの取得

```ruby
get_secrets(uids = [])
```

| パラメータ  | 型               | 必須 | デフォルト | 説明                                      |
| ------ | --------------- | -- | ----- | --------------------------------------- |
| `uids` | `Array<String>` | 任意 | `[]`  | 取得対象のレコードUID一覧。空配列の場合はすべてのシークレットを取得します。 |

### レスポンス

**型:** `Array<KeeperRecord>`

すべてのKeeperレコード、または指定したUIDに一致するレコードの配列が返されます。

### 使用例

すべてのシークレットを取得する

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# すべてのシークレットを取得
records = secrets_manager.get_secrets

records.each do |record|
  puts "#{record.title} (#{record.type})"
end
```

UIDを指定して取得する

```ruby
# 単一レコードをUIDで取得
records = secrets_manager.get_secrets(['RECORD_UID'])
record = records.first

# 複数UIDを指定して取得
uids = ['UID1', 'UID2', 'UID3']
records = secrets_manager.get_secrets(uids)
```

#### タイトルでシークレットを取得する

```ruby
# タイトルに一致するすべてのシークレットを取得
get_secrets_by_title(title)

# タイトルに一致する最初のシークレットを取得
get_secret_by_title(title)
```

| パラメータ   | 型        | 必須 | デフォルト | 説明                   |
| ------- | -------- | -- | ----- | -------------------- |
| `title` | `String` | 必須 | なし    | 検索対象のレコードタイトル (完全一致) |

#### レスポンス

* `get_secrets_by_title` → `Array<KeeperRecord>`
* `get_secret_by_title` → `KeeperRecord`

同じタイトルに一致するすべてのレコード、または最初に一致したレコードを返します。

#### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# タイトルが完全一致するシークレットを1件取得
record = secrets_manager.get_secret_by_title('My Database Credentials')

# 同じタイトルを持つ複数レコードを取得
records = secrets_manager.get_secrets_by_title('My Login')

# レコードからフィールドにアクセス
puts "Login: #{record.login}"
puts "Password: #{record.password}"
```

## シークレットから値を取得する

シークレットを取得した後、フィールド値には複数の方法でアクセスできます。

#### 動的フィールドアクセスを使用する方法

```ruby
record = secrets_manager.get_secrets(['RECORD_UID']).first

# 標準フィールドに動的にアクセス
login = record.login
password = record.password
url = record.url

# 複合フィールドにアクセス
host = record.host  # hostName と port を含むハッシュが返る
```

#### 明示的なフィールドメソッドを使用する方法

```ruby
# 単一値の取得（最初の値を返す）
login = record.get_field_value_single('login')

# 複数値の取得（配列を返す）
passwords = record.get_field_value('password')

# ラベル付きカスタムフィールドへのアクセス
api_key = record.get_field_value_single('API Key')
environment = record.get_field_value_single('Environment')
```

#### Keeper表記法を使用する方法

```ruby
# URI形式のNotationを使ってフィールドにアクセス
password = secrets_manager.get_notation("keeper://#{record.uid}/field/password")

# レコードタイトルを使ってアクセス
url = secrets_manager.get_notation("keeper://My Login/field/url")

# 複合フィールドのプロパティにアクセス
hostname = secrets_manager.get_notation("keeper://#{record.uid}/field/host[hostName]")
port = secrets_manager.get_notation("keeper://#{record.uid}/field/host[port]")

# カスタムフィールドへアクセス
env = secrets_manager.get_notation("keeper://#{record.uid}/custom_field/Environment")
```

## TOTPコードの取得

TOTPコードを生成するには、まずレコードからTOTP URLを取得し、`KeeperSecretsManager::TOTP` モジュールを使用します。

```ruby
# レコードからTOTP URLを取得
totp_url = record.get_field_value_single('oneTimeCode')

# パースしてコードを生成
require 'keeper_secrets_manager/totp'
totp_params = KeeperSecretsManager::TOTP.parse_url(totp_url)
totp_code = KeeperSecretsManager::TOTP.generate_code(
  totp_params['secret'],
  algorithm: totp_params['algorithm'],
  digits: totp_params['digits'],
  period: totp_params['period']
)
```

| パラメータ       | 型         | 必須 | デフォルト    | 説明                                       |
| ----------- | --------- | -- | -------- | ---------------------------------------- |
| `secret`    | `String`  | 必須 | なし       | Base32形式でエンコードされたTOTPシークレット              |
| `algorithm` | `String`  | 任意 | `'SHA1'` | 使用するハッシュアルゴリズム 　(SHA1 / SHA256 / SHA512) |
| `digits`    | `Integer` | 任意 | `6`      | 生成するコードの桁数                               |
| `period`    | `Integer` | 任意 | `30`     | コードの有効期間 (秒)                             |

#### レスポンス

**型:** `String`

2要素認証に使用する現在のTOTP (Time-Based One-Time Password) コードが返されます。

#### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# TOTPを含むレコードを取得
record = secrets_manager.get_secrets(['RECORD_UID']).first

# レコードからTOTP URLを取得
totp_url = record.get_field_value_single('oneTimeCode')

# TOTPパラメータをパース
require 'keeper_secrets_manager/totp'
totp_params = KeeperSecretsManager::TOTP.parse_url(totp_url)

# TOTPコードを生成
totp_code = KeeperSecretsManager::TOTP.generate_code(
  totp_params['secret'],
  algorithm: totp_params['algorithm'],
  digits: totp_params['digits'],
  period: totp_params['period']
)

puts "Current TOTP code: #{totp_code}"
puts "Expires in: #{30 - (Time.now.to_i % 30)} seconds"
```

{% hint style="info" %}
TOTPコードの生成には、Base32デコード用の **base32** gem が必要です。
{% endhint %}

インストール方法

```
gem install base32
```

## ランダムパスワードの生成

暗号学的に安全なランダムパスワードを生成できます。文字種や長さなどを柔軟に指定でき、シークレットをプログラムから作成または更新する際に便利です。

```ruby
KeeperSecretsManager::Utils.generate_password(
  length: 64,
  lowercase: 0,
  uppercase: 0,
  digits: 0,
  special_characters: 0
)
```

| パラメータ                | 型         | 必須 | デフォルト | 説明                                     |
| -------------------- | --------- | -- | ----- | -------------------------------------- |
| `length`             | `Integer` | 任意 | `64`  | パスワード全体の長さ                             |
| `lowercase`          | `Integer` | 任意 | `0`   | 使用する小文字　(a–z) の最小数                     |
| `uppercase`          | `Integer` | 任意 | `0`   | 使用する大文字 (A–Z) の最小数                     |
| `digits`             | `Integer` | 任意 | `0`   | 使用する数字 (0–9) の最小数                      |
| `special_characters` | `Integer` | 任意 | `0`   | 使用する記号 (!@#$%^&\*()\_+-=\[]{} など) の最小数 |

#### レスポンス

**型:** `String`

指定した要件を満たす、暗号学的に安全なランダムパスワードを返します。

{% hint style="info" %}
この関数は、暗号学的に安全な乱数生成を行うRubyの `SecureRandom` を使用しており、適切な文字分布を確保するためにFisher–Yatesシャッフルを適用します。
{% endhint %}

### 使用例

#### デフォルト設定で64文字のパスワードを生成

```ruby
require 'keeper_secrets_manager'

# すべてデフォルト値で生成（64文字のランダムパスワード）
password = KeeperSecretsManager::Utils.generate_password
puts "Generated: #{password}"
# => "Xk9$mP2..."  (64 characters)
```

#### 生成要件を指定する例

```ruby
# 32文字で、各文字種の最低数を指定
password = KeeperSecretsManager::Utils.generate_password(
  length: 32,
  lowercase: 2,
  uppercase: 2,
  digits: 2,
  special_characters: 2
)

puts "Generated: #{password}"
# => "aB12$xY34..."  (32文字、各文字種を最低2つずつ含む)

# 様々な要件で強度の高いパスワードを生成
password = KeeperSecretsManager::Utils.generate_password(
  length: 20,
  lowercase: 3,
  uppercase: 3,
  digits: 3,
  special_characters: 3
)
```

#### 新しいシークレットを作成する際に使用する例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# 生成したパスワードを使って新しいログインレコードを作成
record_data = {
  type: 'login',
  title: 'Production Database',
  fields: [
    { type: 'login', value: ['db_admin'] },
    {
      type: 'password',
      value: [KeeperSecretsManager::Utils.generate_password(
        length: 32,
        lowercase: 4,
        uppercase: 4,
        digits: 4,
        special_characters: 4
      )]
    },
    { type: 'url', value: ['https://db.example.com'] }
  ],
  notes: 'Auto-generated secure password'
}

# 必須のフォルダUIDを指定
options = KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')
record_uid = secrets_manager.create_secret(record_data, options)

puts "Created record with secure password: #{record_uid}"
```

#### 既存のシークレットを更新する際に使用する例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# 既存レコードを取得
record = secrets_manager.get_secrets(['RECORD_UID']).first

# 新しいパスワードを生成して設定
new_password = KeeperSecretsManager::Utils.generate_password(
  length: 40,
  lowercase: 5,
  uppercase: 5,
  digits: 5,
  special_characters: 5
)

record.password = new_password

# 変更を保存
secrets_manager.update_secret(record)

puts "Password updated with new secure value"
```

#### パスワードローテーションスクリプト例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# 複数レコードのパスワードをローテーション
record_uids = ['UID1', 'UID2', 'UID3']

record_uids.each do |uid|
  record = secrets_manager.get_secrets([uid]).first

  # 新しいパスワードを生成
  new_password = KeeperSecretsManager::Utils.generate_password(
    length: 32,
    lowercase: 3,
    uppercase: 3,
    digits: 3,
    special_characters: 3
  )

  # レコードを更新
  record.password = new_password
  record.notes = "Password rotated on #{Time.now}"

  secrets_manager.update_secret(record)

  puts "✓ Rotated password for: #{record.title}"
end
```

## シークレットの更新

```
update_secret(record)
```

| パラメータ    | 型              | 必須 | デフォルト | 説明                  |
| -------- | -------------- | -- | ----- | ------------------- |
| `record` | `KeeperRecord` | はい | なし    | ボルト内で更新する、変更済みのレコード |

### レスポンス

**型:** `void`

変更された値を使って、ボルト内のシークレットが更新されます。

### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# 既存レコードを取得
record = secrets_manager.get_secrets(['RECORD_UID']).first

# 動的アクセスでフィールドを更新
record.password = 'NewSecurePassword123!'

# 明示的メソッドでフィールドを更新
record.set_field('login', 'new_username@example.com')

# ノートを更新
record.notes = "Updated on #{Time.now}"

# 変更を保存
secrets_manager.update_secret(record)

puts "Secret updated successfully"
```

## ファイルのダウンロード

```
download_file(file)
```

| パラメータ  | 型            | 必須 | デフォルト | 説明                                  |
| ------ | ------------ | -- | ----- | ----------------------------------- |
| `file` | `KeeperFile` | 必須 | なし    | ダウンロード対象となるKeeperRecord内のファイルオブジェクト |

### レスポンス

**型:** `Hash`

以下の情報を含むハッシュを返します。

* `'name'` — ファイル名
* `'data'` — バイナリ文字列としてのファイルデータ
* `'size'` — ファイルサイズ（バイト単位）
* `'type'` — ファイルのMIMEタイプ

### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# ファイルを含むレコードを取得
record = secrets_manager.get_secrets(['RECORD_UID']).first

# レコードにファイルがあるか確認
if record.files && record.files.any?
  # 最初のファイルをダウンロード
  file = record.files.first
  downloaded = secrets_manager.download_file(file)

  # ディスクに保存
  filename = downloaded['name'] || 'downloaded_file'
  File.write(filename, downloaded['data'])

  puts "Downloaded: #{filename}"
  puts "Size: #{downloaded['size']} bytes"
  puts "Type: #{downloaded['type']}"
end
```

## ファイルのアップロード

```ruby
upload_file(owner_record_uid, file_data, file_name, file_title = nil)
```

| パラメータ              | 型        | 必須 | デフォルト | 説明                    |
| ------------------ | -------- | -- | ----- | --------------------- |
| `owner_record_uid` | `String` | 必須 | なし    | ファイルを添付する対象レコードのUID   |
| `file_data`        | `String` | 必須 | なし    | ファイル内容 (バイナリまたはテキスト)  |
| `file_name`        | `String` | 必須 | なし    | Keeper上でのファイル名        |
| `file_title`       | `String` | 任意 | nil   | Keeper上でのファイルのタイトル/説明 |

### レスポンス

**型:** `String`

アップロードされたファイルのUIDを返します。

### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# ファイルをアップロード
file_uid = secrets_manager.upload_file(
  'RECORD_UID',                          # owner_record_uid
  File.read('/path/to/certificate.pem'), # file_data
  'certificate.pem',                     # file_name
  'Server Certificate'                   # file_title (任意)
)

puts "File uploaded with UID: #{file_uid}"

# テキストデータをアップロード
file_uid = secrets_manager.upload_file(
  'RECORD_UID',
  "server=localhost\nport=5432\n",
  'config.txt',
  'Database Config'
)
```

## シークレットの作成

```ruby
create_secret(record_data, options = nil)
```

| パラメータ         | 型               | 必須 | デフォルト | 説明                                              |
| ------------- | --------------- | -- | ----- | ----------------------------------------------- |
| `record_data` | `Hash`          | 必須 | なし    | レコード構造 (type、title、fields、custom、notes) を含むハッシュ |
| `options`     | `CreateOptions` | 必須 | なし    | folder\_uid (必須) と任意設定を含むCreateOptionsオブジェクト    |

### レスポンス

**型:** `String`

作成されたシークレットのUIDを返します。

### 要件

* 共有フォルダUID (folder\_uid) を指定する場合、そのUIDが必要
* 共有フォルダがシークレットマネージャーアプリケーションからアクセス可能であること
* あなた自身とシークレットマネージャーアプリケーションの両方に編集権限があること
* 共有フォルダ内に少なくとも1件のレコードが存在すること
* レコードのフィールド形式が正しく構成されていること (フィールドタイプの仕様を参照)

### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# ログインレコードを新規作成
record_data = {
  type: 'login',
  title: 'Production Database',
  fields: [
    { type: 'login', value: ['db_admin'] },
    { type: 'password', value: ['SecurePassword123!'] },
    { type: 'url', value: ['https://db.example.com'] },
    {
      type: 'host',
      value: [{ hostName: '192.168.1.100', port: '5432' }],
      label: 'Database Host'
    }
  ],
  custom: [
    { type: 'text', label: 'Environment', value: ['Production'] },
    { type: 'text', label: 'Database Name', value: ['main_db'] }
  ],
  notes: 'Production database credentials'
}

# 必須のfolder_uidを指定してオプションを作成
options = KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')

# シークレットを作成
record_uid = secrets_manager.create_secret(record_data, options)

puts "Secret created with UID: #{record_uid}"

# 別の記述方法（オプションをインラインで渡す）
record_uid = secrets_manager.create_secret(
  record_data,
  KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')
)
```

#### カスタムタイプレコードの作成例

```ruby
# データベース認証情報レコードを作成
record_data = {
  type: 'databaseCredentials',
  title: 'MySQL Production',
  fields: [
    { type: 'text', label: 'Database Type', value: ['MySQL'] },
    {
      type: 'host',
      value: [{ hostName: 'mysql.example.com', port: '3306' }]
    },
    { type: 'login', value: ['root'] },
    { type: 'password', value: ['SecurePassword123!'] }
  ],
  notes: 'MySQL production database'
}

# 必須のfolder_uidを指定してオプションを作成
options = KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')
record_uid = secrets_manager.create_secret(record_data, options)
```

## シークレットの削除

```ruby
delete_secret(uids)
```

| パラメータ  | 型                            | 必須 | デフォルト | 説明                   |
| ------ | ---------------------------- | -- | ----- | -------------------- |
| `uids` | `String` または `Array<String>` | 必須 | なし    | 削除対象のレコードUID (複数指定可) |

### レスポンス

**型**: `void`

指定したシークレットをボルトから削除します。

### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# 単一のシークレットを削除
secrets_manager.delete_secret('RECORD_UID')
puts "Secret deleted successfully"

# 複数のシークレットを削除
uids = ['UID1', 'UID2', 'UID3']
secrets_manager.delete_secret(uids)
puts "#{uids.length} secrets deleted"
```

## フォルダ

Ruby SDKでは、フォルダ操作に対して完全なCRUD (作成・取得・更新・削除) が利用できます。

## フォルダの取得

```ruby
get_folders
```

### レスポンス

**型**: `Array<KeeperFolder>`

シークレットマネージャーアプリケーションがアクセス可能なすべてのフォルダを返します。

### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# すべてのフォルダを取得
folders = secrets_manager.get_folders

folders.each do |folder|
  puts "#{folder.name} (UID: #{folder.uid})"
end
```

## フォルダパスの取得

```
get_folder_path(folder_uid)
```

| パラメータ        | 型        | 必須 | デフォルト | 説明                |
| ------------ | -------- | -- | ----- | ----------------- |
| `folder_uid` | `String` | 必須 | なし    | パスを取得する対象フォルダのUID |

### レスポンス

型: `String`

フォルダの完全なパス（"/" 区切りのパンくずリスト形式）を返します。

### 使用例

```ruby
# フォルダのパス（パンくずリスト形式）を取得
path = secrets_manager.get_folder_path('FOLDER_UID')
puts "Folder path: #{path}"  # "Parent/Child/Grandchild"（例: 親/子/孫フォルダのパス）
```

## 名前でフォルダを検索

```ruby
find_folder_by_name(name, parent_uid: nil)
```

| パラメータ        | 型        | 必須 | デフォルト | 説明                      |
| ------------ | -------- | -- | ----- | ----------------------- |
| `name`       | `String` | 必須 | なし    | 検索するフォルダ名               |
| `parent_uid` | `String` | 任意 | `nil` | 指定した親フォルダ内を対象に検索する場合に指定 |

### レスポンス

**型**: `KeeperFolder` または `nil`

最初に一致したフォルダ、または一致しない場合は nil を返します。

### 使用例

```ruby
# 名前でフォルダを検索
folder = secrets_manager.find_folder_by_name('Finance')

# 特定の親フォルダ内でフォルダを検索
folder = secrets_manager.find_folder_by_name('Reports', parent_uid: 'PARENT_UID')
```

### フォルダツリーの構築

```ruby
# フォルダマネージャーの取得
fm = secrets_manager.folder_manager

# フォルダツリー全体を構築
tree = fm.build_folder_tree

# ツリー構造をコンソールに出力
fm.print_tree

# フォルダ関係を取得
ancestors = fm.get_ancestors('FOLDER_UID')      # [parent, grandparent, ...]
descendants = fm.get_descendants('FOLDER_UID')  # [children, grandchildren, ...]
```

## フォルダの作成

```
create_folder(name, parent_uid:)
```

| パラメータ       | 型      | 必須 | デフォルト | 説明                 |
| ----------- | ------ | -- | ----- | ------------------ |
| name        | String | 必須 | -     | 作成するフォルダ名          |
| parent\_uid | String | 必須 | -     | フォルダを配置する親フォルダのUID |

### レスポンス

**型:** `String`

作成されたフォルダのUIDを返します。

### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# ルート階層（共有フォルダ内）にフォルダを作成
folder_uid = secrets_manager.create_folder('New Folder', parent_uid: 'SHARED_FOLDER_UID')

puts "Folder created with UID: #{folder_uid}"

# 既存フォルダの下にサブフォルダを作成
subfolder_uid = secrets_manager.create_folder(
  'Subfolder',
  parent_uid: folder_uid
)

puts "Subfolder created: #{subfolder_uid}"
```

## フォルダの更新

```
update_folder(folder_uid, new_name)
```

| パラメータ       | 型      | 必須 | デフォルト | 説明                |
| ----------- | ------ | -- | ----- | ----------------- |
| folder\_uid | String | はい | -     | 名前を変更する対象フォルダのUID |
| new\_name   | String | はい | -     | 新しいフォルダ名          |

### レスポンス

**型:** `void`

指定したフォルダの名前を変更します。

#### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# フォルダ名を変更
secrets_manager.update_folder('FOLDER_UID', 'New Folder Name')

puts "Folder renamed successfully"
```

## フォルダの削除

```ruby
delete_folder(folder_uid, force: false)
```

| パラメータ        | 型         | 必須 | デフォルト   | 説明                       |
| ------------ | --------- | -- | ------- | ------------------------ |
| `folder_uid` | `String`  | はい | -       | 削除対象のフォルダUID             |
| `force`      | `Boolean` | 任意 | `false` | true の場合、フォルダ内の内容物もすべて削除 |

### レスポンス

**型:** `void`

指定したフォルダをボルトから削除します。

### 使用例

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')

# 空のフォルダを削除
secrets_manager.delete_folder('FOLDER_UID')

# フォルダを強制削除（内容物もすべて削除）
secrets_manager.delete_folder('FOLDER_UID', force: true)

puts "Folder deleted"

# 複数フォルダを削除
folder_uids = ['UID1', 'UID2', 'UID3']
folder_uids.each do |uid|
  secrets_manager.delete_folder(uid, force: true)
end
```

## キャッシュ

シークレットをローカルにキャッシュすることで、パフォーマンスを向上できます。

#### CachingStorageの使用

```ruby
require 'keeper_secrets_manager'

# 基本ストレージを作成
base_storage = KeeperSecretsManager::Storage::FileStorage.new('keeper_config.json')

# キャッシュでラップ（TTLは600秒）
cached_storage = KeeperSecretsManager::Storage::CachingStorage.new(base_storage, 600)

# キャッシュ対応ストレージを使用して初期化
secrets_manager = KeeperSecretsManager.new(config: cached_storage)

# 最初の呼び出しではサーバーから取得
records = secrets_manager.get_secrets

# TTL内の呼び出しではキャッシュを使用
records = secrets_manager.get_secrets  # キャッシュされたデータを使用
```

## 高度な構成

#### カスタムホスト名

```ruby
require 'keeper_secrets_manager'

# 欧州データセンター
secrets_manager = KeeperSecretsManager.new(
  token: 'EU:ONE_TIME_TOKEN',
  hostname: 'keepersecurity.eu',
  config: storage
)

# 豪州データセンター
secrets_manager = KeeperSecretsManager.new(
  token: 'AU:ONE_TIME_TOKEN',
  hostname: 'keepersecurity.com.au',
  config: storage
)
```

#### SSL証明書検証

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.new(
  config: storage,
  verify_ssl_certs: true  # 既定値は true
)
```

#### カスタムロギング

```ruby
require 'keeper_secrets_manager'
require 'logger'

# カスタムロガーを作成
logger = Logger.new(STDOUT)
logger.level = Logger::DEBUG

secrets_manager = KeeperSecretsManager.new(
  config: storage,
  logger: logger,
  log_level: Logger::DEBUG
)
```

#### すべての構成オプション

```ruby
require 'keeper_secrets_manager'

secrets_manager = KeeperSecretsManager.new(
  token: 'US:ONE_TIME_TOKEN',           # ワンタイムアクセストークン
  config: storage,                      # 構成ストレージ
  hostname: 'keepersecurity.com',       # APIホスト名
  verify_ssl_certs: true,               # SSL検証
  logger: Logger.new(STDOUT),           # カスタムロガー
  log_level: Logger::WARN,              # ログレベル
  custom_post_function: my_post_func    # カスタムHTTPハンドラー
)
```

## フィールドタイプヘルパー

タイプ付きフィールドを簡単に作成するための便利な方法が用意されています。

```ruby
require 'keeper_secrets_manager'

# フィールド作成にヘルパーを使用
fields = [
  KeeperSecretsManager::FieldTypes::Helpers.login('admin'),
  KeeperSecretsManager::FieldTypes::Helpers.password('SecurePass123!'),
  KeeperSecretsManager::FieldTypes::Helpers.url('https://example.com'),
  KeeperSecretsManager::FieldTypes::Helpers.host(
    hostname: '192.168.1.100',
    port: 22
  ),
  KeeperSecretsManager::FieldTypes::Helpers.name(
    first: 'John',
    middle: 'Q',
    last: 'Doe'
  ),
  KeeperSecretsManager::FieldTypes::Helpers.address(
    street1: '123 Main St',
    city: 'New York',
    state: 'NY',
    zip: '10001'
  )
]

# レコード作成用にハッシュへ変換
record_data = {
  type: 'login',
  title: 'Server with Helpers',
  fields: fields.map(&:to_h)
}

# 必須の folder_uid を指定して作成オプションを作成
options = KeeperSecretsManager::Dto::CreateOptions.new(folder_uid: 'FOLDER_UID')
record_uid = secrets_manager.create_secret(record_data, options)
```

## ダイナミックレコードアクセス

Ruby SDKでは、`method_missing` を利用して JavaScript のような動的フィールドアクセスを実現しています。

```ruby
# レコードを取得
record = secrets_manager.get_secrets(['RECORD_UID']).first

# 動的ゲッター
login = record.login          # フィールド値を返す
password = record.password    # フィールド値を返す
url = record.url              # フィールド値を返す

# 動的セッター
record.password = 'NewPassword123!'
record.url = 'https://newurl.example.com'

# フィールドが存在するか確認
if record.respond_to?(:oneTimeCode)
  # oneTimeCode フィールドからTOTPコードを生成
  require 'keeper_secrets_manager/totp'
  totp_url = record.oneTimeCode
  totp_params = KeeperSecretsManager::TOTP.parse_url(totp_url)
  totp_code = KeeperSecretsManager::TOTP.generate_code(
    totp_params['secret'],
    algorithm: totp_params['algorithm'],
    digits: totp_params['digits'],
    period: totp_params['period']
  )
end

# すべてのフィールドにハッシュ形式でアクセス
fields = record.fields
fields.each do |type, values|
  puts "#{type}: #{values.join(', ')}"
end
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/jp/secrets-manager/developer-sdk-library/ruby-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.