# Python SDK

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2FnEX5oWkd4vv1lw4S7WaN%2Fimage.png?alt=media&#x26;token=193c37e0-cd02-42bd-b589-a0ede76006c0" alt=""><figcaption></figcaption></figure>

## ダウンロードとインストール <a href="#download-and-installation" id="download-and-installation"></a>

### PIPによるインストール <a href="#install-with-pip" id="install-with-pip"></a>

```bash
pip3 install -U keeper-secrets-manager-core
```

**Pythonのバージョン**: 3.9以降

詳細については、[keeper-secrets-manager-core (PyPI)](https://pypi.org/project/keeper-secrets-manager-core/)をご参照ください。

### ソースコード <a href="#source-code" id="source-code"></a>

Pythonのソースコードは、[GitHubリポジトリ](https://github.com/Keeper-Security/secrets-manager/tree/master/sdk/python)で入手できます。

**関連パッケージ**

* [Core SDK (keeper-secrets-manager-core)](https://pypi.org/project/keeper-secrets-manager-core/)
* [Helper Package (keeper-secrets-manager-helper)](https://pypi.org/project/keeper-secrets-manager-helper/)
* [Storage Packages](https://pypi.org/search/?q=keeper-secrets-manager-storage) (AWS KMS、GCP KMS、Oracle KMSとの統合)

## SDKの使用 <a href="#using-the-sdk" id="using-the-sdk"></a>

### 初期化 <a href="#initialize" id="initialize"></a>

{% hint style="info" %}
トークンのみで新しい構成ファイルを生成する場合 (あとから再利用するため)、トークンと端末側の設定を紐付け、`config.json` に必要な内容が書き込まれるまで、少なくとも1回の読み取り操作が必要です。
{% endhint %}

{% tabs %}
{% tab title="シークレットマネージャー" %}

```python
SecretsManager(token, config)
# トークンのみを使用して（後で使用するために）設定を生成するには、
# トークンを紐付ける読み取り操作が少なくとも1回必要です
#get_secrets(uids=None)
```

{% endtab %}

{% tab title="例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)
# トークンのみを使用して設定を生成するには 
# トークンを紐付ける読み取り操作が少なくとも1回必要です
#secrets_manager.get_secrets(uids=None)
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="150">パラメータ</th><th width="150">必須</th><th>説明</th><th>型</th></tr></thead><tbody><tr><td>token</td><td>はい</td><td>ワンタイムアクセストークン</td><td>String</td></tr><tr><td>config</td><td>はい</td><td>ストレージの設定</td><td><code>KeyValueStorage</code></td></tr></tbody></table>

{% hint style="info" %}
構成ファイルは、v17.1.0以降では安全な権限で自動的に作成されます (Unix系システムでは0600)。
{% endhint %}

### シークレットの取得 <a href="#retrieve-secrets" id="retrieve-secrets"></a>

{% tabs %}
{% tab title="シークレットの取得" %}

```python
get_secrets(uids=None)
```

{% endtab %}

{% tab title="例: すべてのシークレットを取得" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# すべてのレコードを取得
all_secrets = secrets_manager.get_secrets()

# すべてのレコードを出力
for secret in all_secrets:
    print(secret.dict)
```

{% endtab %}

{% tab title="例: フィルタを使用してシークレットを取得" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを取得
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# シークレットを出力
print(secret.dict)
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="150">パラメータ</th><th width="150">型</th><th width="150">必須</th><th width="150">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>uids</code></td><td><code>String[]</code></td><td>オプション</td><td>None</td><td>取得するレコードのUID</td></tr></tbody></table>

**戻り値**

型: **`Record[]`**

Keeperのすべてのレコード、または指定されたUIDを持つレコード。

### シークレットから値を取得 <a href="#retrieve-values-from-a-secret" id="retrieve-values-from-a-secret"></a>

#### パスワードを取得 <a href="#retrieve-a-password" id="retrieve-a-password"></a>

Keeperシークレットマネージャーからシークレットを取得すると、このショートカットでそのシークレットのパスワードを取得します。

{% tabs %}
{% tab title="パスワードを取得" %}

```python
secret.field('password', single=True)
```

{% endtab %}

{% tab title="例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD UID>'])[0]

# レコードからパスワードを取得
my_secret_password = secret.field('password', single=True)
```

{% endtab %}
{% endtabs %}

#### 標準フィールドを取得 <a href="#retrieve-standard-fields" id="retrieve-standard-fields"></a>

{% tabs %}
{% tab title="フィールド" %}

```python
secret.field(field_type, value=None, single=False)
```

{% endtab %}

{% tab title="例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD UID>'])[0]

# シークレットのログインフィールドを取得
my_secret_login = secret.field("login", single=True)
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="148.84765625">パラメータ</th><th width="142.27734375">型</th><th width="118.7734375">必須</th><th width="110.86328125">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>field_type</code></td><td><code>String</code></td><td>はい</td><td></td><td>取得するフィールドタイプ</td></tr><tr><td><code>value</code></td><td><code>String</code> または<code>String[]</code></td><td>オプション</td><td>None</td><td>指定すると、フィールドの値を指定値に設定</td></tr><tr><td><code>single</code></td><td><code>boolean</code></td><td>オプション</td><td>False</td><td>最初の値のみを返す</td></tr></tbody></table>

フィールドタイプはKeeper[レコードタイプ](/enterprise-guide/jp/record-types.md)に基づきます。利用可能なフィールドの詳細な一覧については、コマンダーで [`record-type-info`](/keeperpam/jp/commander-cli/command-reference/record-commands/record-type-commands.md#record-type-info-command) コマンドをご参照ください。

#### カスタムフィールドを取得 <a href="#retrieve-custom-fields" id="retrieve-custom-fields"></a>

{% tabs %}
{% tab title="カスタムフィールド" %}

```python
secret.custom_field(label, field_type=None, value=None, single=False)
```

{% endtab %}

{% tab title="例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDで特定のシークレットを取得
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# 標準テンプレートフィールドを取得
password = secret.field('password', single=True)

# APIキーなどのカスタムフィールドを取得
api_key = secret.custom_field('API Key', single=True)
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th>パラメータ</th><th width="150">型</th><th width="150">必須</th><th width="150">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>label</code></td><td><code>String</code></td><td>はい</td><td></td><td>カスタムフィールドのラベル</td></tr><tr><td><code>field_type</code></td><td><code>String</code></td><td>オプション</td><td>None</td><td>取得するフィールドタイプ</td></tr><tr><td><code>value</code></td><td><code>String</code>または<code>String[]</code></td><td>オプション</td><td>None</td><td>指定すると、フィールドの値を指定値に設定</td></tr><tr><td><code>single</code></td><td><code>boolean</code></td><td>オプション</td><td>False</td><td>最初の値のみを返す</td></tr></tbody></table>

カスタムフィールドとは、レコードタイプの定義に含まれていないが、ユーザーが追加できるフィールドのことです。

同じカスタムタイプの複数のフィールドを1つのレコードに表示することができます。これらのフィールドを区別するには、フィールドラベルが必要です。

**戻り値**

型: **`String`** または **`String[]`**

フィールドの1つまたは複数の値。 `single=True`オプションを指定した場合のみ、単一の値になります。

#### タイトルによってシークレットを取得 <a href="#retrieve-secrets-by-title" id="retrieve-secrets-by-title"></a>

{% tabs %}
{% tab title="タイトルによるレコード" %}

```python
# 一致するレコードをすべて取得
get_secrets_by_title(record_title)

# 最初に一致するレコードのみを取得
get_secret_by_title(record_title)
```

{% endtab %}

{% tab title="例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# シークレットマネージャーをセットアップ
secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'))

# レコードタイトルに一致する最初のシークレットを取得する
secret = secrets_manager.get_secret_by_title("My Credentials")

# レコードタイトルに一致するすべてのシークレットを取得する
secrets = secrets_manager.get_secrets_by_title("My Credentials")
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="178.10385756676556">パラメータ</th><th width="226.46137991694417">型</th><th width="150">必須</th><th>説明</th></tr></thead><tbody><tr><td><code>record_title</code></td><td><code>String</code></td><td>はい</td><td>検索するレコードタイトル</td></tr></tbody></table>

#### リンクされたレコードへのアクセス (GraphSync) <a href="#access-linked-records-graphsync" id="access-linked-records-graphsync"></a>

Keeperでは、GraphSyncを使用してレコードを他のレコードと関連付けることができます。Python SDKでは、レコードの `links` プロパティを通じて、これらの関連情報にアクセスできます。

{% tabs %}
{% tab title="リンクへアクセス" %}

```python
# レコードからリンク情報にアクセス
for link in secret.links:
    print(f"Linked Record UID: {link['recordUid']}")
    if link.get('data'):
        print(f"Link Data: {link['data']}")
    if link.get('path'):
        print(f"Link Path: {link['path']}")
```

{% endtab %}

{% tab title="使用例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# シークレットマネージャーを設定
secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDを指定して特定のシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD UID>'])[0]

# レコードにリンクがあるか確認
if secret.links:
    print(f"Record has {len(secret.links)} linked record(s)")

    # リンクを順に処理
    for link in secret.links:
        linked_uid = link.get('recordUid')
        print(f"Linked to record: {linked_uid}")

        # 必要に応じてリンク先のレコードを取得
        linked_record = secrets_manager.get_secrets([linked_uid])[0]
        print(f"Linked record title: {linked_record.title}")
else:
    print("Record has no links")
```

{% endtab %}
{% endtabs %}

**リンクオブジェクトの構造**

各リンクオブジェクトには、以下のプロパティが含まれます。

| プロパティ       | タイプ           | 説明                      |
| ----------- | ------------- | ----------------------- |
| `recordUid` | `String`      | リンク先レコードのUID            |
| `data`      | `String` (任意) | Base64形式でエンコードされたリンクデータ |
| `path`      | `String` (任意) | リンクに関するパス情報             |

{% hint style="info" %}
GraphSyncリンクを使用すると、ボルト内のレコード同士を参照関係で関連付けることができます。これにより、データベースのパスワードをデータベースサーバーの構成に関連付けるなど、認証情報間の関係を構築できます。
{% endhint %}

#### Keeper表記法を使用して値を取得 <a href="#retrieve-values-using-keeper-notation" id="retrieve-values-using-keeper-notation"></a>

{% tabs %}
{% tab title="Get Notation" %}

```python
get_notation(query)
```

{% endtab %}

{% tab title="例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# Keeper表記法を使用して特定の標準フィールドを取得
password = secrets_manager.get_notation('EG6KdJaaLG7esRZbMnfbFA/field/password')[0]

# Keeper表記法を使用して特定のカスタムフィールドを取得
custom_field_value = secrets_manager.get_notation('EG6KdJaaLG7esRZbMnfbFA/custom_field/my_field')
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Keeper表記法の形式と機能については、[Keeper表記法のページ](/keeperpam/jp/secrets-manager/about/keeper-notation.md)をご参照ください。
{% endhint %}

<table><thead><tr><th width="150">パラメータ</th><th width="150">型</th><th width="150">必須</th><th width="150">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>query</code></td><td><code>String</code></td><td>はい</td><td></td><td>指定したフィールドの値を取得するためのKeeper表記法を使用したクエリ</td></tr></tbody></table>

#### 戻り値 <a href="#returns" id="returns"></a>

型: `string` または `string[]`

クエリで取得したフィールドの値

#### TOTPコードを取得 <a href="#retrieve-a-totp-code" id="retrieve-a-totp-code"></a>

{% tabs %}
{% tab title="TOTPコードを取得" %}

```python
get_totp_code(url)
```

{% endtab %}

{% tab title="例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.utils import get_totp_code

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# レコードからTOTP url値を取得
url = record.get_standard_field_value('oneTimeCode', True)

# TOTP urlからコードを取得
totp = get_totp_code(url)
print(totp.code)
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="150">パラメータ</th><th width="150">型</th><th width="150">必須</th><th width="150">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>url</code></td><td><code>String</code></td><td>はい</td><td></td><td>TOTP Url</td></tr></tbody></table>

### シークレットを更新 <a href="#update-a-secret" id="update-a-secret"></a>

{% hint style="warning" %}
レコード更新コマンドは、成功時にローカルのレコードデータ (特にレコードリビジョンの更新) を更新しないため、既に更新されたレコードを継続的に更新してもリビジョンの不一致により失敗となります。各更新バッチの後に、更新済みのレコードをすべてリロードするようにしてください。
{% endhint %}

**変更をシークレットに保存**

{% tabs %}
{% tab title="シークレットを保存" %}

```python
save(record: KeeperRecord)
```

{% endtab %}

{% tab title="使用例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDで特定のシークレットを取得
secret_to_update = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# フィールド値を更新
secret_to_update.field('login', value='new login')

# 非フィールド値を更新
secret_to_update.title = "New Title"
secret_to_update.notes = "New Notes"

# 更新したシークレットを保存
secrets_manager.save(secret_to_update)
```

{% endtab %}

{% tab title="トランザクションの更新" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# シークレットマネージャのセットアップ
secrets_manager = SecretsManager(
     config=FileKeyValueStorage('ksm-config.json')
)

# UIDを使用して特定のシークレットを取得
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# レコードのパスワードをローテーション
secret.field('password', value='new password')
# トランザクションを開始
secrets_manager.save(secret, 'rotation')
# リモートホストでパスワードをローテーション
success = rotate_remote_ssh_password('new password')
# トランザクションを完了 (コミットかロールバック)
secrets_manager.complete_transaction(secret.uid, rollback=not success)

```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="150">パラメータ</th><th>型</th><th>必須</th><th>デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>record</code></td><td><code>KeeperRecord</code></td><td>はい</td><td></td><td>ストレージとクエリの設定</td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="150">パラメータ</th><th>型</th><th>必須</th><th>説明</th></tr></thead><tbody><tr><td>パラメータ</td><td>型</td><td>必須</td><td>説明</td></tr><tr><td><code>record</code></td><td><code>KeeperRecord</code></td><td>はい</td><td>保存するレコード (`KeeperRecord`)</td></tr></tbody></table>

[field](#retrieve-standard-fields)メソッドを使用してフィールド値を設定します。

利用可能なフィールドの詳細な一覧については、コマンダーで [`record-type-info`](/keeperpam/jp/commander-cli/command-reference/record-commands/record-type-commands.md#record-type-info-command) コマンドをご参照ください。一部のフィールドは複数の値を持つことができ、その場合は値をリストとして設定できます。

#### 標準フィールド値を更新 <a href="#update-a-standard-field-value" id="update-a-standard-field-value"></a>

{% tabs %}
{% tab title="フィールド" %}

```python
secret.field(field_type, value=None, single=False)
```

{% endtab %}

{% tab title="例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD UID>'])[0]

# ログインを更新
secret.field("login", value="My New Login")

# シークレットを保存
secrets_manager.save(secret)
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="168">パラメータ</th><th width="150">型</th><th width="150">必須</th><th width="150">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>field_type</code></td><td><code>String</code></td><td>はい</td><td></td><td>取得するフィールドタイプ</td></tr><tr><td><code>value</code></td><td><code>String</code> または <code>String[]</code></td><td>オプション</td><td>None</td><td>指定すると、フィールドの値を指定値に設定</td></tr><tr><td><code>single</code></td><td><code>boolean</code></td><td>オプション</td><td>False</td><td>最初の値のみを返す</td></tr></tbody></table>

#### カスタムフィールド値の更新 <a href="#update-a-custom-field-value" id="update-a-custom-field-value"></a>

{% tabs %}
{% tab title="カスタムフィールド" %}

```python
secret.custom_field(label, field_type=None, value=None, single=False)
```

{% endtab %}

{% tab title="使用例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Secrets Managerを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDで特定のシークレットを取得
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# 標準テンプレートフィールドを取得
password = secret.field('password', single=True)

# カスタムフィールド「API Key」を設定
my_new_api_key = "wKridl2ULt20qGuiP3IY"
secret.custom_field('API Key', value=my_new_api_key)

# 変更をシークレットに保存
secrets_manager.save(secret)
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="171">パラメータ</th><th width="150">型</th><th width="150">必須</th><th width="150">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>label</code></td><td><code>String</code></td><td>はい</td><td></td><td>カスタムフィールドのラベル</td></tr><tr><td><code>field_type</code></td><td><code>String</code></td><td>オプション</td><td>None</td><td>取得するフィールドタイプ</td></tr><tr><td><code>value</code></td><td><code>String</code>または<code>String[]</code></td><td>オプション</td><td>None</td><td>指定すると、フィールドの値を指定値に設定</td></tr><tr><td><code>single</code></td><td><code>boolean</code></td><td>オプション</td><td>False</td><td>最初の値のみを返す</td></tr></tbody></table>

#### ランダムなパスワードを生成 <a href="#generate-a-random-password" id="generate-a-random-password"></a>

{% tabs %}
{% tab title="パスワードを生成" %}

```python
generate_password(length, lowercase, uppercase, digits, specialCharacters)
```

{% endtab %}

{% tab title="使用例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.utils import generate_password

# シークレットマネージャーを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDで特定のシークレットを取得
secret = secrets_manager.get_secrets(['EG6KdJaaLG7esRZbMnfbFA'])[0]

# ランダムなパスワードを生成
password = generate_password()
# 新しいパスワードでレコードを更新
secret.field('password', value=password)

# 変更をシークレットに保存
secrets_manager.save(secret)
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="203.7142857142857">パラメータ</th><th width="150">型</th><th width="150">必須</th><th>デフォルト</th></tr></thead><tbody><tr><td>length</td><td><code>int</code></td><td>オプション</td><td>64</td></tr><tr><td>lowercase</td><td><code>int</code></td><td>オプション</td><td>0</td></tr><tr><td>uppercase</td><td><code>int</code></td><td>オプション</td><td>0</td></tr><tr><td>digits</td><td><code>int</code></td><td>オプション</td><td>0</td></tr><tr><td>specialCharacters</td><td><code>int</code></td><td>オプション</td><td>0</td></tr></tbody></table>

各パラメータは、使用する文字の種類の最小数を示します。たとえば、「uppercase」は、使用する大文字の最小数となります。

### ファイルのダウンロード <a href="#download-a-file" id="download-a-file"></a>

{% tabs %}
{% tab title="ファイルを保存" %}

```python
file.save_file(file_path, create_folders=False)
```

{% endtab %}

{% tab title="例" %}

```python
# すべてのファイルを/tmpフォルダに保存（存在しない場合はフォルダを作成）
for file in secret.files:
    print("file: %s" % file)
    file.save_file("/tmp/" + file.name, True)
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="203">パラメータ</th><th width="150">型</th><th width="150">必須</th><th width="150">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>file_path</code></td><td><code>String</code></td><td>はい</td><td></td><td>ファイルの保存先のパス</td></tr><tr><td><code>create_folders</code></td><td><code>boolean</code></td><td>いいえ</td><td>False</td><td>存在しない場合はfile_pathにフォルダを作成</td></tr></tbody></table>

### ファイルのアップロード <a href="#upload-a-file" id="upload-a-file"></a>

{% tabs %}
{% tab title="ファイルのアップロード" %}
ファイルのアップロード

```python
upload_file(owner_record, file: my_file)
```

Keeperファイルアップロードオブジェクトを作成

```python
KeeperFileUpload.from_file(path, file_name=None, file_title=None, mime_type=None)
```

{% endtab %}

{% tab title="例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.core import KeeperFileUpload

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDによってファイルを添付するシークレットを取得
UID_FILTER = 'XXX'
owner_record= secrets_manager.get_secrets([UID_FILTER])[0]

# アップロード用のファイルデータを準備
my_file = KeeperFileUpload.from_file("./myFile.json", "myfile.json", "My File") 

# 所有者のレコードに添付されたファイルをアップロードしてUIDを取得
file_uid = secrets_manager.upload_file(owner_record, file = my_file)
```

{% endtab %}
{% endtabs %}

ファイルのアップロード

<table><thead><tr><th width="184.14763231197773">パラメータ</th><th width="173">型</th><th width="150">必須</th><th>説明</th></tr></thead><tbody><tr><td><code>owner_record</code></td><td>KeeperRecord</td><td>はい</td><td>アップロードされたファイルを添付するレコード</td></tr><tr><td><code>file</code></td><td>KeeperFileUpload</td><td>はい</td><td>アップロードするファイル</td></tr></tbody></table>

ファイルからのKeeperファイルのアップロード

<table><thead><tr><th width="169">パラメータ</th><th width="150">型</th><th width="150">必須</th><th width="150">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>path</code></td><td>string</td><td>はい</td><td></td><td>アップロードするファイルへのパス</td></tr><tr><td><code>file_name</code></td><td>string</td><td>いいえ</td><td>None</td><td>アップロード後にKeeperに格納されるファイルの名前</td></tr><tr><td><code>file_title</code></td><td>string</td><td>いいえ</td><td>None</td><td>アップロード後にKeeperに格納されるファイルのタイトル</td></tr><tr><td><code>mime_type</code></td><td>string</td><td>いいえ</td><td>None</td><td>ファイル内のデータの種類。 何も指定しない場合は、「application/octet-stream」が使用されます。</td></tr></tbody></table>

#### 戻り値 <a href="#returns-1" id="returns-1"></a>

型: `string`

添付ファイルのファイルUID

### 添付ファイルの削除 <a href="#remove-file-attachments" id="remove-file-attachments"></a>

{% tabs %}
{% tab title="ファイルを削除" %}

```
secrets_manager.save(record, links_to_remove=['<FILE_UID>'])
```

{% endtab %}

{% tab title="使用例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDを指定してシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD_UID>'])[0]

# レコードに含まれるファイルのUIDを取得
file_uids = [file.file_uid for file in secret.files]
print(f"Files to remove: {file_uids}")

# UIDを指定して特定のファイルを削除
secrets_manager.save(secret, links_to_remove=file_uids)
```

{% endtab %}

{% tab title="複数のファイルを削除" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDを指定してシークレットを取得
secret = secrets_manager.get_secrets(['<RECORD_UID>'])[0]

# 複数の特定ファイルを削除
files_to_remove = ['<FILE_UID_1>', '<FILE_UID_2>']
secrets_manager.save(secret, links_to_remove=files_to_remove)

# すべてのファイルを削除
all_file_uids = [file.file_uid for file in secret.files]
secrets_manager.save(secret, links_to_remove=all_file_uids)

```

{% endtab %}
{% endtabs %}

| パラメーター            | タイプ                         | 必須  | 説明                 |
| ----------------- | --------------------------- | --- | ------------------ |
| `record`          | `KeeperRecord`              | はい  | 更新対象となるレコード        |
| `links_to_remove` | `String` または `List[String]` | いいえ | レコードから削除するファイルのUID |

{% hint style="warning" %}
ファイルを削除したあとに同じレコードへ続けて更新する場合は、レコードのリビジョンが更新されているため、`get_secrets()` でレコードを取り直してください。
{% endhint %}

### シークレットの作成 <a href="#create-a-secret" id="create-a-secret"></a>

#### 要件 <a href="#prerequisites" id="prerequisites"></a>

* 共有フォルダのUID
  * 共有フォルダには、シークレットマネージャーアプリケーションからアクセスできること
  * あなたとシークレットマネージャーアプリケーションに編集権限が付与されていること
  * 共有フォルダには、少なくとも1つのレコードが存在すること。
* 作成されたレコードとレコードのフィールドが正しく書式設定されていること。
  * 各レコードタイプで想定されるフィールド形式については、[レコードタイプ](/enterprise-guide/jp/record-types.md)をご参照ください。
* TOTPフィールドには、KSM SDK以外で生成されたURLのみを指定できます。
* レコードの作成後は、[upload\_file](#upload-a-file)を使用して添付ファイルをアップロードできます。

{% tabs %}
{% tab title="レコードを作成" %}

```python
from keeper_secrets_manager_core.dto.dtos import RecordCreate,RecordField

record = RecordCreate(record_type='login', title='test_KSM')
record.fields = [ 
    RecordField(field_type='login',value='test_login'),
    RecordField(field_type='password',value='test_pwd') 
]

secrets_manager.create_secret(folder_uid, record)
```

| パラメータ        | 型              | 必須 | デフォルト |
| ------------ | -------------- | -- | ----- |
| `folder_uid` | `String`       | はい |       |
| `record`     | `KeeperRecord` | はい |       |
| {% endtab %} |                |    |       |

{% tab title="サブフォルダにレコードを作成" %}

```python
from keeper_secrets_manager_core.dto.dtos import RecordCreate,RecordField

record = RecordCreate(record_type='login', title='test_KSM')
record.fields = [ 
    RecordField(field_type='login',value='test_login'),
    RecordField(field_type='password',value='test_pwd') 
]

from keeper_secrets_manager_core.dto.payload import CreateOptions

create_options = CreateOptions(
    folder_uid='shared_folder_uid',
    subfolder_uid='user_folder_uid'
)

secrets_manager.create_secret_with_options(create_options, record)
```

<table><thead><tr><th width="195">パラメータ</th><th width="168">型</th><th width="127">必須</th><th>デフォルト</th></tr></thead><tbody><tr><td><code>create_options</code></td><td><code>CreateOptions</code></td><td>はい</td><td></td></tr><tr><td><code>record</code></td><td><code>KeeperRecord</code></td><td>はい</td><td></td></tr></tbody></table>
{% endtab %}

{% tab title="ログインのレコードの例" %}
この例では、ログイン値と生成されたパスワードを含むログインタイプのレコードを作成します。

{% hint style="info" %}
例にある `[FOLDER UID]` をシークレットマネージャーがアクセスできる共有フォルダのUIDに置き換えます。
{% endhint %}

```python
# 新しいログインレコードを作成
new_login_record = RecordCreate('login', "Sample KSM Record: Python")
# ログインフィールドとパスワードフィールドに入力
new_login_record.fields = [
    RecordField(field_type='login', value='username@email.com'),
    RecordField(field_type='password', value=generate_password())
]
# メモに入力
new_login_record.notes = 'This is a Python record creation example'
# 新しいレコードを作成し、新規レコードのUIDを取得
record_uid = secrets_manager.create_secret('[FOLDER UID]', new_login_record)
```

{% endtab %}

{% tab title="カスタムタイプの例" %}
この例では、カスタムのレコードタイプのレコードを作成します。

{% hint style="info" %}
例にある`[FOLDER UID]`をシークレットマネージャーがアクセスできる共有フォルダのUIDに置き換えます。
{% endhint %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from keeper_secrets_manager_core.dto.dtos import RecordCreate, RecordField
from keeper_secrets_manager_core.utils import generate_password

# setup secrets manger
secrets_manager = SecretsManager(
  # token='US:XXXXXX',
    config=FileKeyValueStorage('ksm-config.json')
)

custom_login = RecordCreate(record_type='Custom Login', title='Sample Custom Type KSM Record: Python')
custom_login.fields = [
    RecordField(field_type='host',
                value={'hostName':'127.0.0.1', 'port':'8080'},
                label="My Custom Host lbl",
                required=True),
    RecordField(field_type='login',
                value='login@email.com',
                label='My Custom Login lbl',
                required=True),
    RecordField(field_type='password',
                value=generate_password(),
                label='My Custom Password lbl',
                required=True),
    RecordField(field_type='url',
                value='http://localhost:8080/login',
                label='My Login Page',
                required=True),
    RecordField(field_type='securityQuestion',
                value={
                    'question':'What is one plus one (write just a number)',
                    'answer':'2'
                },
                label='My Question 1',
                required=True),
    RecordField(field_type='phone',
                value={
                  'region':'US',
                  'number':'510-444-3333',
                  'ext':'2345',
                  'type':'Mobile'},
                label='My Phone Number'),
    RecordField(field_type='date',
                value=1641934793000,
                label='My Date Lbl',
                required=True),
    RecordField(field_type='name',
                value={
                  'first':'John',
                  'middle':'Patrick',
                  'last':'Smith'},
                label="My Custom Name lbl",
                required=True),
    RecordField(field_type='oneTimeCode',
                value='otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example',
                label='My TOTP',
                required=True)
]

custom_login.custom = [
    RecordField(field_type='phone',
                value={'region':'US', 'number':'510-222-5555', 'ext':'99887', 'type':'Mobile'},
                label='My Custom Phone Lbl 1'),
    RecordField(field_type='phone',
                value={'region':'US', 'number':'510-111-3333', 'ext':'45674', 'type':'Mobile'},
                label='My Custom Phone Lbl 2'),
]

custom_login.notes = "\tThis custom type record was created\n\tvia Python SDK copied from https://docs.keeper.io/secrets-manager/secrets-manager/developer-sdk-library/python-sdk"

record_uid = secrets_manager.create_secret('[FOLDER UID]', custom_login)
```

{% endtab %}
{% endtabs %}

#### 戻り値 <a href="#returns-2" id="returns-2"></a>

型: `string`

新規レコードのレコードUID

### シークレットの削除 <a href="#delete-a-secret" id="delete-a-secret"></a>

Python KSM SDKでKeeperボルトのレコードを削除できます。

{% tabs %}
{% tab title="シークレットの削除" %}

```
secrets_manager.delete_secret(record_uid)
```

| パラメータ        | 型        | 必須 |
| ------------ | -------- | -- |
| `record_uid` | `string` | はい |
| {% endtab %} |          |    |

{% tab title="例" %}

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# シークレットマネージャーを設定
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json')
)

# UIDレコードで特定のシークレットを削除
secret = secrets_manager.delete_secret('EG6KdJaaLG7esRZbMnfbFA')
```

{% endtab %}
{% endtabs %}

### キャッシュ <a href="#caching" id="caching"></a>

ネットワークアクセスが失われたときにシークレットにアクセスできなくなる状況を避けるため、Python SDKを使用してシークレットを暗号化されたファイルでローカルマシンにキャッシュできます。

**キャッシュの設定と構成**

Python SDKでキャッシュを設定するには、`SecretsManager` オブジェクトを作成するときにキャッシュポスト関数を含める必要があります。

Python SDKには、`KSMCache` クラスにデフォルトのキャッシュ機能が含まれており、キャッシュされたクエリをローカルファイルに保存し、復旧機能として使用できます (ネットワーク接続がある場合は常にネットワークデータを優先し、ウェブボルトにアクセスできない場合にのみキャッシュを使用します)。独自のキャッシュ機能を作成することも可能で、`KSMCache` を出発点として利用できます。例えば、ネットワークアクセスよりもローカルキャッシュを優先し、独自のキャッシュ管理を行う (例: キャッシュデータを5分ごとに更新する) 機能を作成できます。

```python
secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json'),
    custom_post_function=KSMCache.caching_post_function
)
```

{% hint style="danger" %}
`KSMCache` クラスのデフォルトキャッシュ機能は、常に最後のリクエストのみを保存します。例えば、UID1に対するフィルタリングリクエストがキャッシュされている場合、ネットワーク切断時に同じキャッシュからUID2をリクエストすると、空のレスポンスが返されます (UID2が同じKSMアプリに共有されている場合でも、それがキャッシュされていなければ利用できません)。
{% endhint %}

{% hint style="warning" %}
キャッシュからのレコード更新 (または新しいレコードの作成) は、キャッシュされたレコードデータを無効にし、同じレコードを連続して更新する操作は失敗します。異なるレコードを修正する場合、バッチ更新は機能します。キャッシュされたレコードを更新した後は、常に `get_secrets` 関数を呼び出してキャッシュをリフレッシュし、ボルトから新しいレコードリビジョンなどの更新されたメタデータを取得するようにしてください。
{% endhint %}

#### 独自のキャッシュ関数の作成 <a href="#creating-your-own-caching-function" id="creating-your-own-caching-function"></a>

まず、次の引数を使用してキャッシュ関数を作成し、`post_function` を呼び出します。

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import KSMCache, KSMHttpResponse

def caching_post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs=True, proxy_url=None
):
    ksm_rs = SecretsManager.post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs
    )
    # ここにカスタムキャッシュ処理を記述 ...

    # 常に KSMHttpResponse オブジェクトを返すようにする
    return ksm_rs

```

次に、KSMCacheを使用して任意のキャッシュ処理ロジックを実装できます。

以下は基本的なサンプルです。

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import KSMCache, KSMHttpResponse
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from http import HTTPStatus

def caching_post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs=True, proxy_url=None
):
    ksm_rs = SecretsManager.post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs
    )

    if ksm_rs.status_code < 400:
        KSMCache.save_cache(transmission_key.key + ksm_rs.data)
        return ksm_rs

    # KSMCache が空の場合がある    
    cached_data = KSMCache.get_cached_data()
    cached_transmission_key = cached_data[:32]
    transmission_key.key = cached_transmission_key
    data = cached_data[32 : len(cached_data)]

    new_rs = KSMHttpResponse(HTTPStatus.OK, data, None)
    return new_rs


secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'),
    verify_ssl_certs=False,
    custom_post_function=caching_post_function
)
```

### フォルダ <a href="#folders" id="folders"></a>

フォルダは完全なCRUD (作成、読み取り、更新、削除操作) をサポートしています。

### フォルダの読み取り <a href="#read-folders" id="read-folders"></a>

フォルダの完全な階層構造をダウンロードします。

```python
get_folders()
```

**レスポンス**

型: `List[KeeperFolder]`

**使用例**

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
folders = secrets_manager.get_folders()
```

### フォルダの作成 <a href="#create-a-folder" id="create-a-folder"></a>

`CreateOptions` とフォルダ名の指定が必要です。`CreateOptions` はフォルダのUIDパラメータ (共有フォルダのUID) が必須ですが、サブフォルダのUIDはオプションであり、指定されていない場合は、通常の新しいフォルダが親 (共有フォルダ) の直下に作成されます。サブフォルダは、親の共有フォルダの直接の下位オブジェクトである必要はありません。親フォルダから何階層も深い位置にサブフォルダを作成することができます。

```python
create_folder(create_options: CreateOptions, folder_name: str, folders=None)
```

<table><thead><tr><th width="200.85161529417937">パラメータ</th><th width="225.99431983802478">型</th><th width="102">必須</th><th width="86">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>create_options</code></td><td><code>CreateOptions</code></td><td>はい</td><td></td><td>親およびサブフォルダのUID</td></tr><tr><td><code>folder_name</code></td><td><code>str</code></td><td>はい</td><td></td><td>フォルダ名</td></tr><tr><td><code>folders</code></td><td><code>List[KeeperFolder]</code></td><td>いいえ</td><td><code>None</code></td><td>CreateOptionsで作成した親とサブフォルダの検索に使用するフォルダのリスト</td></tr></tbody></table>

**使用例**

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import CreateOptions
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
co = CreateOptions(folder_uid="[PARENT_SHARED_FOLDER_UID]", subfolder_uid="")
new_folder_uid = secrets_manager.create_folder(co, "new_folder")
```

### フォルダの更新 <a href="#update-a-folder" id="update-a-folder"></a>

フォルダのメタデータ (現在はフォルダ名のみ) を更新します。

```python
update_folder(folder_uid: str, folder_name: str, folders=None)
```

<table><thead><tr><th width="194.85161529417937">パラメータ</th><th width="218.99431983802478">型</th><th width="104">必須</th><th width="92">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>folder_uid</code></td><td><code>str</code></td><td>はい</td><td></td><td>フォルダのUID</td></tr><tr><td><code>folder_name</code></td><td><code>str</code></td><td>はい</td><td></td><td>新しいフォルダ名</td></tr><tr><td><code>folders</code></td><td><code>List[KeeperFolder]</code></td><td>いいえ</td><td><code>None</code></td><td>親フォルダの検索に使用するフォルダのリスト</td></tr></tbody></table>

**使用例**

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
secrets_manager.update_folder("[FOLDER_UID]", "new_folder_name")
```

### フォルダの削除 <a href="#delete-folders" id="delete-folders"></a>

フォルダのリストを削除します。空でないフォルダを削除するには、`force_deletion` フラグを使用します。

{% hint style="info" %}
`force_deletion` を使用する場合は、親フォルダと子フォルダのUIDを一緒に送信しないようにしてください。削除する順序によっては、エラーが発生する可能性があります。たとえば、親が子を先に強制削除した場合などです。リストが必ずしもFIFO順で処理される保証はありません。
{% endhint %}

{% hint style="info" %}
ボルトに存在しないフォルダのUIDやKSMアプリケーションで共有されていないフォルダのUIDはエラーになりません。
{% endhint %}

```python
delete_folder(folder_uids: List[str], force_deletion: bool = False)
```

<table><thead><tr><th width="209.85161529417937">パラメータ</th><th width="165.99431983802478">型</th><th width="108">必須</th><th width="101">デフォルト</th><th>説明</th></tr></thead><tbody><tr><td><code>folder_uids</code></td><td><code>List[str]</code></td><td>はい</td><td></td><td>フォルダUIDリスト</td></tr><tr><td><code>force_deletion</code></td><td><code>bool</code></td><td>いいえ</td><td><code>False</code></td><td>空でないフォルダを強制的に削除</td></tr></tbody></table>

**使用例**

```python
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
secrets_manager.delete_folder(["[FOLDER_UID1]", "[FOLDER_UID2]"], True)
```

## プロキシのサポート <a href="#proxy-support" id="proxy-support"></a>

### 環境変数 <a href="#environment-variable" id="environment-variable"></a>

KeeperシークレットマネージャーSDKは、[デフォルト](https://requests.readthedocs.io/en/latest/user/advanced/#proxies)で[requests](https://pypi.org/project/requests/)ライブラリを使用し、HTTPS\_PROXY環境変数に対応しています。

```
HTTPS_PROXY=https://yourproxy:8888 python main.py
```

この設定を行うと、Keeperシークレットマネージャーへのリクエストを含むすべてのリクエストが、指定したプロキシを経由して送信されます。

{% hint style="info" %}
プロキシ設定は、環境変数で行うことを推奨します。コードに設定を直接記述せずに済み、ツール間で同じ設定を使い回せるほか、導入や運用も容易になります。
{% endhint %}

### SecretsManagerのパラメータ <a href="#secretsmanager-parameter" id="secretsmanager-parameter"></a>

SDK内でのみプロキシを使用したい場合は、`SecretsManager` にプロキシURLを渡すこともできます。

```python
secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'),
    proxy_url="https://yourproxy:8888"
)
```

{% hint style="info" %}
プロキシで認証が必要な場合は、プロキシURLにユーザー名とパスワードを含めて指定してください。
{% endhint %}

```
https://username:pass@yourproxy:8888
```


---

# 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/python-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.