> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeper-connection-manager/jp/using-keeper-connection-manager/creating-connections/batch-import-and-api.md).

# 一括インポートとAPI

## 概要

#### [APIセクションへジャンプ](#importing-connections-via-api-1)

### CSV、JSON、YAMLによる接続のインポート

Keeperコネクションマネージャーでは、管理者が[CSV、JSON、またはYAMLファイル](#supported-file-types)をアップロードして接続を作成し、それらの接続に権限を割り当てることができます。

また、インポートUI内の **\[Replace/Update existing connections]** (既存の接続を置換/更新) チェックボックスをオンにすると、既存の接続を更新できます。

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FnZVR8wx7XTZNpbFloBhe%2Fimage.png?alt=media&#x26;token=fc28bdec-a0ff-46c5-8f5f-d06257ff1aeb" alt=""><figcaption></figcaption></figure>

既存の接続は、名前と親接続グループによって識別されます。

### APIによる接続のインポート

さらに、Keeperコネクションマネージャーでは、管理者が[API](#importing-connections-with-csv)経由で接続を作成し、それらの接続に権限を割り当てることもできます。

## 対応ファイルタイプのデータ <a href="#supported-file-types" id="supported-file-types"></a>

接続のインポートでは、CSV、JSON、YAMLのファイルタイプに対応しています。

各ファイルタイプでは、接続は以下のデータで定義されます。

* 接続名
* 接続プロトコル
  * 対応する接続プロトコルの一覧は、こちらの[ページ](/keeper-connection-manager/jp/supported-protocols.md)をご参照ください
* 接続パラメータ (オプション)
* 接続グループの場所 (オプション)
* アクセスを許可するユーザーのリスト (オプション)
* アクセスを許可するユーザーグループのリスト (オプション)
* 接続属性 (オプション)

### CSVによる接続のインポート <a href="#importing-connections-with-csv" id="importing-connections-with-csv"></a>

接続インポートCSVファイルには、行ごとに1つの接続レコードがあり、各列が接続フィールドを指定します。

以降のセクションでは、接続インポートCSVファイルで有効な接続フィールド (列) をすべて取り扱います。

#### 必須の接続フィールド - name と protocol

少なくとも、接続の **name** (名前) と **protocol** (プロトコル) を指定する必要があります。

KCMは以下の接続プロトコルに対応しており、それぞれに対応する「Internal name」(内部名) を使用する必要があります。

| プロトコル                                                                                             | 内部名          |
| ------------------------------------------------------------------------------------------------- | ------------ |
| [VNC](/keeper-connection-manager/jp/supported-protocols/vnc.md)                                   | `vnc`        |
| [RDP](/keeper-connection-manager/jp/supported-protocols/rdp.md)                                   | `rdp`        |
| [SSH](/keeper-connection-manager/jp/supported-protocols/ssh.md)                                   | `ssh`        |
| [Telnet](/keeper-connection-manager/jp/supported-protocols/telnet.md)                             | `telnet`     |
| [Kubernetes](/keeper-connection-manager/jp/supported-protocols/kubernetes.md)                     | `kubernetes` |
| [MySQL](/keeper-connection-manager/jp/supported-protocols/mysql.md)                               | `mysql`      |
| [PostgreSQL](/keeper-connection-manager/jp/supported-protocols/postgresql.md)                     | `postgresql` |
| [Microsoft SQL Server](/keeper-connection-manager/jp/supported-protocols/microsoft-sql-server.md) | `sql-server` |

#### オプションの接続フィールド - 接続パラメータ

接続のパラメータは、接続のプロトコルに依存します。

接続プロトコルで利用可能なパラメータについて詳しくは、上の表を参照してプロトコルへ移動するか、こちらの[ページ](/keeper-connection-manager/jp/supported-protocols.md)をご参照ください。

#### オプションの接続フィールド - group または parentIdentifier

接続のインポート先となる接続グループIDは、「parentIdentifier」で直接指定するか、「group」を使用して親グループへのパスを指定できます。

セミコロン区切りのユーザー/グループのリスト内で、ユーザーまたはグループ識別子にセミコロンを含める必要がある場合は、バックスラッシュでエスケープできます。たとえば、「first\\;last」です。

#### オプションの接続フィールド - users と groups

ユーザーまたはユーザーグループ識別子のリストはセミコロン区切りとし、`users` および `groups` 接続フィールドで定義する必要があります。

#### オプションの接続フィールド - attributes

接続の追加の特性を指定します。

#### 例

```csv
name,protocol,username,password,private-key,hostname,group,users,groups,guacd-encryption (attribute)
conn1,vnc,alice,pass1,,conn1.web.com,ROOT,guac user 1;guac user 2,Connection 1 Users,none
conn2,rdp,bob,pass2,,conn2.web.com,ROOT/Parent Group,guac user 1,,ssl
conn3,ssh,${KEEPER_SERVER_USERNAME},,${KEEPER_SERVER_KEY},conn3.web.com,ROOT/Parent Group/Child Group,guac user 2;guac user 3,,
conn4,kubernetes,,,,,,,,
```

{% hint style="info" icon="pencil-line" %}
上記の例の最初の行はヘッダーを指定しています。
{% endhint %}

ほとんどの場合、フィールド間で競合は発生しませんが、必要に応じて「(attribute)」または「(parameter)」接尾辞を追加してあいまいさを解消できます。

### JSONによる接続のインポート <a href="#importing-connections-with-json" id="importing-connections-with-json"></a>

接続インポートJSONファイルには、接続オブジェクトのリストがあります。各接続オブジェクトでは、以下のキーを使用できます。

<table><thead><tr><th width="249">キー</th><th>説明</th></tr></thead><tbody><tr><td>name</td><td>接続の名前</td></tr><tr><td>protocol</td><td>接続のプロトコル。対応する接続プロトコルの一覧は、こちらの<a href="/pages/8PpXnZThxB8SSGUuwPkk">ページ</a>をご参照ください</td></tr><tr><td>parameters</td><td>プロトコル接続を確立するための接続パラメータ。必須パラメータについては、こちらの<a href="/pages/8PpXnZThxB8SSGUuwPkk">ページ</a>をご参照ください。(オプション)</td></tr><tr><td>parentIdentifier または group</td><td>接続のインポート先となる接続グループIDは、<code>parentIdentifier</code> キーで直接指定するか、<code>group</code> キーを使用して親グループへのパスを指定できます (オプション)</td></tr><tr><td>users</td><td>アクセスを許可するユーザーの配列 (オプション)</td></tr><tr><td>groups</td><td>アクセスを許可するユーザーグループの配列 (オプション)</td></tr><tr><td>attributes</td><td>接続の属性</td></tr></tbody></table>

各接続オブジェクトでは、少なくとも接続名とプロトコルを指定する必要があります。

#### 例

```json
[
  {
    "name": "conn1",
    "protocol": "vnc",
    "parameters": { "username": "alice", "password": "pass1", "hostname": "conn1.web.com" },
    "parentIdentifier": "ROOT",
    "users": [ "guac user 1", "guac user 2" ],
    "groups": [ "Connection 1 Users" ],
    "attributes": { "guacd-encryption": "none" }
  },
  {
    "name": "conn2",
    "protocol": "rdp",
    "parameters": { "username": "bob", "password": "pass2", "hostname": "conn2.web.com" },
    "group": "ROOT/Parent Group",
    "users": [ "guac user 1" ],
    "attributes": { "guacd-encryption": "none" }
  },
  {
    "name": "conn3",
    "protocol": "ssh",
    "parameters": { "username": "${KEEPER_SERVER_USERNAME}", "private-key": "${KEEPER_SERVER_KEY}", "hostname": "conn3.web.com" },
    "group": "ROOT/Parent Group/Child Group",
    "users": [ "guac user 2", "guac user 3" ]
  },
  {
    "name": "conn4",
    "protocol": "kubernetes"
  }
]
```

### YAMLによる接続のインポート <a href="#importing-connections-with-yaml" id="importing-connections-with-yaml"></a>

接続インポートYAMLファイルは、JSON形式とまったく同じ構造の接続オブジェクトのリストです。

```yaml
---
  - name: conn1
    protocol: vnc
    parameters:
      username: alice
      password: pass1
      hostname: conn1.web.com
    group: ROOT
    users:
      - guac user 1
      - guac user 2
    groups:
      - Connection 1 Users
    attributes:
      guacd-encryption: none
  - name: conn2
    protocol: rdp
    parameters:
      username: bob
      password: pass2
      hostname: conn2.web.com
    group: ROOT/Parent Group
    users:
      - guac user 1
    attributes:
      guacd-encryption: none
  - name: conn3
    protocol: ssh
    parameters:
      username: ${KEEPER_SERVER_USERNAME}
      private-key: ${KEEPER_SERVER_KEY}
      hostname: conn3.web.com
    group: ROOT/Parent Group/Child Group
    users:
      - guac user 2
      - guac user 3
  - name: conn4
    protocol: kubernetes
```

## APIによる接続のインポート

Keeperコネクションマネージャーでは、管理者がBatch Import UIと同じエンドポイントを使用して、API経由で接続を直接一括インポートすることもできます。

複数の接続を作成または置換するには、接続ディレクトリリソース (`/api/session/data/{DATA_SOURCE}/connections`) に対してHTTP PATCHメソッドを使用します。データソースは接続の作成先を指定し、通常はインストール時に選択したデータベースの名前、つまり `mysql`、`postgres`、または `sqlserver` になります。以下の例では、`mysql` データソースを使用します。

任意の接続プロトコルタイプで使用可能なパラメータについて詳しくは、[KCMプロトコルのドキュメント](/keeper-connection-manager/jp/supported-protocols.md)をご参照ください。

{% hint style="warning" %}
ディレクトリのPATCHメソッドではアトミック性が保証されます。リクエスト全体が成功する必要があり、含まれるいずれかのパッチが失敗した場合、バッチ内のすべての変更がロールバックされます。
{% endhint %}

### ログイン - API認証トークン

他のAPIエンドポイントを使用する前に、認証トークン (HEX値) が必要です。Webアプリにログインしたユーザーのリクエストを確認するか、`tokens` エンドポイントに直接リクエストを送信することで取得できます。以下は、その例です。

```bash
curl 'https://kcm.example.com/api/tokens' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=kcm_admin&password=kcm_admin_pass123'
```

レスポンスには認証トークンと、ログインを承認したデータソースが含まれます。

```json
{
  "authToken": "TG9YZW0GAXBZDW0GZG9SB3IGC2L0",
  "username": "kcm_admin",
  "dataSource": "mysql",
  "availableDataSources": [
    "mysql",
    "mysql-shared"
  ]
}
```

お好みのAPIツールを使用できます。Postmanを使用する場合、GETまたはPATCHを送信するときは、認可を **\[Inherit auth from parent]** に設定し、キーを `Guacamole-Token`、値をトークンとしたヘッダーを設定します。トークンのデフォルトの有効期限は60分であることにご留意ください。

<figure><img src="https://3357255970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fb7weUpu7VBcMnESSH8vG%2Fuploads%2FcyPl0zV7Wy0UEkb4CiTQ%2Fpostman.png?alt=media&#x26;token=315b907c-5967-4d50-8fb1-4e0f4e3228a9" alt=""><figcaption><p>Postmanの使用例</p></figcaption></figure>

### 新しい接続の作成

作成する各接続は、リクエスト本文内で「add」操作を使用する個別のPATCHとして表す必要があります。以下は、いくつかの新しい接続を作成する例です。

```bash
cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/connections' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Guacamole-Token: TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
  -d '@-'
[
  {
    "op": "add",
    "path": "/",
    "value": {
      "parentIdentifier": "ROOT",
      "name": "conn1 ssh",
      "protocol": "ssh",
      "parameters": {
        "hostname": "conn1.web.com",
        "color-scheme": "white-black",
        "username": "${KEEPER_SERVER_USERNAME}", 
        "private-key": "${KEEPER_SERVER_KEY}"
      },
      "attributes": {
        "guacd-encryption": "none"
      }
    }
  },
  {
    "op": "add",
    "path": "/",
    "value": {
      "parentIdentifier": "1",
      "name": "conn2 vnc",
      "protocol": "vnc",
      "parameters": {
        "hostname": "conn2.web.com",
        "username": "alice", 
        "password": "password123"
      },
      "attributes": {}
    }
  }
]
```

ユーザー、ユーザーグループ、接続グループ、共有プロファイルも、接続と同じPATCHセマンティクスを使用して変更できます。それぞれのAPIエンドポイントは以下のとおりです。

* `/api/session/data/{DATA_SOURCE}/users`
* `/api/session/data/{DATA_SOURCE}/userGroups`
* `/api/session/data/{DATA_SOURCE}/connectionGroups`
* `/api/session/data/{DATA_SOURCE}/sharingProfiles`

対応するキーと値のペアの一覧については、本ドキュメントのこの[セクション](#importing-connections-with-json)をご参照ください。

レスポンスには、パッチが送信されたのと同じ順序で、すべての接続の操作とIDが含まれます。

```json
{
  "patches": [
    {
      "op": "add",
      "identifier": "1",
      "path": "/"
    },
    {
      "op": "add",
      "identifier": "2",
      "path": "/"
    }
  ]
}
```

### 既存の接続の更新

既存の接続を置換するには、「replace」操作を使用できます。「replace」操作は接続フィールドを完全に置換しますが、既存のユーザーまたはユーザーグループの権限は保持されることにご留意ください。たとえば、上記で作成した接続を置換するには、それぞれに対して「replace」パッチを送信します。

```bash
cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/connections' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Guacamole-Token: TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
  -d '@-'
[
  {
    "op": "replace",
    "path": "/1",
    "value": {
      "parentIdentifier": "ROOT",
      "name": "conn1 ssh (updated)",
      "protocol": "ssh",
      "parameters": {
        "hostname": "conn1-new.web.com",
        "color-scheme": "white-black",
        "username": "${KEEPER_SERVER_USERNAME}", 
        "private-key": "${KEEPER_SERVER_KEY}"
      },
      "attributes": {
        "guacd-encryption": "ssl"
      }
    }
  },
  {
    "op": "replace",
    "path": "/2",
    "value": {
      "parentIdentifier": "1",
      "name": "conn2 vnc (updated)",
      "protocol": "vnc",
      "parameters": {
        "hostname": "conn2-new.web.com",
        "username": "bob", 
        "password": "password12345"
      },
      "attributes": {}
    }
  }
]
```

### 既存の接続の完全な置換

既存の接続を完全に置換し、その接続に付与されたすべての権限をリセットするには、接続を削除して再作成する必要があります。「remove」と「add」操作のパッチのペアを使用して実行できます。たとえば、先に作成した接続を完全に置換するには、それぞれに対してパッチのペアを送信します。

```bash
cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/connections' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Guacamole-Token: TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
  -d '@-'
[
  {
    "op": "remove",
    "path": "/1"
  },
  {
    "op": "add",
    "path": "/",
    "value": {
      "parentIdentifier": "ROOT",
      "name": "conn1 ssh (completely replaced)",
      "protocol": "ssh",
      "parameters": {
        "hostname": "conn1-newest.web.com",
        "username": "${KEEPER_SERVER_USERNAME}", 
        "private-key": "${KEEPER_SERVER_KEY}"
      },
      "attributes": {}
    }
  },
  {
    "op": "remove",
    "path": "/2"
  },
  {
    "op": "add",
    "path": "/",
    "value": {
      "parentIdentifier": "1",
      "name": "conn2 vnc (completely replaced)",
      "protocol": "vnc",
      "parameters": {
        "hostname": "conn2-newest.web.com",
        "username": "carol", 
        "password": "password123456789"
      },
      "attributes": {}
    }
  }
]
```

### 接続へのアクセスの付与

ユーザーまたはユーザーグループに接続へのアクセスを付与するには、接続IDごとにアクセス付与のパッチを送信します。たとえば、ユーザー「KCM\_User\_1」にアクセスを付与するには、以下のパッチを送信します。

```bash
cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/users/KCM_User_1/permissions' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Guacamole-Token: TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
  -d '@-'
[
  {
    "op": "add",
    "path": "/connectionPermissions/1",
    "value": "READ"
  },
  {
    "op": "add",
    "path": "/connectionPermissions/2",
    "value": "READ"
  }
]
```

ユーザーグループに権限を付与するには、以下のエンドポイントを使用します。

`/api/session/data/{DATA_SOURCE}/userGroups/{GROUP_ID}/permissions`

以下は、その例です。

`/api/session/data/mysql/userGroups/KCM%20Administrators/permissions`

### ログアウト

APIの使用が完了したら、認証トークンを明示的に無効化する必要があります。

```bash
curl 'https://kcm.example.com/api/session' \
  -X 'DELETE' \
  -H 'Guacamole-Token: TG9YZW0GAXBZDW0GZG9SB3IGC2L0'
```

### エラー

パッチのリスト送信時にエラーが発生すると、全体のエラーが返り、パッチ固有のエラーも含まれます。以下は、同じ接続グループで同じ名前の既存接続を作成しようとした場合の例です。

```json
{
  "message": "The provided patches failed to apply.",
  "translatableMessage": {
    "key": "APP.TEXT_UNTRANSLATED",
    "variables": {
      "MESSAGE": "The provided patches failed to apply."
    }
  },
  "statusCode": null,
  "expected": null,
  "patches": [
    {
      "op": "add",
      "identifier": null,
      "path": "/",
      "error": {
        "key": "APP.TEXT_UNTRANSLATED",
        "variables": {
          "MESSAGE": "The connection \"KCM connection 1\" already exists."
        }
      }
    },
    {
      "op": "add",
      "identifier": null,
      "path": "/",
      "error": {
        "key": "APP.TEXT_UNTRANSLATED",
        "variables": {
          "MESSAGE": "The connection \"KCM connection 2\" already exists."
        }
      }
    }
  ],
  "type": "BAD_REQUEST"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.keeper.io/keeper-connection-manager/jp/using-keeper-connection-manager/creating-connections/batch-import-and-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.