Medium hochladen

Der Upload von Medienelementen erfolgt in zwei Schritten:

1. Lade die Bytes deiner Mediendateien über den Endpunkt „uploads“ auf einen Google-Server hoch. Dadurch wird ein Upload-Token zurückgegeben, das die hochgeladenen Byte identifiziert.
2. Verwende einen batchCreate-Aufruf mit dem Upload-Token, um ein Medienelement im Google Fotos-Konto des Nutzers zu erstellen.

In diesen Schritten wird beschrieben, wie ein einzelnes Medienelement hochgeladen wird. Wenn Sie mehrere Medienelemente hochladen (sehr wahrscheinlich bei Produktionsanwendungen), lesen Sie die Best Practices für Uploads, um die Effizienz des Uploads zu verbessern.

Hinweis

Erforderliche Autorisierungsbereiche

Für das Hochladen von Medienelementen in die Mediathek oder in ein Album eines Nutzers ist der Gültigkeitsbereich photoslibrary.appendonly erforderlich. Weitere Informationen zu Bereichen finden Sie unter Autorisierungsbereiche.

Zulässige Dateitypen und -größen

Sie können die in dieser Tabelle aufgeführten Dateitypen hochladen.

Schritt 1: Byte hochladen

Mit Uploadanfragen Bytes auf Google hochladen. Bei einer erfolgreichen Uploadanfrage wird ein Uploadtoken in Form eines Rohtextstrings zurückgegeben. Verwende diese Upload-Tokens, um mit dem batchCreate-Aufruf Medienelemente zu erstellen.

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-type: application/octet-stream
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: raw

media-binary-data

upload-token

Die empfohlene Dateigröße für Bilder beträgt weniger als 50 MB. Bei Dateien, die größer als 50 MB sind, treten häufig Leistungsprobleme auf.

Die Google Fotos-Mediathek API unterstützt fortsetzbare Uploads. Bei einem fortsetzbaren Upload können Sie eine Mediendatei in mehrere Abschnitte aufteilen und diese nacheinander hochladen.

Schritt 2: Medienelement erstellen

Nachdem Sie die Bytes Ihrer Mediendateien hochgeladen haben, können Sie sie mithilfe von Uploadtokens als Medienelemente in Google Fotos erstellen. Ein Upload-Token ist einen Tag nach der Erstellung gültig. Ein Medienelement wird immer der Mediathek des Nutzers hinzugefügt. Medienelemente können nur Alben hinzugefügt werden, die von deiner App erstellt wurden. Weitere Informationen findest du unter Autorisierungsbereiche.

Rufen Sie zum Erstellen neuer Medienelemente mediaItems.batchCreate auf. Geben Sie dazu eine Liste von newMediaItems an. Jede newMediaItem enthält ein Upload-Token, das in einem simpleMediaItem angegeben ist, und eine optionale Beschreibung, die dem Nutzer angezeigt wird.

Das Beschreibungsfeld ist auf 1.000 Zeichen beschränkt und sollte nur aussagekräftige Texte enthalten, die von Nutzern erstellt wurden. Beispiel: Unser Ausflug in den Park oder Festtagsessen. Fügen Sie keine Metadaten wie Dateinamen, programmatische Tags oder anderen automatisch generierten Text ein.

Die beste Leistung erzielen Sie, wenn Sie die Anzahl der Aufrufe von mediaItems.batchCreate reduzieren, indem Sie mehrere Medienelemente in einem Aufruf einbinden. Warten Sie immer, bis die vorherige Anfrage abgeschlossen ist, bevor Sie einen weiteren Aufruf für denselben Nutzer starten.

Du kannst ein einzelnes oder mehrere Medienelemente in der Mediathek eines Nutzers erstellen, indem du die Beschreibungen und die entsprechenden Upload-Tokens angibst:

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

{
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

Sie können auch albumId und albumPosition angeben, um Medienelemente an einer bestimmten Stelle im Album einzufügen.

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "after-media-item",
    "relativeMediaItemId": "media-item-id"
  }
}

Weitere Informationen zur Positionierung in Alben findest du unter Anreicherungen hinzufügen.

Antwort zur Elementerstellung

Der mediaItems.batchCreate-Aufruf gibt das Ergebnis für jedes der Medienelemente zurück, die du erstellen wolltest. Die Liste der newMediaItemResults gibt den Status an und enthält die uploadToken für die Anfrage. Ein Statuscode ungleich null weist auf einen Fehler hin.

{
  "newMediaItemResults": [
    {
      "uploadToken": "upload-token",
      "status": {
        "message": "Success"
      },
      "mediaItem": {
        "id": "media-item-id",
        "description": "item-description",
        "productUrl": "https://photos.google.com/photo/photo-path",
        "mimeType": "mime-type",
        "mediaMetadata": {
          "width": "media-width-in-px",
          "height": "media-height-in-px",
          "creationTime": "creation-time",
          "photo": {}
        },
        "filename": "filename"
      }
    },
    {
      "uploadToken": "upload-token",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

Wenn ein Artikel erfolgreich hinzugefügt wurde, wird eine mediaItem zurückgegeben, die die mediaItemId, productUrl und mediaMetadata enthält. Weitere Informationen finden Sie unter Auf Medienelemente zugreifen.

Wenn das Medienelement ein Video ist, muss es zuerst verarbeitet werden. Der mediaItem enthält in seinem mediaMetadata einen status, der den Verarbeitungsstatus der Videodatei beschreibt. Eine neu hochgeladene Datei erhält zuerst den Status PROCESSING, bevor sie READY ist. Weitere Informationen findest du unter Auf Medienelemente zugreifen.

Wenn während dieses Aufrufs ein Fehler auftritt, folge den Best Practices und wiederhole die Anfrage. Sie sollten die erfolgreichen Hinzufügungen im Auge behalten, damit das Bild bei der nächsten Anfrage an der richtigen Position in das Album eingefügt werden kann. Weitere Informationen finden Sie unter Alben erstellen.

Die Ergebnisse werden immer in der Reihenfolge zurückgegeben, in der die Uploadtokens gesendet wurden.

Best Practices für Uploads

Die folgenden Best Practices und Ressourcen helfen Ihnen, Ihre Effizienz beim Hochladen zu steigern:

• Beachten Sie die Best Practices für Wiederholungsversuche und Fehlerbehandlung und beachten Sie dabei Folgendes:
  • 429-Fehler können auftreten, wenn Ihr Kontingent aufgebraucht ist oder Sie aufgrund zu vieler Aufrufe zu schnell eine Ratenbegrenzung erhalten. Achten Sie darauf, batchCreate für denselben Nutzer erst aufzurufen, wenn die vorherige Anfrage abgeschlossen ist.
  • Bei 429-Fehlern ist eine Wartezeit von mindestens 30s Sekunden vor dem nächsten Versuch erforderlich. Verwenden Sie beim Wiederholen von Anfragen eine exponentielle Backoff-Strategie.
  • 500-Fehler treten auf, wenn auf dem Server ein Fehler auftritt. Beim Hochladen ist das höchstwahrscheinlich auf mehrere Schreibaufrufe (z. B. batchCreate) für denselben Nutzer zur selben Zeit zurückzuführen. Prüfen Sie die Details Ihrer Anfrage und führen Sie keine parallelen Aufrufe an batchCreate aus.
• Mit dem fortsetzbaren Upload können Sie Ihre Uploads bei Netzwerkunterbrechungen robuster gestalten und die Bandbreitennutzung reduzieren, da Sie teilweise abgeschlossene Uploads fortsetzen können. Dies ist beim Hochladen von Client-Mobilgeräten oder beim Hochladen großer Dateien wichtig.

Beachte außerdem die folgenden Tipps für die einzelnen Schritte des Uploads: Upload von Bytes und anschließendes Erstellen von Medienelementen.

Hochgeladene Byte

• Der Upload von Bytes (zum Abrufen von Upload-Tokens) kann parallel erfolgen.
• Legen Sie für jeden Uploadaufruf im Header X-Goog-Upload-Content-Type immer den richtigen MIME-Typ fest.

Medienelemente erstellen

• Führen Sie für einen einzelnen Nutzer keine parallelen Aufrufe von batchCreate durch.

  • Rufen Sie für jeden Nutzer nacheinander batchCreate auf.
  • Wenn du mehrere Nutzer hast, musst du immer batchCreate-Aufrufe für jeden Nutzer nacheinander ausführen. Führe nur parallele Aufrufe für unterschiedliche Nutzer aus.

• Fügen Sie so viele NewMediaItems wie möglich in jeden Aufruf von batchCreate ein, um die Gesamtzahl der Aufrufe zu minimieren. Sie können maximal 50 Elemente angeben.

• Legen Sie einen aussagekräftigen Beschreibungstext fest, der von Ihren Nutzern erstellt wurde. Fügen Sie in das Beschreibungsfeld keine Metadaten wie Dateinamen, programmatische Tags oder anderen automatisch generierten Text ein.

Beispiel für eine Schritt-für-Schritt-Anleitung

In diesem Beispiel wird anhand von Pseudocode veranschaulicht, wie Medienelemente für mehrere Nutzer hochgeladen werden. Ziel ist es, die beiden Schritte des Uploadprozesses (Upload von Rohbytes und Erstellen von Medienelementen) zu skizzieren und Best Practices für die Erstellung einer effizienten und robusten Uploadintegration zu erläutern.

Schritt 1: Rohbytes hochladen

Erstelle zuerst eine Warteschlange, um die Rohbytes für deine Medienelemente von allen deinen Nutzern hochzuladen. Verfolge jede zurückgegebene uploadToken pro Nutzer. Denken Sie an die folgenden wichtigen Punkte:

• Die Anzahl der gleichzeitigen Uploadthreads hängt von Ihrer Umgebung ab.
• Sie können die Uploadwarteschlange bei Bedarf neu anordnen. Sie können Uploads beispielsweise anhand der Anzahl der verbleibenden Uploads pro Nutzer, des Gesamtfortschritts eines Nutzers oder anderer Anforderungen priorisieren.

CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
  WHILE uploadQueue is not empty
    POP uploadQueue
    UPLOAD file for user
    GET uploadToken
    CHECK and HANDLE errors
    STORE uploadToken for user in uploadTokensQueue
  END

Schritt 2: Medienelemente erstellen

In Schritt 1 können Sie mehrere Bytes von mehreren Nutzern parallel hochladen. In Schritt 2 können Sie jedoch nur jeweils einen Aufruf für jeden Nutzer ausführen.

// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
  // Calls can be made in parallel for different users,
  // but only make a single call per user at a time.
  START new thread for (this) user if there is no thread yet
    POP 50 uploadTokens from uploadTokensQueue for user
    CALL mediaItems.batchCreate with uploadTokens
    WAIT UNTIL batchCreate call has completed
    CHECK and HANDLE errors (retry as needed)
  DONE.

Wiederhole diesen Vorgang, bis alle Uploads und Aufrufe zur Medienerstellung abgeschlossen sind.