Das Hochladen von Medienelementen erfolgt in zwei Schritten:
- Laden Sie die Byte Ihrer Mediendateien über den Upload-Endpunkt auf einen Google-Server hoch. Dadurch wird ein Upload-Token zurückgegeben, das die hochgeladenen Byte identifiziert.
- 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) In den Best Practices für Uploads erfährst du, wie du deine effizienter hochladen.
Hinweis
Erforderliche Autorisierungsbereiche
Zum Hochladen von Medienelementen in die Bibliothek oder das Album eines Nutzers ist entweder die
photoslibrary.appendonly
- oder photoslibrary
-Bereich.
Medienelemente können auch mit dem Bereich photoslibrary.sharing
erstellt werden. Bis
zum Erstellen von Elementen mit dem Bereich photoslibrary.sharing
erstellen, müssen Sie zuerst ein
Album und markieren Sie es mit shareAlbum
als geteilt. Anschließend kannst du Medieninhalte erstellen
die für den Nutzer im Album freigegeben sind. Sie können Elemente nicht direkt in
in der Mediathek des Nutzers oder in Alben, die nicht über Ihre App geteilt wurden.
Beim Auflisten von Alben gibt die Eigenschaft isWriteable
an, ob Ihr
-Anwendung die Berechtigung zum Erstellen von Medien in einem bestimmten Album hat.
Zulässige Dateitypen und ‐größen
Sie können die in der folgenden Tabelle aufgeführten Dateitypen hochladen.
Medientyp | Zulässige Dateitypen | Maximale Dateigröße |
---|---|---|
Fotos | AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, 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 im Header der POST-Anfrage die folgenden Felder 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.
Zu den gängigen MIME-Typen gehören 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
Java
// Open the file and automatically close it after upload try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) { // Create a new upload request UploadMediaItemRequest uploadRequest = UploadMediaItemRequest.newBuilder() // The media type (e.g. "image/png") .setMimeType(mimeType) // The file to upload .setDataFile(file) .build(); // Upload and capture the response UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest); if (uploadResponse.getError().isPresent()) { // If the upload results in an error, handle it Error error = uploadResponse.getError().get(); } else { // If the upload is successful, get the uploadToken String uploadToken = uploadResponse.getUploadToken().get(); // Use this upload token to create a media item } } catch (ApiException e) { // Handle error } catch (IOException e) { // Error accessing the local file }
PHP
try { // Create a new upload request by opening the file // and specifying the media type (e.g. "image/png") $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType); } catch (\GuzzleHttp\Exception\GuzzleException $e) { // Handle error }
Die empfohlene Dateigröße für Bilder beträgt weniger als 50 MB. Dateien mit mehr als 50 MB werden anfällig für Leistungsprobleme ist.
Die Google Photos Library API unterstützt fortsetzbare Uploads. Eine fortsetzbare Mit dem Upload kannst du eine Mediendatei in mehrere Abschnitte unterteilen und einen Abschnitt für Abschnitt.
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 zu Alben hinzugefügt die von Ihrer App erstellt wurden. Weitere Informationen finden Sie unter Autorisierungsbereiche.
Rufen Sie zum Erstellen neuer Medienelemente
mediaItems.batchCreate
indem Sie eine Liste von newMediaItems
angeben. Jedes newMediaItem
enthält einen Upload
Token, das in einem simpleMediaItem
angegeben wird, und einer optionalen Beschreibung
die der Nutzer sieht.
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.
Reduzieren Sie die Anzahl der Aufrufe für mediaItems.batchCreate
, um die Leistung zu optimieren
indem Sie mehrere Medienelemente
in einen Aufruf aufnehmen. Immer warten
bis die vorherige Anforderung abgeschlossen ist, bevor ein weiterer Aufruf für die
über denselben Nutzer.
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" } } , ... ] }
Java
try { // Create a NewMediaItem with the following components: // - uploadToken obtained from the previous upload request // - filename that will be shown to the user in Google Photos // - description that will be shown to the user in Google Photos NewMediaItem newMediaItem = NewMediaItemFactory .createNewMediaItem(uploadToken, fileName, itemDescription); List<NewMediaItem> newItems = Arrays.asList(newMediaItem); BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems); for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) { Status status = itemsResponse.getStatus(); if (status.getCode() == Code.OK_VALUE) { // The item is successfully created in the user's library MediaItem createdItem = itemsResponse.getMediaItem(); } else { // The item could not be created. Check the status and try again } } } catch (ApiException e) { // Handle error }
PHP
try { $newMediaItems = []; // Create a NewMediaItem with the following components: // - uploadToken obtained from the previous upload request // - filename that will be shown to the user in Google Photos // - description that will be shown to the user in Google Photos $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName( $uploadToken, $itemDescription, $fileName); $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems); foreach ($response->getNewMediaItemResults() as $itemResult) { $status = $itemResult->getStatus(); if ($status->getCode() != Code::OK) { // Error while creating the item. } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Du kannst der Bibliothek und einem Album Medienelemente hinzufügen, indem du die
Album id
. Weitere Informationen finden Sie unter
Alben erstellen
Jedes Album kann bis zu 20.000 Medienelemente enthalten. Anfragen zum Erstellen von Medien Elemente in einem Album, die diese Beschränkung überschreiten würden, schlagen fehl.
REST
{ "albumId": "album-id", "newMediaItems": [ { "description": "item-description", "simpleMediaItem": { "fileName": "filename", "uploadToken": "upload-token" } } , ... ] }
Java
try { // Create new media items in a specific album BatchCreateMediaItemsResponse response = photosLibraryClient .batchCreateMediaItems(albumId, newItems); // Check the response } catch (ApiException e) { // Handle error }
PHP
try { $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
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" } }
Java
try { // Create new media items in a specific album, positioned after a media item AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum(); BatchCreateMediaItemsResponse response = photosLibraryClient .batchCreateMediaItems(albumId, newItems, positionInAlbum); // Check the response } catch (ApiException e) { // Handle error }
PHP
try { $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId); $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId, 'albumPosition' => $albumPosition]); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Weitere Informationen zur Positionierung in Alben finden Sie unter Anreicherungen hinzufügen:
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 steht für
Fehler.
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" } } ] }
Java
BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems); // The response contains a list of NewMediaItemResults for (NewMediaItemResult result : response.getNewMediaItemResultsList()) { // Each result item is identified by its uploadToken String uploadToken = result.getUploadToken(); Status status = result.getStatus(); if (status.getCode() == Code.OK_VALUE) { // If the request is successful, a MediaItem is returned MediaItem mediaItem = result.getMediaItem(); String id = mediaItem.getId(); String productUrl = mediaItem.getProductUrl(); // ... } }
PHP
// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults foreach ($response->getNewMediaItemResults() as $itemResult) { // Each result item is identified by its uploadToken $itemUploadToken = $itemResult->getUploadToken(); // Verify the status of each entry to ensure that the item has been uploaded correctly $itemStatus = $itemResult->getStatus(); if ($itemStatus->getCode() != Code::OK) { // Error when item is being created } else { // Media item is successfully created // Get the MediaItem object from the response $mediaItem = $itemResult->getMediaItem(); // It contains details such as the Id of the item, productUrl $id = $mediaItem->getId(); $productUrl = $mediaItem->getProductUrl(); // ... } }
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
Wenn während dieses Anrufs ein Fehler auftritt, folgen Sie der Anleitung Best Practices und wiederholen Sie Ihre Anfrage. Es empfiehlt sich, den Überblick über erfolgreiche Ergänzungen zu behalten, damit das Bild eingefügt werden kann. bei der nächsten Anfrage an die richtige Position in das Album verschieben. Weitere Informationen finden Sie unter Alben erstellen
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:
- Verwenden Sie eine unserer unterstützten Clientbibliotheken.
- Folgen Sie den Best Practices für Wiederholungen und Fehlerbehandlung.
Beachten Sie dabei Folgendes:
<ph type="x-smartling-placeholder">
- </ph>
429
-Fehler können auftreten, wenn Ihr Kontingent erschöpft ist. oder die Ratenbegrenzung überschritten wird, weil zu viele Anrufe zu schnell getätigt wurden. Achten Sie darauf, Sie rufenbatchCreate
für denselben Nutzer erst beim vorherigen abgeschlossen ist.429
-Fehler erfordern eine Mindestverzögerung von30s
, bevor sie es noch einmal versuchen. Verwenden Sie exponentieller Backoff wenn Sie Anfragen wiederholen.500
-Fehler treten auf, wenn auf dem Server ein Fehler auftritt. 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 SiebatchCreate
nicht parallel auf.
- Nutzen Sie den Ablauf des fortsetzbaren Uploads für folgende Aktionen: machen deine Uploads bei Netzwerkunterbrechungen robuster und Bandbreitennutzung, da teilweise abgeschlossene Uploads fortgesetzt werden können. Dies ist wichtig beim Hochladen über Client-Mobilgeräte oder wenn Sie große Dateien hochladen.
Beachten Sie außerdem die folgenden Tipps für die einzelnen Schritte des Upload-Vorgangs: Bytes hochladen und anschließend Medien erstellen
Bytes werden hochgeladen
- Das Hochladen von Bytes (zum Abrufen von Uploadtokens) kann parallel erfolgen.
- Legen Sie im
X-Goog-Upload-Content-Type
-Header immer den richtigen MIME-Typ fest. für jeden Upload-Aufruf.
Medien werden erstellt
Führen Sie für einen einzelnen Nutzer keine parallelen Aufrufe zu
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.
- Starten Sie für jeden Nutzer nacheinander
So viele
NewMediaItems
wie möglich einbeziehen in jedem Aufruf vonbatchCreate
, 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 keine Metadaten wie Dateinamen, programmatische Tags oder anderen automatisch generierten Text in der Datei Beschreibung eingeben.
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 allen 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 gleichzeitig hochladen, Schritt 2 können Sie für jeden Nutzer jeweils nur einen Aufruf starten.
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.