Eine Datei mit Boto3 zu Amazon S3 hochladen

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Mit upload_file() von Boto3 senden Sie eine lokale Datei an einen bestehenden privaten S3-Bucket. Diese Anleitung liefert einen Befehl, der ein explizites Ziel entgegennimmt, auf den Abschluss des Uploads wartet und bei einem Datei- oder Übertragungsfehler mit einem Fehlerstatus endet. Zugangsdaten und Bucket-Berechtigungen bleiben in Ihrer AWS-Konfiguration.

Der verwaltete Upload von Boto3 übernimmt mehrteilige Übertragungen großer Dateien. Sie geben Dateiname, Bucket-Name und Objektschlüssel an; die Datei müssen Sie nicht selbst aufteilen.

Umgebung vorbereiten

Die folgenden Befehle verwenden Bash und Python 3.12 mit venv und pip unter Linux. Das Beispiel verwendet Boto3 1.43.100. Bevor Sie es ausführen, benötigen Sie:

Einen bestehenden privaten S3-Bucket für allgemeine Zwecke, seine AWS-Region und ein Präfix, unter dem Sie schreiben dürfen, etwa incoming/. Lassen Sie S3 Block Public Access aktiviert.
Ein authentifiziertes AWS-Profil. Verwenden Sie auf einem Arbeitsplatzrechner die temporären Zugangsdaten Ihrer Organisation, etwa ein IAM-Identity-Center-Profil. Schließen Sie diese Einrichtung zuerst ab. Für ein bestehendes Profil namens uploads erneuern Sie die Sitzung mit aws sso login --profile uploads über AWS CLI v2. Speichern Sie keine Zugriffsschlüssel im Skript.
Die Berechtigung, s3:PutObject auf den Zielobjekten auszuführen, zum Beispiel arn:aws:s3:::your-bucket-name/incoming/*. Erlauben Sie für diesen Bereich s3:AbortMultipartUpload, um fehlgeschlagene mehrteilige Uploads zu bereinigen. Siehe die Berechtigungen für mehrteilige Uploads von AWS. Das Skript listet keine Objekte auf und lädt keine herunter. Daher benötigt es weder s3:ListBucket noch s3:GetObject.

Erstellen Sie ein neues Verzeichnis und eine isolierte Python-Umgebung. Die Befehlskette mit && stoppt, wenn ein Schritt fehlschlägt. Falls boto3-upload bereits existiert, wählen Sie vor dem Fortfahren einen anderen Verzeichnisnamen.

mkdir boto3-upload &&
cd boto3-upload &&
python3 -m venv .venv &&
.venv/bin/python -m pip install 'boto3==1.43.100'

Arbeiten Sie nach erfolgreicher Installation im Verzeichnis boto3-upload weiter. Der folgende Befehl setzt das Profil uploads und us-east-1 voraus. Ersetzen Sie diese durch Ihr Profil und die Region des Buckets. Die Zugangsdatenkette von Boto3 kann auf AWS auch eine zugewiesene IAM-Rolle verwenden. Lassen Sie in dieser Umgebung AWS_PROFILE weg, statt Zugangsdaten vom Arbeitsplatzrechner auf den Server zu kopieren. Zugangsdaten aus der Umgebung können Vorrang vor einem Profil haben. Entfernen Sie daher veraltete Zugangsdatenüberschreibungen aus Ihrer Shell, falls Boto3 die falsche Identität auswählt.

Upload-Befehl speichern

Speichern Sie dieses vollständige Programm als upload.py im neuen Verzeichnis. Es akzeptiert eine reguläre Datei, auch eine leere, und weist einen fehlenden Pfad oder ein Verzeichnis zurück, bevor es einen S3-Client erstellt.

import argparse
import sys
from pathlib import Path

import boto3
from boto3.exceptions import S3UploadFailedError
from botocore.exceptions import BotoCoreError, ClientError


def main():
    parser = argparse.ArgumentParser(description="Upload one file to S3.")
    parser.add_argument("file", type=Path, help="Local file to upload")
    parser.add_argument("bucket", help="Existing S3 bucket name")
    parser.add_argument("key", help="Full destination object key")
    args = parser.parse_args()
    if not args.bucket or not args.key:
        parser.error("bucket and key must not be empty")

    try:
        if not args.file.is_file():
            parser.error("file must be an existing regular file")
        s3 = boto3.client("s3")
        s3.upload_file(str(args.file), args.bucket, args.key)
    except (S3UploadFailedError, BotoCoreError, ClientError, OSError) as error:
        print(f"Upload failed ({type(error).__name__}).", file=sys.stderr)
        return 1

    print(f"Uploaded to s3://{args.bucket}/{args.key}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

Die Upload-Implementierung gibt bei Erfolg None zurück und löst bei einem Fehler eine Ausnahme aus. Prüfen Sie den Rückgabewert nicht auf seinen Wahrheitswert. Das Programm gibt erst nach Abschluss des Aufrufs eine Erfolgsmeldung aus und fängt sowohl Fehler der verwalteten Übertragung als auch Fehler auf SDK- oder Dateisystemebene ab. Es meldet den Ausnahmetyp, ohne die vollständige Dienstantwort auszugeben.

Der Client verwendet standardmäßig HTTPS mit Zertifikatsprüfung. Behalten Sie diese Standardeinstellungen für AWS bei und entfernen Sie benutzerdefinierte Endpunktüberschreibungen, die von lokalen Tests übrig sind. Verschlüsselung im Ruhezustand und Zugriffsberechtigungen sind separate Einstellungen, die weiter unten behandelt werden.

Mit einem expliziten Objektschlüssel ausführen

Wählen Sie eine lokale Datei und ihr Ziel, bevor Sie den Befehl ausführen. Hier ist ./report.pdf eine bestehende Datei, die Sie in boto3-upload ablegen; Sie können einen anderen Pfad einsetzen. Ersetzen Sie your-bucket-name durch Ihren Bucket-Namen, ohne das Präfix s3://.

AWS_PROFILE=uploads AWS_DEFAULT_REGION=us-east-1 \
  .venv/bin/python upload.py './report.pdf' 'your-bucket-name' 'incoming/report.pdf'

Der Schlüssel ist der vollständige Name innerhalb des Buckets. S3 leitet ihn weder aus dem lokalen Pfad ab noch hängt es den Dateinamen an incoming/ an. Setzen Sie Pfade und Schlüssel mit Leerzeichen in Anführungszeichen. Bei einem lokalen Dateinamen, der mit einem Bindestrich beginnt, geben Sie das Präfix ./ mit an.

Für das oben gezeigte Ziel lautet die Ausgabe bei Erfolg:

Uploaded to s3://your-bucket-name/incoming/report.pdf

Wenn Sie diesen Befehl erneut ausführen, schreibt er ohne Rückfrage erneut unter demselben Schlüssel. In einem Bucket ohne Versionierung ersetzt das das bestehende Objekt. Bei aktivierter Versionierung speichert S3 eine neue Version. Verwenden Sie einen anderen Schlüssel, wenn Sie Uploads getrennt aufbewahren müssen. Siehe das Verhalten beim Überschreiben und bei der Versionierung von AWS.

Verwenden Sie für einen Scheduler oder ein anderes Skript den Prozessstatus: 0 bedeutet, dass der Upload abgeschlossen wurde, 1 steht für einen abgefangenen Upload-Fehler und 2 für ungültige Argumente oder eine fehlende Eingabe beziehungsweise eine Eingabe, die keine Datei ist. Die lokale Datei bleibt erhalten. Bei einem Verbindungsfehler kann das Ergebnis auf der Gegenseite ungewiss sein, wenn S3 eine Anfrage angenommen hat, bevor die Antwort verloren ging. Prüfen Sie das Ziel vor einem erneuten Versuch, wenn eine doppelte Version relevant wäre. Lassen Sie die Quelldatei während des Uploads unverändert.

Verschlüsselungseinstellungen des Buckets verwenden

Amazon S3 verschlüsselt alle neuen Objekte im Ruhezustand. SSE-S3 mit AES256 ist die anfängliche Standardeinstellung des Buckets und verursacht keine zusätzlichen Verschlüsselungskosten. Administratoren können einen anderen Standard wie SSE-KMS wählen. Da dieses Programm keine Verschlüsselungsüberschreibung sendet, verwendet S3 die konfigurierte Standardeinstellung des Buckets.

Für SSE-KMS benötigt die hochladende Identität kms:GenerateDataKey für den Schlüssel; mehrteilige Uploads benötigen außerdem kms:Decrypt. Der Schlüssel muss sich in der Region des Buckets befinden und seine Schlüsselrichtlinie muss die vorgesehene Nutzung zulassen. AWS dokumentiert diese KMS-Berechtigungen und -Anforderungen. Eine Bucket-Richtlinie, die explizite Verschlüsselungsheader verlangt, kann dieses Skript auch dann zurückweisen, wenn die Standardverschlüsselung des Buckets konfiguriert ist. Fragen Sie vor der Nutzung dieses Beispiels den Bucket-Eigentümer, ob Uploads mit der Standardverschlüsselung erlaubt sind. Lockern Sie diese Richtlinie nicht, nur damit ein Upload gelingt.

Zugriffskontrolle beim Bucket-Eigentümer belassen

Das Weglassen einer ACL macht einen beliebigen Bucket nicht privat. Verwenden Sie den zuvor vorbereiteten privaten Bucket und die Identität mit begrenzten Berechtigungen. Bei neuen Buckets ist standardmäßig die Einstellung aktiv, die den Bucket-Eigentümer als Eigentümer erzwingt und ACLs deaktiviert. Wenn Sie einem solchen Upload ACL='private' hinzufügen, kann das zu AccessControlListNotSupported führen. Verwalten Sie den Zugriff über Richtlinien und lassen Sie Block Public Access aktiviert, wie in den S3-Sicherheitsempfehlungen von AWS beschrieben.

Lassen Sie den Bucket-Eigentümer die Regeln für den gesamten Bucket pflegen, einschließlich einer etwaigen Vorgabe, Anfragen ohne HTTPS abzulehnen. Der Dateiuploader sollte nicht bei jedem Senden einer Datei eine neue Bucket-Richtlinie einrichten.

Fehlgeschlagenen Upload diagnostizieren

Ungültige Eingabe, Status 2: Prüfen Sie den Pfad relativ zu Ihrem aktuellen Verzeichnis. Ein Verzeichnis ist keine hochladbare Datei; dieser Befehl durchsucht es nicht rekursiv.
NoCredentialsError oder eine abgelaufene Sitzung: Wählen Sie das vorgesehene Profil und erneuern Sie dessen Anmeldung. Vergewissern Sie sich, dass der Scheduler oder Dienst eine eigene konfigurierte Identität hat, falls der Befehl nur in Ihrer interaktiven Shell funktioniert.
S3UploadFailedError: Prüfen Sie mit dem Eigentümer den Bucket-Namen, das genaue Schlüsselpräfix, die Upload-Berechtigung und mögliche Ablehnungen durch die Bucket-Richtlinie. Prüfen Sie bei SSE-KMS auch die Schlüsselberechtigungen. Diese Ausnahme kann mehrere Dienstfehler kapseln; ihr Typ allein belegt nicht, dass der Zugriff verweigert wurde.
EndpointConnectionError oder ein anderer Verbindungsfehler: Prüfen Sie Netzwerk, Region, Proxy und Endpunktkonfiguration. Deaktivieren Sie nicht die Zertifikatsprüfung, um einen TLS-Fehler zu umgehen.
PermissionError oder ein anderer Fehler vom Typ OSError: Prüfen Sie, ob der Prozess die Datei lesen kann und ob sie während des Uploads weder verschoben noch entfernt wurde.

Transfer Acceleration, Lebenszyklusregeln und Ereignisbenachrichtigungen sind separate Entscheidungen der Bucket-Verwaltung. Insbesondere gilt: Das Setzen einer S3-Benachrichtigungskonfiguration ersetzt die bestehende Konfiguration. Ein Lambda-Trigger sollte im Rahmen einer geprüften Infrastrukturänderung hinzugefügt werden, bei der die bestehenden Ziele erhalten bleiben. Bringen Sie den Befehl für eine einzelne Datei mit der vorgesehenen Identität und dem vorgesehenen Präfix zum Laufen, bevor Sie ihn in eine geplante Aufgabe einbinden.