# Keeper表記法

## 概要

Keeperノーテーションは、Keeperシークレットマネージャー[SDK](https://docs.keeper.io/keeperpam/secrets-manager/developer-sdk-library)および[統合機能](https://docs.keeper.io/keeperpam/secrets-manager/integrations)でKeeperレコードのフィールドを紹介するために使用されます。利用できるさまざまなレコードタイプとフィールド名については、[こちらのページ](https://docs.keeper.io/jp/keeperpam/secrets-manager/about/field-record-types)をご参照ください。

## 表記法

{% tabs %}
{% tab title="形式" %}
**`keeper://<TITLE/UID>/<type|title|notes>`**

**`keeper://<TITLE/UID>/file/<filename|title|fileUID>`**

**`keeper://<TITLE/UID>/<field|custom_field>/<label|type>[[predicate1][predicate2]]`**

表記は4つの部分に分かれています。

* シークレットレコードのタイトルまたはUID
* レコードデータのセレクタ。以下の3種類があります。
  * ショートセレクタ: `type`、`title`、`notes`など、追加のパラメータなしで使用されるタイプ。
  * ファイルセレクタ: 1つのパラメータ (ファイル名、タイトル、UID) を指定できます。
  * フルセレクタ: フィールドタイプ (`field`や`custom_field`) を指定し、追加のパラメータを必要とします。
* フルセレクタのパラメータ\
  フルセレクタで使用されるパラメータは、レコード内の固有のフィールドを選択するフィールド**タイプ**または**ラベル**を指定する必要があります。述部はオプションです。
* 述部は、フィールド値のより詳細なオプションインデックスです。最初の述部は値の配列への数値インデックスで、2番目のインデックスは複合値の場合のプロパティインデックスです (例: .../custom\_field/name\[1]\[middle])。

{% hint style="warning" %}
最初の述部は、2番目の述部を使用するために常に必要となります。以下の例のどちらかを使用してください。

* `phone[0][number]`: 「phone」配列の最初のレコード (インデックス0) のみを取得します (配列に項目が1つしかない場合でも)。
* `phone[][number]`: 「phone」配列のすべてのレコードから「number」を取得し、CSV形式でリストを返します。
  {% endhint %}

**述部**

述部を使用すると、値にきめ細かくアクセスできます。値は、1つの値の場合もあれば、値の配列の場合もあり、それぞれの値が文字列の場合もあれば、値の連想配列の場合もあります。

**配列**

述部が定義されていない場合は、1つの値のみが返されます。\
戻り値に値の配列が含まれている場合は、最初の値のみが返されます。\
数値を指定する述部が定義されている場合は (`phone[0]`など)、そのインデックスの値が返されます。\
インデックスは0から始まります。

値を指定しない述部が定義されている場合は (`phone[]`など)、配列値が返されます。

**サブフィールド**

以下のように、一部のフィールドは他のサブフィールドで構成されています。

```
"fields": [
    { "type": "name", "value": [ 
        {"first:": "John", "last": "Doe"},
        {"first:": "Jane", "last": "Doe"} ]
    },
    { "type": "phone", "value": [
        {"number": "555-5555555", "ext": "55"}, 
        {"number": "777-7777777", "ext": "77"} ]
    }
]
```

サブフィールドにアクセスするには、フィールド名を英数字の述部として含めます。\
たとえば、`name[last]`は上の例では「Doe」を返し、`name[first]`は「John」を返します。

**混合型**

以下のように、配列とサブフィールドを組み合わせた値もあります。

```
[
    {"number":"555-5555555", "ext":"55"},
    {"number":"777-7777777", "ext":"77"},
    {"number":"888-8888888", "ext": "", "type":"Home"},
    {"number":"999-9999999", "type":"Work"}
]
```

特定の値を取得するには、最初の数値述部を使用して全体の値を取得できます。例えば、`phone[1]`は、2番目のphoneの全体の値`{"number": "777-7777777", "ext": "77"}`を返します。

特定のサブフィールドを取得するには、2つの述部を使用する必要があります。例えば、`phone[1][number]`は、2番目のphoneのレコードのnumberのみを返します。
{% endtab %}

{% tab title="例" %}
これらの例を参考にして、Keeper表記法によるクエリを作成してください。 各例でのレコードUIDはサンプルです。

{% hint style="warning" %}
Keeper表記法を利用する場合は、例にあるUIDを実際のレコードのレコードUIDに置き換えてください。
{% endhint %}

**レコードのタイプ、タイトル、メモを照会する**\
`keeper://EG6KdJaaLG7esRZbMnfbFA/type`\
`keeper://EG6KdJaaLG7esRZbMnfbFA/title`\
`keeper://EG6KdJaaLG7esRZbMnfbFA/notes`

**ログインレコードのパスワードを照会する**\
`keeper://EG6KdJaaLG7esRZbMnfbFA/field/password`\
戻り値: `RX$u!h!pBzDGhR4Jr6#b` (レコードからランダムに生成されたパスワード)

**連絡先のレコードからファーストネームを照会する**\
`keeper://3FXqmP5nFKwju0H8pl0DmQ/field/name[first]`

戻り値: `'Craig'`

**レコードからファイルを照会する**\
`keeper://bf3dg-99-JuhoaeswgtFxg/file/credentials.txt`

戻り値: `b"jNxmJkhbZ[...]6jQtE"` (credentials.txtの内容)

**ラベルが「code」のカスタム暗証番号フィールドを照会する**

`keeper://aj3dg-9ecJuhoa-sdyehg/custom_field/code`

戻り値: `5876` (暗証番号)

**ログインレコードの二要素コードフィールドを照会する**

`keeper://aj3dg-9ecJuhoa-sdyehg/field/oneTimeCode`

戻り値: `5876891`

**複数のカスタムフィールド電話番号の2番目を照会する**

`keeper://aj3dg-9ecJuhoa-sdyehg/custom_field/phone[1]`

戻り値: `{"number":"555-555-5555", "type": "home"}`

**この電話フィールドの番号だけを取得する**

`keeper://aj3dg-9ecJuhoa-sdyehg/custom_field/phone[1][number]`

戻り値: `"555-555-5555"`

**レコードにあるすべての電話番号を配列として取得する**

`keeper://aj3dg-9ecJuhoa-sdyehg/custom_field/phone[]`

戻り値:

```javascript
[
  {"number":"123-456-7890", "type": "work"},
  {"number":"555-555-5555", "type": "home"}
]
```

{% endtab %}
{% endtabs %}

## 名前でレコードを取得

KeeperシークレットマネージャーSDKでは、レコード名でレコードを取得するKeeper表記法をサポートしています。

### 表記文字のエスケープ

レコードのどこかに「/」「\」「\[」「]」が含まれている場合は、その文字をバックスラッシュでエスケープする必要があります。これらの記号は、内部セクションおよびインデックスの区切り文字として表記法で使用され、レコードタイトル、フィールドラベル、ファイル名に含まれる場合はエスケープする必要があります。

例:

タイトル: Twitter Login \[Marketing]\
`keeper://Twitter Login \[Marketing\]/field/password`\
ラベルが「/. links」のURLカスタムフィールド\
`keeper://My Slashdot Links/custom_field/\/.links[]` (すべてのリンク)\
`keeper://My Slashdot Links/custom_field/\/.links[1]` (2番目のリンクのみ)\
ファイル名: creds\[2].crt\
`keeper://My \/.Credentials/file/creds\[2\].crt`

### 名前を使用した環境切替の簡略化

Keeper表記法のレコードタイトル取得機能を使用すると、一度Keeper表記法で記述したクエリを、異なるビルド環境で異なるシークレットマネージャーアプリケーションを活用して再利用することができます。

例:

この例では、2つの共有フォルダを作成しました。1つは開発環境用、もう1つは本番用です。 それぞれのフォルダ内には、同じ名前のレコードがあります。 これらのレコードは同じ名前ですが、格納されているクレデンシャルは異なります。

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fd9nmUsXHvuMnIDcvxYHT%2Fimage.png?alt=media&#x26;token=abc07b21-bdc1-44ff-96c6-d30675e16a06" alt=""><figcaption></figcaption></figure>

それぞれの共有フォルダは、異なるシークレットマネージャーアプリケーションに関連付けられます。

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2FLpzl5bD46LWfTxwTSduW%2Fimage.png?alt=media&#x26;token=c1b01f3f-51e7-4252-9ba3-34babdf37a10" alt=""><figcaption></figcaption></figure>

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2FUYMikjYX9dRQDFMJ9O1a%2Fimage.png?alt=media&#x26;token=c986bda5-49ae-415a-8448-a88d4fa9f994" alt=""><figcaption></figcaption></figure>

関連するシークレットマネージャー統合で、以下のように表記法を使用してクレデンシャルを取得します。\
`keeper://MySQL Creds/fields/password`\
\
開発ビルドで使用される統合では、「Development Environment」フォルダに関連付けられたシークレットマネージャーアプリケーションを使用します。その後、プロダクションビルドを行う際には、関連付けられたシークレットマネージャーアプリケーションを「Production Environment」に変更するだけで、コードやスクリプトの変更は必要ありません。