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

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

​

Cài đặt access key

SDK cần được cấu hình với khóa truy cập của bạn, khóa này có sẵn trong Bảng điều khiển Locker Secrets của bạn. Khởi tạo secret_access_key thành giá trị của nó. Bạn cũng cần thiết lập giá trị api_base (mặc định là https://api.locker.io/locker_secrets).

import { Locker } from 'lockerpm'
// You should not hardcode access key credentials. Instead, load them from environment variables
const locker = new Locker({
  accessKeyId: process.env.LOCKER_ACCESS_KEY_ID,
  secretAccessKey: process.env.LOCKER_ACCESS_KEY_SECRET,
  apiBase: '<your base api url>'
})

Tất cả các tuỳ chọn khởi tạo được liệt kê dưới đây:

Key	Description	Type	Required
accessKeyId	Your access key id	string	✅
accessKeySecret	Your access key secret	string	✅
apiBase	Your server base API URL, default value is https://api.locker.io/locker_secrets	string	❌
headers	Custom headers for API calls	{[header: string]: string}	❌
unsafe	Set TLS to unsafe if you use a server with self-signed certificate, default value is false	boolean	❌
logLevel	Refer to Logging, default value is 1	number	❌

Bây giờ, bạn có thể sử dụng SDK để lấy hoặc đặt các giá trị.

---

​

Get secrets

Phương pháp:

• list: list all secrets

list: () => Promise<Secret[]>

• listSync: lấy tất cả secrets, nhưng được đồng bộ hoá

listSync: () => Secret[]

• get: lấy secrets theo khóa (key) và tên môi trường (tùy chọn, mặc định là môi trường TẤT CẢ), có thể trả về giá trị mặc định nếu không tìm thấy secret nào

get: (key: string, env?: string, defaultValue?: string) => Promise<string | undefined>

• getSync: lấy 1 secret nhưng được đồng bộ hoá

getSync: (key: string, env?: string, defaultValue?: string) => string | undefined

Ví dụ:

// Get list secrets quickly
const secrets = await locker.list()
// or
const secrets = locker.listSync()

// Get a secret value by secret key
// Replace 'ENVIRONMENT' with null or undefined for the enviroment ALL
const secretValue1 = await locker.get('SECRET_NAME_1')
const secretValue2 = await locker.get('SECRET_NAME_2', 'ENVIRONMENT')
const secretValue3 = await locker.get('SECRET_NAME_3', 'ENVIRONMENT', 'default value')
// or
const secretValue3 = locker.getSync('SECRET_NAME_3', 'ENVIRONMENT', 'default value')

---

​

Get a secret value

Hàm này sẽ lấy giá trị bí mật bằng một khóa. Nếu khóa không tồn tại, SDK sẽ trả về default_value

secret_value = locker.get("REDIS_CONNECTION", default_value="TheDefaultValue")
print(secret_value)

Bạn có thể lấy giá trị secrets bằng một khóa bí mật và tên môi trường cụ thể thông qua tham số environment_name Nếu khóa không tồn tại, SDK sẽ trả về giá trị mặc định.

secret_value = locker.get_secret(
	"REDIS_CONNECTION", 
	environment_name="staging", 
	default_value="TheDefaultValue"
)
print(secret_value)

---

​

Tạo mới secrets

Phương pháp:

• create: tạo một secret mới có tên, giá trị, tên môi trường (tùy chọn) và mô tả (tùy chọn). Bạn không thể tạo secrets bằng cùng một khóa trong cùng một môi trường. Trả về secret mới.

create: (data: { key: string; value: string; environmentName?: string; description?: string }) => Promise<Secret>

Ví dụ

// Create new secret
const secret1 = await locker.create({
  key: 'key',
  value: 'value',
	description: 'a new secret'
})

// This will throw an Error
const secret2 = await locker.create({
  key: 'key',
  value: 'value 2',
})

// Use another env, this will not throw an Error
const secret3 = await locker.create({
  key: 'key',
  value: 'value',
	environmentName: 'prod'
})

// This will throw an Error
const secret4 = await locker.create({
  key: 'key',
  value: 'value 2',
	environmentName: 'prod'
})

---

​

Cập nhật secrets

Phương pháp:

• modify: chỉnh sửa giá trị, tên môi trường hoặc mô tả của secret. Bạn không thể thay đổi secret’s key. Bạn cũng không thể thay đổi môi trường sang môi trường mới đã có secret có cùng tên. Trả về secret đã cập nhật.

modify: (key: string, env: string, data: { value: string; environmentName?: string; description?: string }) => Promise<Secret>

Ví dụ:

// Update the secret "key" of env "ALL"
const secret = await locker.modify('key', '', {
  value: 'value 2',
	description: 'desc'
})

// Update the secret "key" of env "prod"
const secret = await locker.modify('key', 'prod', {
  value: 'value 2',
	environmentName: 'prod'
})

// This will update the env from "prod" to "ALL"
const secret = await locker.modify('key', 'prod', {
  value: 'value 2'
})

// This will update the env from "ALL" to "prod"
const secret = await locker.modify('key', '', {
  value: 'value 2',
	environmentName: 'prod'
})

---

​

Get environments

Phương pháp:

• listEnvironments: Liệt kê tất cả môi trường

listEnvironments: () => Promise<Environment[]>

• listEnvironmentsSync: Liệt kê tất cả môi trường nhưng được đồng bộ

listEnvironmentsSync: () => Environment[]

• getEnvironment: lấy tất cả môi trường bằng tên

getEnvironment: (name: string) => Promise<Environment | undefined>

• getEnvironmentSync: lấy một môi trường nhưng được đồng bộ

getEnvironmentSync: () => Environment | undefined

Ví dụ:

// List environments
const environments = await locker.listEnvironments()
// or
const environments = locker.listEnvironmentsSync()

// Get an environment object by name
const environment = await locker.getEnvironment('prod')
// or
const environment = locker.getEnvironmentSync('prod')

---

​

Retrieve an environment

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

prod_env = locker.get_environment("prod")
print(prod_env.name, prod_env.external_url)

---

​

Tạo mới environment

Phương pháp:

• createEnvironment: tạo một môi trường mới có tên, url bên ngoài (external url) và mô tả (tùy chọn). Bạn không thể tạo môi trường có cùng tên. Trả về môi trường mới.

createEnvironment: (data: { name: string; externalUrl: string; description?: string }) => Promise<Environment>

Ví dụ:

// Create a new environment
const env1 = await locker.createEnvironment({
  name: 'prod',
  externalUrl: 'product.prod',
	description: 'testing'
})

// This will throw an error
const env2 = await locker.createEnvironment({
  name: 'prod',
  externalUrl: 'product.prod.example'
})

---

​

Cập nhật environment

Phương pháp:

• modifyEnvironment: chỉnh sửa mô tả và external url của môi trường. Bạn không thể thay đổi tên của môi trường. Trả về môi trường đã cập nhật.

modifyEnvironment: (name: string, data: { externalUrl: string; description?: string }) => Promise<Environment>

Ví dụ:

// Update an environment by name
const env = await locker.modifyEnvironment("name", {
  externalUrl: 'new value',
})

---

​

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ệ. Để bắt ngoại lệ, sử dụng cú pháp try/except của Python. Bắt locker.error.LockerError hoặc các lớp con của nó để xử lý các ngoại lệ chỉ định của Locker. Mỗi lớp con đại diện cho một loại ngoại lệ khác nhau. Khi bạn bắt ngoại lệ, bạn có thể sử dụng lớp của nó để chọn một phản hồi.

Ví dụ:

from locker import Locker
from locker.error import LockerError

# Create a new secret and handle error
try:
    new_secret = locker.create(key="YOUR_KEY", value="your_key_value", environment_name="staging")
    print(new_secret.key, new_secret.value, new_secret.description, new_secret.environment_name)
except LockerError as e:
    print(e.user_message)
    print(e.http_body)

Trong SDK, các đối tượng lỗi thuộc về locker.error.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.

Code	HTTP Status	Name	Class	Description
unauthorized	401	Authentication Error	locker.error.AuthenticationError	access_client_id hoặc secret_access_key không hợp lệ
permission_denied	403	Permission Denied Error	locker.error.PermissionDeniedError	Khóa truy cập không đủ quyền
rate_limit	429	Rate Limit Error	locker.error.RateLimitError	Quá nhiều requests
not_found	404	Resource Not Found	locker.error.ResourceNotFoundError	Tài nguyên không tìm thấy
server_error	500	API Server Error	locker.error.APIServerError	Locker server gặp vấn đề (Hiếm khi)
http_error	503	API Connect Error	locker.error.APIConnectionError	Lỗi network
cli_error	—	CLI Run Error	locker.error.CliRunError	Binary thực hiện mã hóa/giải mã lỗi do dữ liệu cục bộ không hợp lệ hoặc tiến trình bị ngắt
locker_error	—	General Locker Error	locker.error.LockerError	Lỗi chung

---

​

Logging

Thư viện có thể được cấu hình để phát ra thông tin đăng nhập giúp bạn hiểu rõ hơn về những gì đang diễn ra. Có một số cấp độ NONE (0), ERROR (1), DEBUG (2). Đặt mức độ log khi tạo phiên bản Locker để kích hoạt.

const locker = new Locker({
  // ...
  logLevel: 1  // default is ERROR
})