Medien hochladen

Das Hochladen von Medienelementen erfolgt in zwei Schritten:

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

Im Folgenden wird beschrieben, wie Sie ein einzelnes Medienelement hochladen. Wenn Sie mehrere Mediaelemente hochladen (wahrscheinlich für eine beliebige Produktionsanwendung), lesen Sie die Best Practices für Uploads, um die Uploadeffizienz zu verbessern.

Hinweis

Erforderliche Autorisierungsbereiche

Zum Hochladen von Medienelementen in die Mediathek oder das Album eines Nutzers ist entweder photoslibrary.appendonly oder photoslibrary erforderlich.

Mediaelemente können auch mit dem Gültigkeitsbereich photoslibrary.sharing erstellt werden. Um Elemente mit dem Geltungsbereich photoslibrary.sharing zu erstellen, müssen Sie zuerst ein Album erstellen und es mithilfe von shareAlbum als freigegeben markieren. Dann können Sie Medienelemente erstellen, die für die Nutzer im Album freigegeben werden. Sie können Elemente nicht direkt in der Mediathek des Nutzers oder in Alben erstellen, die Ihre App nicht geteilt hat.

Beim Auflisten von Alben gibt das Attribut isWriteable an, ob Ihre Anwendung Zugriff 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: Bytes hochladen

Laden Sie Bytes mithilfe von Uploadanfragen auf Google hoch. Bei einer erfolgreichen Uploadanfrage wird ein Uploadtoken in Form eines Rohtextstrings zurückgegeben. Verwenden Sie diese Uploadtokens, um Medienelemente mit dem Aufruf batchCreate zu erstellen.

Hinweis :Alle Medienelemente, die über die API in Google Fotos hochgeladen werden, werden in voller Auflösung und Originalqualität gespeichert. Wenn Ihre Uploads 25 MB pro Nutzer überschreiten, sollte Ihre Anwendung den Nutzer daran erinnern, dass diese Uploads auf den Speicherplatz in seinem Google-Konto angerechnet werden.

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 den MIME-Typ der hochzuladenden Byte 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-Anfrageheader:

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 die Binärdatei der Datei in den Anfragetext ein:

media-binary-data

Wenn diese POST-Anfrage erfolgreich ist, wird ein Upload-Token in Form eines Rohtextstrings als Antworttext zurückgegeben. Verwenden Sie zum Erstellen von Medienelementen 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. Bei Dateien über 50 MB kann es zu Leistungsproblemen kommen.

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

Schritt 2: Medienelement erstellen

Nachdem du die Bytes deiner Mediendateien hochgeladen hast, kannst du sie mithilfe von Uploadtokens als Medienobjekte in Google Fotos erstellen. Ein Uploadtoken ist nach der Erstellung einen Tag lang gültig. Medienelemente werden immer der Mediathek des Nutzers hinzugefügt. Medienelemente können nur Alben hinzugefügt werden, die von Ihrer Anwendung erstellt wurden. Weitere Informationen finden Sie unter Autorisierungsbereiche.

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

Das Beschreibungsfeld ist auf 1.000 Zeichen beschränkt und sollte nur aussagekräftigen Text enthalten, der von Nutzern erstellt wurde. Beispiele: Unser Ausflug in den Park oder Feiertagsabendessen. Fügen Sie keine Metadaten wie Dateinamen, programmatische Tags oder anderen automatisch generierten Text ein.

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

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

REST

Hier ist der POST-Anfrageheader:

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 Mediathek und einem Album Medienelemente hinzufügen, indem du das Album id angibst. Weitere Informationen finden Sie unter Alben erstellen.

Jedes Album kann bis zu 20.000 Medienelemente enthalten. Anfragen zum Erstellen von Medienelementen in einem Album, die dieses Limit ü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
}

Du kannst auch albumId und albumPosition angeben, um Medienelemente an einer bestimmten Stelle im Album einzufü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.

Warnung: Der Aufruf batchCreate beschränkt die Anzahl der in einem Aufruf erstellten Medienelemente auf 50. Außerdem empfiehlt es sich nicht, mehrere batchCreate gleichzeitig für denselben Nutzer aufzurufen.

Antwort auf die Erstellung eines Elements

Der Aufruf mediaItems.batchCreate gibt das Ergebnis für jedes Medienelement zurück, das Sie erstellen wollten. 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.

REST

Wurden alle Medienelemente erfolgreich erstellt, gibt die Anfrage den HTTP-Status 200 OK zurück. Wenn einige Medienelemente nicht erstellt werden können, gibt die Anfrage den HTTP-Status 207 MULTI-STATUS zurück, um auf einen teilweisen Erfolg hinzuweisen.

{
  "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 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. mediaItem enthält ein status innerhalb des mediaMetadata, das den Verarbeitungsstatus der Videodatei beschreibt. Eine neu hochgeladene Datei gibt zuerst den Status PROCESSING zurück, bevor die Datei READY verwendet werden kann. Weitere Informationen finden Sie unter Auf Medienelemente zugreifen.

Wenn bei diesem Aufruf ein Fehler auftritt, folgen Sie den Best Practices und wiederholen Sie die Anfrage. Wenn Sie wissen, welche Bilder hinzugefügt wurden, kann das Bild bei der nächsten Anfrage an der richtigen Stelle ins Album eingefügt werden. Weitere Informationen finden Sie unter Alben erstellen.

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

Hinweis: Dasselbe Medienelement (definiert als dieselben Byte, die hochgeladen werden) wird als dasselbe Objekt behandelt. Das bedeutet, dass dasselbe Medienelement-id zurückgegeben wird, auch wenn es durch eine andere uploadToken referenziert wird.

Best Practices für Uploads

Die folgenden Best Practices und Ressourcen helfen Ihnen, Ihre Effizienz durch Uploads zu verbessern:

• Verwenden Sie eine unserer unterstützten Clientbibliotheken.
• Folgen Sie den Best Practices für Wiederholungen und Fehlerbehandlung und beachten Sie dabei die folgenden Punkte:
  • 429-Fehler können auftreten, wenn Ihr Kontingent erschöpft ist oder Sie aufgrund zu vieler Aufrufe ein Limit haben. Rufen Sie batchCreate erst dann für denselben Nutzer auf, wenn die vorherige Anfrage abgeschlossen ist.
  • Bei 429 Fehlern ist eine Verzögerung von mindestens 30s erforderlich, bevor es wiederholt wird. Verwenden Sie beim Wiederholen von Anfragen einen exponentiellen Backoff.
  • 500-Fehler treten auf, wenn auf dem Server ein Fehler festgestellt wird. Beim Hochladen liegt dies höchstwahrscheinlich daran, dass mehrere Schreibaufrufe (z. B. batchCreate) für denselben Nutzer gleichzeitig ausgeführt werden. Prüfen Sie die Details Ihrer Anfrage und rufen Sie batchCreate nicht parallel auf.
• Mit dem Ablauf des fortsetzbaren Uploads können Sie Ihre Uploads bei Netzwerkunterbrechungen robuster machen und die Bandbreitennutzung reduzieren, indem Sie teilweise abgeschlossene Uploads fortsetzen. Das ist wichtig, wenn Sie Daten über Mobilgeräte von Clients oder große Dateien hochladen.

Beachten Sie außerdem die folgenden Tipps für jeden Schritt des Uploadprozesses: Byte hochladen und dann Mediaelemente erstellen.

Bytes werden hochgeladen

• 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 werden erstellt

• Führen Sie für einen einzelnen Nutzer keine Aufrufe parallel zu batchCreate aus.

  • Rufen Sie für jeden Nutzer nacheinander batchCreate auf.
  • Bei mehreren Nutzern führen Sie immer batchCreate-Aufrufe für jeden Nutzer nach dem anderen aus. Rufen Sie nur gleichzeitig verschiedene Nutzer auf.

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

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

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

In diesem Beispiel wird Pseudocode verwendet, um Medienelemente für mehrere Nutzer hochzuladen. Ziel ist es, beide Schritte des Uploadprozesses (Hochladen von Rohbyte und Erstellen von Medienelementen) zu beschreiben und die Best Practices für eine effiziente und stabile Uploadintegration zu erläutern.

Schritt 1: Rohbyte hochladen

Erstellen Sie zuerst eine Warteschlange, um die Rohbyte für Ihre Medienelemente von allen Nutzern hochzuladen. Alle zurückgegebenen uploadToken pro Nutzer erfassen. Denken Sie an die folgenden wichtigen Punkte:

• Die Anzahl der gleichzeitigen Upload-Threads hängt von Ihrer Betriebsumgebung ab.
• Sie können die Upload-Warteschlange nach Bedarf neu anordnen. Beispielsweise können Sie Uploads anhand der Anzahl der verbleibenden Uploads pro Nutzer, des Gesamtfortschritts eines Nutzers oder anderer Anforderungen priorisieren.

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: Medienelemente erstellen

In Schritt 1 können Sie mehrere Bytes von mehreren Nutzern gleichzeitig hochladen. In Schritt 2 können Sie jedoch nur einen einzigen Aufruf für jeden Nutzer gleichzeitig senden.

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.

Führen Sie diesen Vorgang so lange fort, bis alle Uploads und Aufrufe zur Medienerstellung abgeschlossen sind.