Przesyłanie elementów multimedialnych przebiega w dwóch krokach:
- 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.
- 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 funkcjibatchCreate
dla tego samego użytkownika aż do poprzedniego zrealizowano. 429
błędu wymaga co najmniej30s
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ń funkcjibatchCreate
.
- Jeśli limit zostanie przekroczony, może wystąpić
- 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.
- Wykonuj po kolei połączenia z numerem
Uwzględnij jak najwięcej elementów
NewMediaItems
w każdym połączeniu z numerembatchCreate
, 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.