Medien hochladen

Das Hochladen von Medienelementen erfolgt in zwei Schritten:

1. Laden Sie die Byte Ihrer Mediendateien mit dem uploads-Endpunkt auf einen Google-Server hoch. Dadurch wird ein Upload-Token zurückgegeben, das die hochgeladenen Bytes identifiziert.
2. Verwenden Sie einen batchCreate-Aufruf mit dem Upload-Token, um ein Medienelement im Google Fotos-Konto des Nutzers zu erstellen.

In diesen Schritten wird beschrieben, wie Sie ein einzelnes Media-Element hochladen. Wenn Sie mehrere Media-Elemente hochladen (was bei jeder Produktionsanwendung sehr wahrscheinlich ist), sollten Sie sich die Best Practices für Uploads ansehen, um die Effizienz Ihrer Uploads zu verbessern.

Hinweis

Erforderliche Autorisierungsbereiche

Für das Hochladen von Medienelementen in die Mediathek oder das Album eines Nutzers ist der Bereich 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: Bytes hochladen

Mit Uploadanfragen können Sie Byte zu Google hochladen. Bei einer erfolgreichen Uploadanfrage wird ein Upload-Token in Form eines Rohtextstrings zurückgegeben. Verwenden Sie diese Upload-Tokens, um mit dem Aufruf batchCreate Media-Elemente 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, kann es zu Leistungsproblemen kommen.

Die Google Photos Library API unterstützt fortsetzbare Uploads. Bei einem fortsetzbaren Upload können Sie eine Mediendatei in mehrere Abschnitte aufteilen und jeweils einen Abschnitt hochladen.

Schritt 2: Media-Element erstellen

Nachdem Sie die Byte Ihrer Mediendateien hochgeladen haben, können Sie sie mithilfe von Upload-Tokens als Media-Elemente in Google Fotos erstellen. Ein Upload-Token ist nach der Erstellung einen Tag lang gültig. Ein Media-Element wird immer der Mediathek des Nutzers hinzugefügt. Media-Elemente können nur Alben hinzugefügt werden, die von Ihrer App erstellt wurden. Weitere Informationen finden Sie unter Autorisierungsumfang.

Rufen Sie zum Erstellen neuer Media-Elemente mediaItems.batchCreate auf und geben Sie eine Liste von newMediaItems an. Jedes 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 von Nutzern erstellten, aussagekräftigen Text enthalten. Beispiele: „Unser Ausflug in den Park“ oder „Weihnachtsessen“. Fügen Sie keine Metadaten wie Dateinamen, programmatische Tags oder anderen automatisch generierten Text ein.

Um die Leistung zu optimieren, sollten Sie die Anzahl der Aufrufe von mediaItems.batchCreate reduzieren, indem Sie mehrere Media-Elemente in einen Aufruf einfügen. Warten Sie immer, bis die vorherige Anfrage abgeschlossen ist, bevor Sie einen nachfolgenden Aufruf für denselben Nutzer ausführen.

Sie können ein einzelnes oder mehrere Media-Elemente in der Mediathek eines Nutzers erstellen, indem Sie die Beschreibungen und die entsprechenden Upload-Tokens angeben:

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 Media-Elemente 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 finden Sie unter Verzierungen hinzufügen.

Antwort auf die Erstellung eines Elements

Der mediaItems.batchCreate-Aufruf gibt das Ergebnis für jedes der Media-Elemente zurück, die Sie erstellt haben. 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 Element erfolgreich hinzugefügt wurde, wird ein mediaItem mit den zugehörigen mediaItemId, productUrl und mediaMetadata zurückgegeben. Weitere Informationen finden Sie unter Auf Media-Elemente zugreifen.

Wenn es sich bei dem Medienelement um ein Video handelt, muss es zuerst verarbeitet werden. Der mediaItem-Container enthält in seinem mediaMetadata-Container ein status, das den Verarbeitungsstatus der Videodatei beschreibt. Bei einer neu hochgeladenen Datei wird zuerst der Status PROCESSING zurückgegeben, bevor sie READY ist. Weitere Informationen finden Sie unter Auf Media-Elemente zugreifen.

Wenn bei diesem Aufruf ein Fehler auftritt, folgen Sie den Best Practices und wiederholen Sie die Anfrage. Es kann sinnvoll sein, erfolgreiche Ergänzungen zu verfolgen, damit das Bild bei der nächsten Anfrage an der richtigen Stelle in das Album eingefügt werden kann. Weitere Informationen finden Sie unter Alben erstellen.

Die Ergebnisse werden immer in derselben Reihenfolge zurückgegeben, in der die Upload-Tokens eingereicht wurden.

Best Practices für Uploads

Die folgenden Best Practices und Ressourcen können Ihnen helfen, die Gesamteffizienz bei Uploads zu verbessern:

• Beachten Sie die Best Practices für Wiederholungsversuche und Fehlerbehandlung und die folgenden Punkte:
  • 429-Fehler können auftreten, wenn Ihr Kontingent aufgebraucht ist oder Sie aufgrund zu vieler Aufrufe in zu kurzer Zeit einer Ratenbegrenzung unterliegen. Rufen Sie batchCreate für denselben Nutzer erst auf, wenn die vorherige Anfrage abgeschlossen ist.
  • Bei 429-Fehlern ist eine Mindestverzögerung von 30s vor einem Neuversuch erforderlich. Verwenden Sie einen exponentiellen Backoff, wenn Sie Anfragen wiederholen.
  • 500-Fehler treten auf, wenn auf dem Server ein Fehler auftritt. Beim Hochladen liegt das höchstwahrscheinlich daran, dass mehrere Schreibaufrufe (z. B. batchCreate) für denselben Nutzer gleichzeitig erfolgen. Prüfen Sie die Details Ihrer Anfrage und rufen Sie batchCreate nicht parallel auf.
• Verwenden Sie den fortsetzbaren Upload, um Ihre Uploads bei Netzwerkunterbrechungen robuster zu gestalten. Dadurch wird die Bandbreitennutzung reduziert, da Sie teilweise abgeschlossene Uploads fortsetzen können. Das ist wichtig, wenn Sie Dateien von mobilen Clientgeräten oder große Dateien hochladen.

Beachten Sie außerdem die folgenden Tipps für jeden Schritt des Uploadvorgangs: Bytes hochladen und dann Media-Elemente erstellen.

Byte hochladen

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

Medienelemente erstellen

• Rufen Sie batchCreate nicht parallel für einen einzelnen Nutzer auf.

  • Führen Sie für jeden Nutzer die Aufrufe von batchCreate nacheinander (seriell) aus.
  • Bei mehreren Nutzern sollten Sie batchCreate-Aufrufe immer für jeden Nutzer nacheinander ausführen. Rufen Sie nur verschiedene Nutzer parallel auf.

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

• Legen Sie einen aussagekräftigen Beschreibungstext fest, der von Ihren Nutzern erstellt wurde. Das Beschreibungsfeld darf keine Metadaten wie Dateinamen, programmatische Tags oder anderen automatisch generierten Text enthalten.

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

In diesem Beispiel wird Pseudocode verwendet, um das Hochladen von Media-Elementen für mehrere Nutzer zu veranschaulichen. Ziel ist es, beide Schritte des Upload-Prozesses (Rohbytes hochladen und Media-Elemente erstellen) zu beschreiben und Best Practices für die Entwicklung einer effizienten und stabilen Upload-Integration zu erläutern.

Schritt 1: Rohbyte hochladen

Erstellen Sie zuerst eine Warteschlange, um die Rohbytes für Ihre Media-Elemente von allen Ihren Nutzern hochzuladen. Erfassen Sie jede zurückgegebene uploadToken pro Nutzer. Wichtige Hinweise:

• Die Anzahl der gleichzeitigen Upload-Threads hängt von Ihrer Betriebsumgebung ab.
• Ordnen Sie die Upload-Warteschlange bei Bedarf neu an. Sie können beispielsweise Uploads basierend auf der Anzahl der verbleibenden Uploads pro Nutzer, dem Gesamtfortschritt eines Nutzers oder anderen 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: Media-Elemente erstellen

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

// 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.

Wiederholen Sie diesen Vorgang, bis alle Uploads und Media-Erstellungsaufrufe abgeschlossen sind.