Medien hochladen

Das Hochladen von Medienelementen erfolgt in zwei Schritten:

1. 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.
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) 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.

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.

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

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

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:

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"
      }
    }
   , ...
  ]
}

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
}

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.

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

try {
  // Create new media items in a specific album
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

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.

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

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
}

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.

{
  "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"
      }
    }
  ]
}

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();
    // ...
  }
}

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

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

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.

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