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

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

​

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. Các thông tin nên được giữ một cách bí mật nhất, không được phép lộ lọt ở bất cứ đâu. Nếu khóa truy cập bị lộ lọt, bạn cần thu hồi chúng ngay lập tức. Biến môi trường (Environment variable) là một phương án được khuyến nghị để lưu trữ các khóa điều khiển này trong phiên sử dụng của bạn.

​

Với Linux/MacOS

export ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
export SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>

​

Với Windows

PowerShell

$Env:ACCESS_KEY_ID = '<YOUR_ACCESS_KEY_ID>'
$Env:SECRET_ACCESS_KEY = '<SECRET_ACCESS_KEY>'

Command Prompt

set ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
set SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>

Bạn cũng cần thiết lập giá trị api_base (mặc định là https://api.locker.io/locker_secrets). Nếu bạn cần thiết lập các tiêu đề tùy chỉnh, bạn cũng cần thiết lập giá trị headers trong tham số options. Bây giờ, bạn có thể sử dụng SDK để lấy hoặc đặt các giá trị:

from locker import Locker

api_base = "your_base_api.host"
locker = Locker(
    api_base=api_base,
    options={"headers": headers}
)

Bạn cũng có thể truyền các tham số của khóa truy cập trong hàm khởi tạo Locker() hoặc chỉnh sửa file xác thực (~/.locker/credentials), nhưng cách này không được chúng tôi khuyến khích sử dụng:

locker = Locker(
    access_key_id=os.get_env("<YOUR_ACCESS_KEY_ID>"),
    secret_access_key=os.get_env("<YOUR_SECRET_ACCESS_KEY>"),
    api_base=api_base,
    options={"headers": headers}
)

---

​

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.

secrets = locker.list()
for secret in secrets:
    print(secret.id, secret.key, secret.value)

---

​

Get giá trị secrets

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

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

secret = locker.create(key="YOUR_NEW_SECRET_KEY", value="YOUR_NEW_SECRET_VALUE")

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

secret = locker.create(key="YOUR_NEW_SECRET_KEY", value="YOUR_NEW_SECRET_VALUE", environment_name="staging")

---

​

Cập nhật secrets

Dùng hàm .modify() để cập nhật giá trị secrets:

secret = locker.modify(key="YOUR_NEW_SECRET_KEY", value="UPDATED_SECRET_VALUE")
print(secret.key, secret.value, secret.environment_name)

Cập nhật một giá trị bí mật bằng khóa bí mật và tên môi trường cụ thể:

secret = locker.modify(key="YOUR_NEW_SECRET_KEY", value="UPDATED_SECRET_VALUE", environment_name="staging")
print(secret.key, secret.value, secret.environment_name)

---

​

List environments

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

environments = locker.list_environments()
for env in environments:
    print(env.name, env.external_url)

---

​

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

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

new_environment = locker.create_environment(name="staging", external_url="staging.host")
print(new_environment.name, new_environment.external_url)

---

​

Cập nhật environment

Để cập nhật external_url của môi trường bằng tên, sử dụng .modify_environment():

environment = locker.modify_environment(name="staging", external_url="new.staging.host")

---

​

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/except của Python và bắt locker.error.LockerError hoặc các lớp con của nó để xử lý các ngoại lệ của Locker.

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	Invalid access_client_id or invalid secret_access_key
permission_denied	403	Permission Denied Error	locker.error.PermissionDeniedError	Your credential does not have enough permission to execute this operation
rate_limit	429	Rate Limit Error	locker.error.RateLimitError	Too many requests
not_found	404	Resource Not Found	locker.error.ResourceNotFoundError	The requested resource is not found
server_error	500	API Server Error	locker.error.APIServerError	Something went wrong on Locker’s end (These are rare)
http_error	503	API Connect Error	locker.error.APIConnectionError	The request to API server error. Check your network connection
cli_error	—	CLI Run Error	locker.error.CliRunError	The encryption/decryption binary runs error by invalid local data, process interruptions
locker_error	—	General Locker Error	locker.error.LockerError	The general error

---

​

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. Thiết lập biến môi trường LOCKER_LOG thành một trong các giá trị: debug, info, warning hoặc error

$ export LOCKER_LOG=debug

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

from locker import Locker

locker = Locker(log="debug")

3. Bật logging thông qua mô-đun logging của Python

import logging
logging.basicConfig()
logging.getLogger('locker').setLevel(logging.DEBUG)