Prześlij multimedia

Przesyłanie elementów multimedialnych przebiega w dwóch krokach:

  1. Prześlij bajty plików multimedialnych na serwer Google, korzystając z punktu końcowego przesyłania. Spowoduje to zwrócenie tokena przesyłania, który identyfikuje przesłane bajty.
  2. Użyj wywołania batchCreate z tokenem przesyłania, aby utworzyć element multimedialny na koncie Zdjęć Google użytkownika.

Poniżej znajdziesz informacje o procesie przesyłania pojedynczego elementu multimedialnego. Jeśli jesteś przesyłanie wielu elementów multimedialnych (prawdopodobnie w przypadku każdej aplikacji produkcyjnej), zapoznaj się ze sprawdzonymi metodami przesyłania, aby poprawić jakość efektywność przesyłania.

Zanim zaczniesz

Wymagane zakresy autoryzacji

Przesyłanie elementów multimedialnych do biblioteki lub albumu użytkownika wymaga: photoslibrary.appendonly lub zakres photoslibrary.

Elementy multimedialne można też tworzyć za pomocą zakresu photoslibrary.sharing. Do utwórz elementy o zakresie photoslibrary.sharing, najpierw musisz utworzyć i oznacz go jako udostępniony przy użyciu konta shareAlbum. Potem możesz tworzyć elementy multimedialne które są udostępniane użytkownikowi w albumie. Nie możesz tworzyć elementów bezpośrednio w w bibliotece użytkownika lub w albumach, które nie zostały udostępnione przez Twoją aplikację.

Przy wyświetlaniu listy albumów właściwość isWriteable wskazuje, czy Aplikacja ma dostęp do tworzenia multimediów w określonym albumie.

Akceptowane typy i rozmiary plików

Możesz przesyłać pliki wymienione w tabeli poniżej.

Typ nośnika Akceptowane typy plików Maksymalny rozmiar pliku
Zdjęcia AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, niektóre pliki RAW. 200 MB
Filmy 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV. 20 GB

Krok 1. Przesyłam bajty

Przesyłanie bajtów do Google za pomocą żądań przesyłania. Przesłano prośbę zwraca token przesyłania w postaci nieprzetworzonego ciągu tekstowego. Użyj tych przesłanych danych tokeny do tworzenia elementów multimedialnych z wywołaniem batchCreate.

REST

Uwzględnij te pola w nagłówku żądania POST:

Pola nagłówka
Content-type Ustaw jako: application/octet-stream.
X-Goog-Upload-Content-Type Zalecane. Ustaw typ MIME przesyłanych bajtów. Typowe typy MIME to image/jpeg, image/png i image/gif.
X-Goog-Upload-Protocol Ustaw jako: raw.

Oto nagłówek żądania POST:

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

W treści żądania umieść plik binarny pliku:

media-binary-data

Jeśli to żądanie POST zostanie zrealizowane, token przesyłania w postaci formularza nieprzetworzonego ciągu tekstowego, zwracany jako treść odpowiedzi. Aby utworzyć multimedia elementów, użyj tych ciągów tekstowych w wywołaniu batchCreate.

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
}

Sugerowany rozmiar pliku z obrazami nie przekracza 50 MB. Pliki powyżej 50 MB są podatne na problemy z wydajnością.

Interfejs Google Photos Library API obsługuje z możliwością wznowienia. Element, który można wznowić Prześlij umożliwia podzielenie pliku multimedialnego na kilka sekcji i przesłanie jednej pojedynczo.

Krok 2. Tworzenie elementu multimedialnego

Po przesłaniu bajtów plików multimedialnych możesz je utworzyć jako pliki multimedialne elementy w Zdjęciach Google za pomocą tokenów przesyłania. Token przesyłania jest prawidłowy przez 1 dzień od utworzenia. Element multimedialny jest zawsze dodawany bibliotece. Elementy multimedialne mogą być dodano do albumów utworzone przez Twoją aplikację. Więcej informacji znajdziesz w artykule na temat zakresów autoryzacji.

Aby utworzyć nowe elementy multimedialne, wywołaj polecenie mediaItems.batchCreate przez określenie listy newMediaItems. Każdy element newMediaItem zawiera przesłany plik token określony w tagu simpleMediaItem oraz opcjonalny opis które będą wyświetlane użytkownikowi.

Pole opisu może mieć maksymalnie 1000 znaków i powinno zawierać tylko tekstu tworzonego przez użytkowników. Na przykład „Nasza wycieczka do parku”. lub „Świąteczna kolacja”. Nie dodawaj metadanych, takich jak nazwy plików, informacje o automatyzacji tagów i innego automatycznie generowanego tekstu.

Aby uzyskać najlepszą skuteczność, zmniejsz liczbę połączeń do mediaItems.batchCreate które można utworzyć, uwzględniając wiele elementów multimedialnych w jednym wywołaniu. Zawsze czekaj dopóki poprzednie żądanie nie zostanie zrealizowane, a potem wywoła kolejne tego samego użytkownika.

Możesz utworzyć jeden element multimedialny lub wiele elementów multimedialnych w bibliotece użytkownika podając opisy i odpowiadające im tokeny przesyłania:

REST

Oto nagłówek żądania POST:

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

Treść żądania powinna zawierać listę tych elementów: newMediaItems.

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

Elementy multimedialne możesz dodać do biblioteki i do albumu, określając album id. Więcej informacji: Tworzenie albumów

Każdy album może zawierać do 20 000 elementów multimedialnych. Prośby o utworzenie multimediów elementy w albumie, które zostałyby przekroczone, nie będą obsługiwane.

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
}

Możesz też określić albumId i albumPosition, aby wstawić elementy multimedialne w określonym miejscu albumu.

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
}

Więcej informacji na temat pozycjonowania w albumach znajdziesz w sekcji Dodaj wzbogacanie.

Odpowiedź na utworzenie elementu

Wywołanie mediaItems.batchCreate zwraca wynik każdego elementu multimedialnego. którą próbowano utworzyć. Lista newMediaItemResults wskazuje stan i zawiera element uploadToken dla tego żądania. Kod stanu o wartości innej niż zero oznacza .

REST

Jeśli wszystkie elementy multimedialne zostały utworzone, żądanie zostanie zwrócone. Stan HTTP 200 OK. Jeśli nie można utworzyć niektórych elementów multimedialnych, żądanie zwraca stan HTTP 207 MULTI-STATUS wskazujący, częściowego sukcesu.

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

Jeśli udało się dodać element, zwracany jest element mediaItem zawierający: mediaItemId, productUrl i mediaMetadata. Więcej informacji: Dostęp do elementów multimedialnych.

Jeśli element multimedialny to film, musi zostać najpierw przetworzony. mediaItem zawiera ciąg status w elemencie mediaMetadata, który opisuje przetwarzanie pliku wideo. Nowo przesłany plik zwraca stan PROCESSING zanim będzie można go używać jako READY. Więcej informacji: Dostęp do elementów multimedialnych.

Jeśli podczas rozmowy napotkasz błąd, postępuj zgodnie z Sprawdzone metody i spróbuj jeszcze raz. Możesz śledzić pomyślne dodawanie, aby móc wstawiać obraz podczas następnej prośby o dostęp do albumu we właściwym miejscu. Więcej Więcej informacji zawiera Tworzenie albumów

Wyniki są zawsze zwracane w tej samej kolejności, w jakiej tokeny przesyłania przesłano.

Sprawdzone metody przesyłania

Te sprawdzone metody i zasoby pomogą Ci zwiększyć ogólną wydajność z przesłanymi filmami:

  • Użyj jednej z obsługiwanych bibliotek klienta.
  • Postępuj zgodnie ze sprawdzonymi metodami dotyczącymi ponawiania prób i postępowania w przypadku błędów. o następujących kwestiach:
    • Jeśli limit zostanie przekroczony, może wystąpić 429 błędu lub zbyt szybkie nawiązywanie zbyt wielu połączeń ogranicza liczbę połączeń. Upewnij się, nie wywołujesz funkcji batchCreate dla tego samego użytkownika aż do poprzedniego zrealizowano.
    • 429 błędu wymaga co najmniej 30s opóźnienia przed ponowną próbą. Użyj wykładniczy czas do ponowienia przy ponawianiu żądań.
    • Gdy serwer napotka błąd, występuje 500 błąd. Podczas przesyłania jest to najprawdopodobniej spowodowane wielokrotnymi wywołaniami zapisu (np. batchCreate) tego samego użytkownika. Sprawdź szczegóły: żądania i nie wykonuj równolegle wywołań funkcji batchCreate.
  • Skorzystaj z procedury wznawiania przesyłania, aby: bardziej niezawodne przesyłanie w przypadku przerw w sieci, wykorzystanie przepustowości sieci przez możliwość wznawiania częściowo zakończonego przesyłania. Jest to ważne, jeśli przesyłasz dane z urządzeń mobilnych klienta. podczas przesyłania dużych plików.

Na każdym etapie procesu przesyłania weź pod uwagę także te wskazówki: przesyłanie bajtów, a następnie tworzenie elementów multimedialnych.

Przesłane bajty

  • Równoległe przesyłanie bajtów (w celu pobrania tokenów przesyłania) można wykonać równolegle.
  • Zawsze ustawiaj prawidłowy typ MIME w nagłówku X-Goog-Upload-Content-Type. za każde wywołanie przesyłania.

Tworzenie elementów multimedialnych

  • Nie wywołuj połączenia równoległego do batchCreate dla tego samego użytkownika.

    • Wykonuj po kolei połączenia z numerem batchCreate (w seryjny).
    • W przypadku wielu użytkowników zawsze używaj batchCreate wywołań dla każdego z nich co jakiś czas. Wykonaj połączenia równoległe tylko do różnych użytkowników.
  • Uwzględnij jak najwięcej elementów NewMediaItems w każdym połączeniu z numerem batchCreate, by zminimalizować łączną liczbę połączeń i wykonania innych czynności. Możesz przesłać maksymalnie 50 elementów.

  • Dodaj odpowiedni tekst opisu. utworzone przez użytkowników. Nie dodawaj metadanych, takich jak nazw plików, tagów programowych ani innego automatycznie generowanego tekstu opis.

Przykładowy przewodnik

W tym przykładzie pokazano, jak przesyłać elementy multimedialne na potrzeby wielu użytkowników. Celem jest omówienie obu etapów procesu przesyłania (przesyłanie nieprzetworzonych danych B oraz tworzenie elementów multimedialnych) poznać sprawdzone metody tworzenia wydajnego i odpornego przesyłania i integrację społeczną.

Krok 1. Prześlij nieprzetworzone bajty

Najpierw utwórz kolejkę, by przesłać nieprzetworzone bajty elementów multimedialnych ze wszystkich użytkowników. Śledź każdą zwróconą kwotę uploadToken przypadającą na użytkownika. Pamiętaj o tych najważniejszych kwestiach:

  • Liczba jednoczesnych wątków przesyłania zależy od systemu operacyjnego dla środowiska.
  • W razie potrzeby rozważ zmianę kolejności w kolejce przesyłania. Możesz na przykład: ustala kolejność przesyłania na podstawie liczby filmów niezbędnych do przesłania na użytkownika, ogólne postępy użytkownika lub inne wymagania.

Pseudokod

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

Krok 2. Utwórz elementy multimedialne

W kroku 1 możesz przesłać równolegle kilka bajtów od różnych użytkowników, w kroku 2 możesz wykonać tylko jedno połączenie dla każdego użytkownika naraz.

Pseudokod

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

Kontynuuj ten proces, aż wszystkie operacje przesyłania i tworzenia multimediów zostaną zakończone.