Medien hochladen

Das Hochladen von Medienelementen erfolgt in zwei Schritten:

  1. Lade die Bytes deiner Mediendateien über den Endpunkt für Uploads auf einen Google-Server hoch. Dadurch wird ein Upload-Token zurückgegeben, das die hochgeladenen Byte.
  2. Verwenden Sie einen batchCreate-Aufruf mit dem Uploadtoken, ein Medienelement im Google Fotos-Konto des Nutzers zu erstellen

Mit diesen Schritten wird der Prozess zum Hochladen eines einzelnen Medienelements beschrieben. Wenn Sie Hochladen mehrerer Medienelemente (sehr wahrscheinlich für jede Produktionsanwendung) Lies dir die Best Practices für Uploads durch, um deinen Upload zu verbessern. Effizienz.

Hinweis

Erforderliche Autorisierungsbereiche

Für das Hochladen von Medienelementen in die Mediathek oder das 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.

Medientyp Zulässige Dateitypen Maximale Dateigröße
Fotos AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP und einige RAW-Dateien 200 MB
Videos 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4 MPG, MTS, TOD, WMV. 20 GB

Schritt 1: Byte hochladen

Bytes über Uploadanfragen auf Google hochladen. Eine erfolgreiche Uploadanfrage gibt ein Upload-Token in Form einer Rohtextzeichenfolge zurück. Upload verwenden Tokens zum Erstellen von Medienelementen mit dem batchCreate-Aufruf.

REST

Fügen Sie die folgenden Felder in den POST-Anfrageheader ein:

Headerfelder
Content-type Setze diese Property auf application/octet-stream.
X-Goog-Upload-Content-Type Empfohlen. Legen Sie als Wert den MIME-Typ der hochzuladenden Bytes fest. Gängige MIME-Typen sind image/jpeg, image/png und image/gif.
X-Goog-Upload-Protocol Setze diese Property auf raw.

Hier ist ein POST-Anfrage-Header:

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

Fügen Sie in den Anfragetext die Binärdatei der Datei ein: 

media-binary-data

Wenn diese POST-Anfrage erfolgreich ist, wird ein Upload-Token in der Form einer Rohtextzeichenfolge, wird als Antworttext zurückgegeben. Um Medien zu erstellen -Elemente verwenden, verwenden Sie diese Textstrings im batchCreate-Aufruf.

upload-token

Die empfohlene Dateigröße für Bilder beträgt weniger als 50 MB. Dateien, die größer als 50 MB sind zu Leistungsproblemen führen.

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

Schritt 2: Medienelement erstellen

Nachdem du die Bytes deiner Mediendateien hochgeladen hast, kannst du sie als Mediendateien erstellen Elemente in Google Fotos mithilfe von Uploadtokens hochladen. Ein Uploadtoken ist gültig für einen Tag nach der Erstellung. Ein Medienelement wird immer dem Element Bibliothek. Medienelemente können nur hinzugefügt werden zu Alben, die von Ihren Weitere Informationen finden Sie unter Autorisierung Bereiche.

Rufen Sie zum Erstellen neuer Medienelemente mediaItems.batchCreate indem Sie eine Liste von newMediaItems angeben. 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 darf nur folgende Zeichen enthalten: aussagekräftiger Text, der von Nutzenden erstellt wurde. Beispiel: Unser Ausflug in den Park oder „Weihnachtsessen“. Fügen Sie keine Metadaten wie Dateinamen, Programmatic -Tags oder anderen automatisch generierten Text.

Für eine optimale Leistung sollten Sie die Anzahl der mediaItems.batchCreate-Anrufe reduzieren indem Sie mehrere Medienelemente in einen Aufruf aufnehmen. Warten Sie immer, bis die vorherige Anfrage abgeschlossen ist, bevor Sie einen weiteren Aufruf für denselben Nutzer starten.

Sie können ein einzelnes Medienelement oder mehrere Medienelemente in der Mediathek eines Nutzers erstellen. indem Sie die Beschreibungen und die entsprechenden Uploadtokens angeben:

REST

Hier ist der POST-Anfrage-Header:

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

Der Anfragetext sollte eine Liste von newMediaItems enthalten.

{
  "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 einfügen.

REST

{
  "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 Hinzufügen Bereicherung.

Antwort zur Elementerstellung

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

REST

Wenn alle Medienelemente erfolgreich erstellt wurden, wird die Anforderung zurückgegeben. HTTP-Status 200 OK. Wenn einige Medienelemente nicht erstellt werden können, gibt die Anfrage den HTTP-Status 207 MULTI-STATUS zurück, teilweisen Erfolg.

{
  "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 zurückgegeben, das seine mediaItemId, productUrl und mediaMetadata. Weitere Informationen finden Sie unter Auf Medienelemente zugreifen

Wenn das Medienelement ein Video ist, muss es zuerst verarbeitet werden. Das mediaItem enthält ein status in seinem mediaMetadata, das die Verarbeitung beschreibt Status der Videodatei. Eine neu hochgeladene Datei gibt den Status PROCESSING zurück. bevor es READY zur Verwendung ist. Weitere Informationen finden Sie unter Auf Medienelemente zugreifen.

Falls während des Gesprächs ein Fehler auftritt, befolgen Sie die Anleitung Beste und wiederholen Sie Ihre 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 erhalten Sie unter Erstellen Alben.

Die Ergebnisse werden immer in der gleichen Reihenfolge zurückgegeben, in der die Upload-Tokens gesendet.

Best Practices für Uploads

Mit den folgenden Best Practices und Ressourcen können Sie Ihre Effizienz steigern. mit Uploads:

  • Folgen Sie den Best Practices für Wiederholungen und Fehlerbehandlung. beachten Sie die folgenden Punkte:
    • 429-Fehler können auftreten, wenn Ihr Kontingent aufgebraucht ist oder Sie aufgrund zu vieler Aufrufe zu schnell eine Ratenbegrenzung erhalten. Achten Sie darauf, Sie rufen batchCreate für denselben Nutzer erst beim vorherigen abgeschlossen ist.
    • 429-Fehler erfordern eine Mindestverzögerung von 30s, bevor sie es noch einmal versuchen. Verwenden Sie beim Wiederholen von Anfragen eine exponentielle Backoff-Strategie.
    • 500-Fehler treten auf, wenn der Server einen Fehler erkennt. Achten Sie beim Hochladen darauf, ist dies höchstwahrscheinlich auf mehrere Schreibaufrufe (z. B. batchCreate) für denselben Nutzer. Überprüfen Sie die Details der und rufen Sie batchCreate nicht parallel auf.
  • 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. Dieses ist wichtig beim Hochladen von Client-Mobilgeräten große Dateien.

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

Bytes werden hochgeladen

Medien werden erstellt

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

    • Starten Sie für jeden Nutzer nacheinander batchCreate-Aufrufe (im seriell).
    • Führen Sie bei mehreren Nutzern immer batchCreate-Aufrufe für jeden Nutzer durch. nach einem anderen. Führen Sie Aufrufe nur für verschiedene Nutzer gleichzeitig aus.

  • So viele NewMediaItems wie möglich einbeziehen in jedem Aufruf von batchCreate, um die Gesamtzahl der Anrufe zu minimieren die Sie treffen müssen. Sie können maximal 50 Elemente angeben.

  • Geben Sie einen aussagekräftigen Beschreibungstext ein. das von den Nutzenden erstellt wurde. Fügen Sie dem Beschreibungsfeld keine Metadaten wie Dateinamen, programmatische Tags oder anderen automatisch generierten Text hinzu.

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

In diesem Beispiel wird Pseudocode verwendet, um das Hochladen von Medienelementen für mehrere Nutzenden. Ziel ist es, beide Schritte des Upload-Prozesses (Rohdaten-Uploads Bytes und Erstellen von Medienelementen) und Erläutern Sie die Best Practices zum Erstellen effizienter und stabiler Uploads.

Schritt 1: Rohbyte hochladen

Erstellen Sie zunächst eine Warteschlange, um die Rohbyte für Ihre Medienelemente von all Ihren Nutzenden. Verfolge jede zurückgegebene uploadToken pro Nutzer. Denken Sie an die folgenden wichtigen Punkte:

  • Die Anzahl der gleichzeitigen Upload-Threads hängt von zu verbessern.
  • Du kannst die Upload-Warteschlange nach Bedarf neu anordnen. Zum Beispiel könnten Sie Uploads basierend auf der Anzahl der verbleibenden Uploads pro Nutzer priorisieren, den Gesamtfortschritt der Nutzenden oder andere Anforderungen.

Pseudocode

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: Mediendateien 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.

Pseudocode

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

Fahren Sie mit diesem Vorgang fort, bis alle Uploads und Aufrufe zur Medienerstellung abgeschlossen sind.