So funktionieren lokale und Remote-Uploads

In diesem Leitfaden wird der vollständige Fluss zum Hochladen von Dateien mit der Frame.io V4-API beschrieben.Erklärt werden die rohen API-Anfragen und -Antworten sowohl für lokale als auch für Remote-Uploads.

**Suchen Sie nach SDK-spezifischen Leitfäden?**Informationen zu Upload-Implementierungen mit integriertem Chunking, Wiederholungsversuchen und Tracking des Fortschritts finden Sie im Python SDK Upload-Leitfaden.

Voraussetzungen

Bevor Sie mit dem Hochladen von Dateien beginnen, vergewissern Sie sich, dass Sie diese Setup-Schritte abgeschlossen haben:

1

Frame.io V4-Konto

Sie haben ein Frame.io V4-Konto, das über die Adobe Admin Console verwaltet wird, ODER Sie haben für Ihren Kontobenutzer bzw. Ihre Kontobenutzerin zur Adobe-Authentifizierung gewechselt.

2

Setup der Adobe Developer Console

Sie haben sich bei der Adobe Developer Console angemeldet und die Frame.io-API zu einem neuen oder bestehenden Projekt hinzugefügt.

3

Authentifizierungsdaten

Sie haben die entsprechenden Authentifizierungsdaten für Ihr Projekt generiert.

4

Zugriffstoken

Sie haben diese Anmeldedaten erfolgreich verwendet, um einen Zugriffstoken zu generieren.

Auswahl Ihrer Upload-Methode

Es gibt zwei Möglichkeiten, eine Datei mit der Frame.io-API hochzuladen: Datei erstellen (lokal hochladen) und Datei erstellen (Remote-Upload).

Lokaler Upload

Diese Methode wird genutzt, wenn die Medien für Ihre Anwendung lokal zugänglich sind, ähnlich wie beim Ziehen einer Datei vom Desktop.

Remote-Upload

Diese Methode wird verwendet, wenn über das Netzwerk auf die Medien zugegriffen wird, beispielsweise durch .eine Integration mit einem anderen Service

In diesem Leitfaden beginnen wir mit dem einfacheren Fall des Abschließens eines Remote-Uploads.

Remote-Upload

Wählen Sie den Endpunkt Datei erstellen (Remote-Upload), um eine Datei über Remote-Upload zu erstellen.Für den Anfragefließtext wird der Dateiname und seine Quell-URL benötigt.

Für den Remote-Upload besteht derzeit ein Dateigrößen-Limit von 50 GB.Nutzen Sie bei Dateien von mehr als 50 GB stattdessen den lokalen Upload.

Anfragebeispiel

1{
2 "data": {
3 "name": "my_file.jpg",
4 "source_url": "https://upload.wikimedia.org/wikipedia/commons/e/e1/White_Pixel_1x1.jpg"
5 }
6}

Antwortbeispiel

Eine erfolgreiche Anfrage führt zu einer Antwort wie der unten gezeigten:

1{
2 "data": {
3 "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4 "name": "my_file.jpg",
5 "status": "created",
6 "type": "file",
7 "file_size": 518,
8 "updated_at": "2025-06-26T20:14:33.796116Z",
9 "media_type": "image/jpeg",
10 "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
11 "project_id": "7e46e495-4444-4555-8649-bee4d391a997",
12 "created_at": "2025-06-26T20:14:33.159489Z",
13 "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e"
14 },
15 "links": {
16 "status": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/files/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e/status"
17 }
18}

Lokaler Upload

Wählen Sie den Endpunkt Datei erstellen (lokal hochladen), um eine Datei über den lokalen Upload zu erstellen.Für den Anfragefließtext werden der Dateiname und die Dateigröße in Bytes benötigt.

Anfragebeispiel

1{
2 "data": {
3 "name": "my_file.jpg",
4 "file_size": 50645990
5 }
6}

Antwortbeispiel

Wenn die Anfrage erfolgreich ist, wird eine Platzhalter-Dateiressource ohne Inhalt erstellt.Je nach Dateigröße enthält der Antwortfließtext eine oder mehrere upload_urls.Bei diesem Beispiel müssen wir diesen Upload in mehreren Teilen verwalten.

1{
2 "data": {
3 "id": "fa18ba7b-b3ee-4dd6-9b31-bd07e554241d",
4 "name": "my_file.jpg",
5 "status": "created",
6 "type": "file",
7 "file_size": 50645990,
8 "updated_at": "2025-06-26T20:08:06.823170Z",
9 "media_type": "image/jpeg",
10 "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
11 "project_id": "7e46e495-4444-4555-8649-bee4d391a997",
12 "created_at": "2025-06-26T20:08:06.751313Z",
13 "upload_urls": [
14 {
15 "size": 16881997,
16 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?..."
17 },
18 {
19 "size": 16881997,
20 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?..."
21 },
22 {
23 "size": 16881996,
24 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
25 }
26 ],
27 "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d"
28 }
29}

Wichtige Upload-Anforderungen:

Hier sind wichtige Details, die Sie bei nachfolgenden Upload-Anfragen beachten müssen:

  • Die HTTP-Anfragemethode muss PUT sein.
  • Der x-amz-acl-Header muss enthalten sein und auf „privat“ eingestellt sein.
  • Der Header Content-Type muss mit dem media_type übereinstimmen, der in der ursprünglichen Anfrage Datei erstellen (lokal hochladen) angegeben wurde.Dies gilt auch beim Hochladen der Datei in separaten Teilen.Im obigen Beispiel lautet der Wert für media_type``image/jpeg.Daher muss der Wert für Content-Type ebenfalls image/jpeg sein.

Mehrteiliger Upload

Wenn eine bestimmte Datei zu mehr als einer Upload-URL führt, müssen Sie die Quelldatei in Chunks aufteilen und für jeden einzelnen eine PUT-Anfrage senden.

Empfehlung: Im Python SDK Upload-Leitfaden wird der mehrteilige Upload mit FrameioUploader dargelegt, mit dem das Chunking, parallele Uploads, Wiederholungsversuche und die Fortschrittsverfolgung vorkonfiguriert verarbeitet wird.

Wenn Sie den Upload manuell implementieren müssen – zum Beispiel in einer Sprache ohne SDK oder für vollständige Kontrolle über den Prozess –, sehen Sie im unten stehenden Skript, wie Sie eine Datei in Chunks aufteilen und jeden einzelnen mit den vorsignierten URLs hochladen.

Python-Implementierungsbeispiel

Skript für mehrteiligen Upload
1import requests
2import math
3from typing import List
4from tqdm import tqdm # For progress bar
5
6def upload_file_in_chunks(file_path: str, upload_urls: list[str], content_type: str | None = None, chunk_size: int | None = None) -> bool:
7 """
8 Upload a file in chunks using presigned URLs.
9 """
10 try:
11 # Auto-detect content type based on file extension
12 if content_type is None:
13 detected_content_type, _ = mimetypes.guess_type(file_path)
14 content_type = detected_content_type # Default fallback
15
16 print(f"Detected content type: {content_type}")
17
18 # Get file size
19 with open(file_path, 'rb') as f:
20 f.seek(0, 2) # Seek to end of file
21 file_size = f.tell()
22
23 # Calculate chunk size if not provided
24 if chunk_size is None:
25 chunk_size = math.ceil(file_size / len(upload_urls))
26
27 print(f"File size: {file_size} bytes")
28 print(f"Chunk size: {chunk_size} bytes")
29 print(f"Number of chunks: {len(upload_urls)}")
30
31 # Upload each chunk
32 with open(file_path, 'rb') as f:
33 with tqdm(total=len(upload_urls), desc="Uploading chunks") as pbar:
34 for i, url in enumerate(upload_urls):
35 start_byte = i * chunk_size
36 end_byte = min(start_byte + chunk_size, file_size)
37
38 # Read chunk from file
39 f.seek(start_byte)
40 chunk = f.read(end_byte - start_byte)
41
42 print(f"Uploading chunk {i+1}: {len(chunk)} bytes")
43
44 # Upload chunk with minimal headers matching the signature
45 response = requests.put(
46 url,
47 data=chunk,
48 headers={
49 'content-type': content_type,
50 'x-amz-acl': 'private'
51 }
52 )
53
54 if response.status_code != 200:
55 print(f"Failed to upload chunk {i+1}. Status code: {response.status_code}")
56 print(f"Response text: {response.text}")
57 print(f"Response headers: {dict(response.headers)}")
58 return False
59 else:
60 print(f"Chunk {i+1} uploaded successfully!")
61
62 pbar.update(1)
63
64 return True
65
66 except Exception as e:
67 print(f"Error during upload: {str(e)}")
68 return False
69
70# Example usage
71if __name__ == "__main__":
72 # Replace these with your actual values
73 file_path = "/Users/MyComputer/local_upload/sample.jpg" # Path to your file
74 upload_urls = [
75 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?...",
76 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?...",
77 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
78 ]
79 content_type = "image/jpeg"
80
81 print("Starting file upload...")
82 success = upload_file_in_chunks(file_path, upload_urls, content_type)
83
84 if success:
85 print("File upload completed successfully!")
86 else:
87 print("File upload failed!")

Zusammenfassung des Upload-Flusses

1

Wahl der Upload-Methode

Entscheiden Sie sich zwischen Remote-Upload (Datei über URL zugänglich) oder lokalem Upload (Datei auf Ihrem System).

2

Erstellen der Dateianfrage

Stellen Sie die erste Anfrage, um die Dateiressource mit den erforderlichen Metadaten zu erstellen.

3

Verarbeiten von Upload-URLs

Verarbeite bei lokalen Uploads die zurückgegebenen upload_urls (einzeln oder mehrere Teile)

4

Hochladen des Dateiinhalts

Laden Sie Dateiinhalte mit PUT-Anfragen und den richtigen Headern auf die bereitgestellten URLs hoch.

5

Überprüfen des Uploads

Überprüfen Sie den Dateistatus, um das erfolgreiche Hochladen und die Verarbeitung zu bestätigen.

Nächste Schritte: Sobald Ihre Datei hochgeladen ist, können Sie mit der zurückgegebenen Datei-ID Kommentare hinzufügen, Freigaben erstellen oder andere Vorgänge mit der Frame.io V4-API durchführen.