> ## Documentation Index
> Fetch the complete documentation index at: https://support.locker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hướng dẫn sử dụng

> Hướng dẫn sử dụng Locker Secrets Manager SDK cho Java

## Cài đặt access key

SDK cần được cấu hình với khóa truy cập của bạn (bao gồm id của khóa, và khóa truy cập), khóa này có sẵn ở trang quản lý Locker Secrets. Các khóa này phải không được tiết lộ. Nếu bạn để lộ khóa, bạn cần thu hồi chúng ngay lập tức. Biến môi trường là một giải pháp tốt và dễ sử dụng trong hầu hết các ngôn ngữ lập trình.

### Thiết lập thông tin xác thực trên Linux/MacOS

```bash theme={null}
export ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
export SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
```

### Thiết lập thông tin xác thực trên Windows

**PowerShell**

```powershell theme={null}
$Env:ACCESS_KEY_ID = '<YOUR_ACCESS_KEY_ID>'
$Env:SECRET_ACCESS_KEY = '<SECRET_ACCESS_KEY>'
```

**Command Prompt**

```bash theme={null}
set ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
set SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
```

Bạn cũng cần đặt giá trị `api_base` (mặc định là `https://api.locker.io/locker_secrets`). Nếu bạn cần thiết lập `header` tùy chỉnh, bạn cũng cần đặt giá trị `headers` trong tham số `option`:

```java theme={null}
Map<String, String> headers = new HashMap<String, String>() {
    {
        put("CF-Access-Client-Id", "YOUR_CF_ACCESS_CLIENT_ID");
        put("CF-Access-Client-Secret", "YOUR_CF_ACCESS_CLIENT_SECRET");
    }
};
LockerResponseGetterOptions responseGetter = new LockerClient.LockerClientBuilder()
        .setApiBase("YOUR_API_BASE")
        .setHeaders(headers)
        .buildOptions();
LockerClient client = new LockerClient(new LiveLockerResponseGetter(responseGetter));
```

Bạn cũng có thể truyền vào tham số hoặc sử dụng tệp thông tin xác thực được chia sẻ ( `~/.locker/credentials` ), nhưng chúng tôi không khuyến khích bạn thực hiện theo những cách này.

```java theme={null}
import locker.LockerClient;
import locker.exception.LockerError;
import locker.model.Secret;
import locker.param.secret.SecretRetrieveParams;

public class LockerExample {
    public static void main(String[] args) {
        LockerClient client = new LockerClient("YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET");
        try {
            Secret secret = client.secrets().retrieve("YOUR_SECRET_KEY", Secret.class);
            System.out.println(secret);
        } catch (LockerError e) {
            e.printStackTrace();
        }
    }
}
```

***

## List secrets

Sử dụng phương thức `.list()` để lấy tất cả các secret trong dự án của bạn.

```java theme={null}
String secrets = client.secrets().list(String.class);

/**
 *  return a list of secrets
 * */

Class<? super LockerCollection<Secret>> type = new TypeToken<LockerCollection<Secret>>() {
}.getRawType();
LockerCollection<Secret> secretList = (LockerCollection<Secret>) client.secrets().list(type);
```

***

## Get giá trị secrets

### Lấy giá trị bằng tên khóa

```java theme={null}
// Get a secret by secret key
Secret secret = client.secrets().retrieve("java_key_1", Secret.class);
String secretValue = client.secrets().retrieve("java_key_1", String.class);
```

### Lấy giá trị bằng tên khóa và tên môi trường

Bạn có thể lấy giá trị bí mật bằng tên khóa và tên môi trường:

```java theme={null}
// Get a secret by secret key and specific environment name
Secret secret = client.secrets().retrieve("java_key_1", Secret.class, "env_name");
String secretValue = client.secrets().retrieve("java_key_1", String.class, "env_name");
```

***

## Tạo mới secrets

Dùng hàm `.create()` để tạo mới secret:

```java theme={null}
SecretCreateParams createParams = new SecretCreateParams.Builder()
        .setKey("key")
        .setValue("value")
        .setDescription("description")
        .build();
Secret newSecret = client.secrets().create(createParams, Secret.class);
```

Tạo một secret mới với một môi trường cụ thể:

```java theme={null}
SecretCreateParams createParams = new SecretCreateParams.Builder()
        .setKey("key")
        .setValue("value")
        .setDescription("description")
        .setEnvironment("environment")
        .build();
Secret newSecret = client.secrets().create(createParams, Secret.class);
```

***

## Cập nhật secrets

```java theme={null}
SecretUpdateParams updateParams = new SecretUpdateParams.Builder()
        .setKey("your_update_secret_key")
        .setValue("your_update_secret_value")
        .setDescription("your_update_secret_description")
        .build();

// Update a secret by secret key
Secret updatedSecret = client.secrets().modify("your_secret_key", updateParams, Secret.class);

// Update a secret by secret key and specific environment name
Secret updatedSecret = client.secrets().modify("your_secret_key", updateParams, Secret.class, "your_secret_env_name");
```

***

## List environments

Dùng hàm `.list()` để lấy tất cả các môi trường trong dự án của bạn:

```java theme={null}
Class<? super LockerCollection<Environment>> type = new TypeToken<LockerCollection<Environment>>() {
}.getRawType();
LockerCollection<Environment> listEnvs = (LockerCollection<Environment>) client.environments().list(type);

// Hoặc lấy dạng chuỗi JSON
String envs = client.environments().list(String.class);
```

***

## Retrieve an environment

Để lấy một môi trường theo tên, sử dụng `.retrieve()`:

```java theme={null}
Environment environment = client.environments().retrieve("your_env_name", Environment.class);
```

***

## Tạo mới environment

Để tạo mới môi trường, sử dụng `.create()`:

```java theme={null}
EnvironmentCreateParams createEnvParams = EnvironmentCreateParams.builder()
        .setName("your_env_name")
        .setExternalUrl("your_env_external_url")
        .setDescription("your_env_description")
        .build();
Environment newEnv = client.environments().create(createEnvParams, Environment.class);
```

***

## Cập nhật environment

```java theme={null}
EnvironmentUpdateParams params = EnvironmentUpdateParams.builder()
        .setName("your_update_env_name")
        .setExternalUrl("your_update_env_external_url")
        .setDescription("your_update_env_description")
        .build();
Environment updatedEnv = client.environments().modify("your_env_name", params, Environment.class);
```

***

## Error Handling

SDK của Locker Secret cung cấp một số loại lỗi. Chúng có thể phản ánh các sự kiện bên ngoài, như thông tin đăng nhập không hợp lệ, gián đoạn kết nối mạng, hoặc các vấn đề về mã lỗi như các cuộc gọi API không hợp lệ.

Nếu một vấn đề ngay lập tức ngăn chặn một hàm tiếp tục, SDK sẽ ném ra một ngoại lệ. Đây là một thực hành tốt để bắt và xử lý các ngoại lệ. Sử dụng cú pháp **`try/catch`** của Java và bắt **`LockerError`** hoặc các lớp con của nó để xử lý các ngoại lệ của Locker.

```java theme={null}
LockerClient client = new LockerClient(
    "95443edf-eb33-4fae-a66d-c264d14e7217",
    "C+NCA5fwzJeCh3R4O3Dw4YLAbJrrvgJt1bJSe1BEhrY="
);
SecretCreateParams params = SecretCreateParams.builder()
    .setValue("your_secret_value")
    .setKey("your_secret_key")
    .setDescription("your_secret_description")
    .build();
try {
    Secret newSecret = client.secrets().create(params, Secret.class);
} catch (LockerError e) {
    e.printStackTrace();
}
```

Trong SDK, các đối tượng lỗi thuộc về `LockerError` và các lớp con của nó. Sử dụng tài liệu cho mỗi lớp để biết cách phản ứng.

| **Name**                | **Class**                            | **Description**                                                                                                                   |
| ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| Authentication Error    | `locker.error.AuthenticationError`   | Invalid `access_client_id` or invalid `secret_access_key`                                                                         |
| Permission Denied Error | `locker.error.PermissionDeniedError` | Your credential does not have enough permission to execute this operation                                                         |
| RateLimit Error         | `locker.error.RateLimitError`        | Too many requests                                                                                                                 |
| API Error               | `locker.error.APIError`              | You made an API call with the wrong parameters, in the wrong state, or in an invalid way, or something went wrong on Locker's end |
| CLI Run Error           | `locker.error.CliRunError`           | The encryption/decryption binary runs errors by invalid local data, process interruptions, or invalid `secret_access_key`         |

***

## Logging

Thư viện có thể được cấu hình để phát ra thông tin logging giúp bạn hiểu rõ hơn về những gì đang diễn ra. Có một số cấp độ: `debug`, `info`, `warning`, `error`.

Cấp độ `info` thường phù hợp nhất cho việc sử dụng trong môi trường production, nhưng `debug` cũng có sẵn để có thêm chi tiết.

### Cách kích hoạt logging

**1. Đặt biến môi trường `LOCKER_LOG`**

```bash theme={null}
export LOCKER_LOG=debug
```

**2. Đặt `log` khi khởi tạo đối tượng LockerClient**

```java theme={null}
LockerClient client = new LockerClient.LockerClientBuilder()
        .setAccessKeyId("YOUR_ACCESS_KEY_ID")
        .setSecretAccessKey("YOUR_SECRET_ACCESS_KEY")
        .setLogLevel("debug")
        .build();
```