Python-SDK-Anleitung
Verwenden Sie das offizielle AWS SDK für Python (Boto3) mit RustFS.
Überblick
RustFS enthält keine eigenen SDKs. Der Dienst ist S3-kompatibel, daher verwenden Sie das offizielle AWS SDK für Python, Boto3, und richten es auf Ihren RustFS-Server aus.
Diese Anleitung behandelt:
- das Erstellen und Löschen von Buckets
- das Hochladen, Herunterladen und Löschen von Objekten
- das Auflisten von Objekten
- das Erzeugen vorsignierter URLs
- den mehrteiligen Upload für große Dateien
Voraussetzungen
- Python 3.8 oder höher
- Eine laufende RustFS-Instanz (siehe Installationsanleitung). Die S3-API nimmt Verbindungen auf Port
9000entgegen, die Console (Weboberfläche) auf Port9001 - Zugriffsschlüssel, die Sie bei der Installation über die Umgebungsvariablen
RUSTFS_ACCESS_KEYundRUSTFS_SECRET_KEYsetzen (siehe Zugriffsschlüssel-Verwaltung)
Lokaler Test
Wenn Sie bei der Installation keine Anmeldedaten gesetzt haben, verwendet der Server standardmäßig rustfsadmin / rustfsadmin. Das reicht für einen wegwerfbaren lokalen Test, niemals für eine Instanz, die andere erreichen können.
2.1 Boto3 installieren
Wir empfehlen eine virtuelle Umgebung:
python3 -m venv venv
source venv/bin/activate
pip install boto3Boto3 hängt von
botocoreab. Das Paket wird automatisch installiert.
Verbindung mit RustFS
Das folgende Skript ist vollständig und ausführbar. Ersetzen Sie localhost durch die IP-Adresse Ihres Servers, wenn RustFS auf einem anderen Rechner läuft, und tragen Sie Ihre eigenen Zugriffsschlüssel ein:
import boto3
from botocore.client import Config
s3 = boto3.client(
's3',
endpoint_url='http://localhost:9000',
aws_access_key_id='<your-access-key>',
aws_secret_access_key='<your-secret-key>',
region_name='us-east-1',
config=Config(
signature_version='s3v4',
s3={'addressing_style': 'path'},
),
)
response = s3.list_buckets()
for bucket in response['Buckets']:
print(bucket['Name'])Führen Sie es aus:
python main.pyErläuterung der Client-Parameter
endpoint_url: zeigt auf Ihre RustFS-S3-API (Port9000, nicht der Port9001der Console)signature_version='s3v4': RustFS unterstützt v4-Signaturenregion_name='us-east-1': die Standardregion von RustFSaddressing_style='path': RustFS verwendet standardmäßig pfadbasierte Adressierung (Path-Style). Für die Adressierung im Virtual-Hosted-Stil istRUSTFS_SERVER_DOMAINSerforderlich
Grundlegende Operationen
4.1 Bucket erstellen
bucket_name = 'my-bucket'
try:
s3.create_bucket(Bucket=bucket_name)
print(f'Bucket {bucket_name} created.')
except s3.exceptions.BucketAlreadyOwnedByYou:
print(f'Bucket {bucket_name} already exists.')Bucket my-bucket created.4.2 Datei hochladen
s3.upload_file('/path/to/hello.txt', bucket_name, 'hello.txt')
print('File uploaded.')File uploaded.4.3 Datei herunterladen
s3.download_file(bucket_name, 'hello.txt', 'hello-downloaded.txt')
print('File downloaded.')File downloaded.4.4 Objekte auflisten
response = s3.list_objects_v2(Bucket=bucket_name)
for obj in response.get('Contents', []):
print(f"- {obj['Key']} ({obj['Size']} bytes)")- hello.txt (12 bytes)4.5 Objekt und Bucket löschen
s3.delete_object(Bucket=bucket_name, Key='hello.txt')
print('Object deleted.')
s3.delete_bucket(Bucket=bucket_name)
print('Bucket deleted.')Object deleted.
Bucket deleted.Erweiterte Funktionen
5.1 Vorsignierte URLs erzeugen
5.1.1 Download-Link (GET)
url = s3.generate_presigned_url(
ClientMethod='get_object',
Params={'Bucket': bucket_name, 'Key': 'hello.txt'},
ExpiresIn=600, # expires in 10 minutes
)
print('Presigned GET URL:', url)Presigned GET URL: http://localhost:9000/my-bucket/hello.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&...5.1.2 Upload-Link (PUT)
url = s3.generate_presigned_url(
ClientMethod='put_object',
Params={'Bucket': bucket_name, 'Key': 'upload-by-url.txt'},
ExpiresIn=600,
)
print('Presigned PUT URL:', url)Sie können mit curl hochladen:
curl -X PUT --upload-file /path/to/hello.txt "http://localhost:9000/my-bucket/upload-by-url.txt?X-Amz-Algorithm=..."5.2 Mehrteiliger Upload
Verwenden Sie den mehrteiligen Upload für Dateien über 10 MB, wenn Sie jeden Teil steuern müssen.
file_path = 'largefile.bin'
key = 'largefile.bin'
part_size = 5 * 1024 * 1024 # 5 MB
# 1. Start upload
response = s3.create_multipart_upload(Bucket=bucket_name, Key=key)
upload_id = response['UploadId']
parts = []
try:
with open(file_path, 'rb') as f:
part_number = 1
while True:
data = f.read(part_size)
if not data:
break
part = s3.upload_part(
Bucket=bucket_name,
Key=key,
PartNumber=part_number,
UploadId=upload_id,
Body=data,
)
parts.append({'ETag': part['ETag'], 'PartNumber': part_number})
print(f'Uploaded part {part_number}')
part_number += 1
# 2. Complete upload
s3.complete_multipart_upload(
Bucket=bucket_name,
Key=key,
UploadId=upload_id,
MultipartUpload={'Parts': parts},
)
print('Multipart upload complete.')
except Exception as e:
# Abort upload
s3.abort_multipart_upload(Bucket=bucket_name, Key=key, UploadId=upload_id)
print('Multipart upload aborted due to error:', e)Uploaded part 1
Uploaded part 2
Uploaded part 3
Multipart upload complete.Fehlerbehebung
| Problem | Ursache | Lösung |
|---|---|---|
SignatureDoesNotMatch | Es wird keine v4-Signatur verwendet | Setzen Sie signature_version='s3v4' |
EndpointConnectionError | Falsche RustFS-Adresse, oder der Dienst ist nicht gestartet | Prüfen Sie den Endpunkt und den Status des RustFS-Dienstes |
AccessDenied | Falsche Zugangsdaten oder unzureichende Berechtigungen | Prüfen Sie Zugriffsschlüssel, geheimen Zugriffsschlüssel und die Bucket-Richtlinien |
PermanentRedirect oder falsche Bucket-URL | Pfadbasierte Adressierung ist nicht aktiviert | Setzen Sie in der Config den Wert s3={'addressing_style': 'path'} |
Anhang: Kurzes Skript zum Hoch- und Herunterladen
def upload_file(local_path, bucket, object_key):
s3.upload_file(local_path, bucket, object_key)
print(f"Uploaded {local_path} to s3://{bucket}/{object_key}")
def download_file(bucket, object_key, local_path):
s3.download_file(bucket, object_key, local_path)
print(f"Downloaded s3://{bucket}/{object_key} to {local_path}")Weitere Operationen (Objekt-Tagging, Bucket-Richtlinien und mehr) stehen in der Boto3-S3-Dokumentation. Die meisten S3-Operationen funktionieren gegenüber RustFS auf dieselbe Weise. Ausnahmen stehen unter S3-Kompatibilität.
Wenn Sie native asynchrone Unterstützung und vollständige Typhinweise bevorzugen, funktioniert auch das von der Community entwickelte SDK capo mit RustFS. Lesen Sie die Integrationsanleitung für capo (Python).