Prześlij multimedia

Przesyłanie elementów multimedialnych to proces dwuetapowy:

1. Prześlij bajty plików multimedialnych na serwer Google za pomocą punktu końcowego uploads. Zwraca token 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 opisujemy proces przesyłania pojedynczego elementu multimedialnego. Jeśli przesyłasz wiele plików multimedialnych (co jest bardzo prawdopodobne w przypadku każdej aplikacji produkcyjnej), zapoznaj się ze sprawdzonymi metodami przesyłania, aby zwiększyć wydajność przesyłania.

Zanim zaczniesz

Wymagane zakresy autoryzacji

Przesyłanie elementów multimedialnych do biblioteki lub albumu użytkownika wymaga zakresu photoslibrary.appendonly. Więcej informacji o zakresach znajdziesz w artykule Zakresy autoryzacji.

Akceptowane typy i rozmiary plików

Możesz przesłać typy plików wymienione w tej tabeli.

Krok 1. Przesyłanie bajtów

Przesyłaj bajty do Google za pomocą żądań przesyłania. W przypadku udanego żądania przesłania zwracany jest token przesyłania w postaci ciągu tekstowego. Użyj tych tokenów przesyłania, aby utworzyć elementy multimedialne za pomocą wywołania batchCreate.

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

Sugerowany rozmiar pliku obrazu to mniej niż 50 MB. Pliki większe niż 50 MB mogą powodować problemy z wydajnością.

Interfejs Google Photos Library API obsługuje wznawialne przesyłanie. Przesyłanie z możliwością wznowienia umożliwia podzielenie pliku multimedialnego na kilka sekcji i przesyłanie ich pojedynczo.

Krok 2. Tworzenie elementu multimedialnego

Po przesłaniu bajtów plików multimedialnych możesz utworzyć z nich elementy multimedialne w Zdjęciach Google za pomocą tokenów przesyłania. Token przesyłania jest ważny przez 1 dzień od utworzenia. Element multimedialny jest zawsze dodawany do biblioteki użytkownika. Elementy multimedialne można dodawać tylko do albumów utworzonych przez Twoją aplikację. Więcej informacji znajdziesz w sekcji Zakresy autoryzacji.

Aby utworzyć nowe elementy multimedialne, wywołaj mediaItems.batchCreate określając listę newMediaItems. Każdy element newMediaItem zawiera token przesyłania określony w elemencie simpleMediaItem oraz opcjonalny opis wyświetlany użytkownikowi.

Pole opisu jest ograniczone do 1000 znaków i powinno zawierać tylko istotny tekst utworzony przez użytkowników. Na przykład „Wycieczka do parku” lub „Świąteczna kolacja”. Nie dodawaj metadanych, takich jak nazwy plików, tagi programowe ani inne automatycznie generowane teksty.

Aby uzyskać najlepszą wydajność, zmniejsz liczbę wywołań funkcji mediaItems.batchCreate, uwzględniając w jednym wywołaniu wiele elementów multimedialnych. Zanim wywołasz kolejną funkcję dla tego samego użytkownika, zawsze poczekaj, aż poprzednia prośba zostanie zrealizowana.

Możesz utworzyć jeden lub kilka elementów multimedialnych w bibliotece użytkownika, podając opisy i odpowiednie tokeny przesyłania:

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

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

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

Więcej informacji o pozycjonowaniu w albumach znajdziesz w artykule Dodawanie ulepszeń.

Odpowiedź na utworzenie elementu

Wywołanie mediaItems.batchCreate zwraca wynik dla każdego elementu multimedialnego, który został utworzony. Lista newMediaItemResults wskazuje stan i zawiera uploadToken dla żądania. Kod stanu różny od zera oznacza błąd.

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

Jeśli element zostanie dodany, zwracany jest kod mediaItem zawierający jego mediaItemId, productUrl i mediaMetadata. Więcej informacji znajdziesz w artykule Dostęp do plików multimedialnych.

Jeśli element multimedialny jest filmem, musi zostać najpierw przetworzony. Element mediaItem zawiera element status w swoim elemencie mediaMetadata, który opisuje stan przetwarzania pliku wideo. Nowo przesłany plik najpierw zwraca stan PROCESSING, a dopiero potem jest READY. Więcej informacji znajdziesz w artykule Uzyskiwanie dostępu do elementów multimedialnych.

Jeśli podczas rozmowy wystąpi błąd, postępuj zgodnie z najlepszymi praktykami i ponów próbę. Warto śledzić udane dodania, aby podczas następnego żądania można było wstawić obraz do albumu we właściwym miejscu. Więcej informacji znajdziesz w artykule Tworzenie albumów.

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

Sprawdzone metody przesyłania

Te sprawdzone metody i zasoby pomogą Ci zwiększyć ogólną efektywność przesyłania:

• Postępuj zgodnie ze sprawdzonymi metodami dotyczącymi ponawiania prób i obsługi błędów, pamiętając o tych kwestiach:
  • Błędy 429 mogą wystąpić, gdy wyczerpiesz limit lub gdy zostaną nałożone na Ciebie ograniczenia szybkości z powodu zbyt dużej liczby wywołań w krótkim czasie. Nie wywołuj funkcji batchCreate dla tego samego użytkownika, dopóki nie zostanie zakończone poprzednie żądanie.
  • Błędy 429 wymagają co najmniej 30s opóźnienia przed ponowną próbą. Podczas ponawiania żądań stosuj strategię wzrastającego czasu do ponowienia.
  • Błędy 500 występują, gdy serwer napotka błąd. Podczas przesyłania jest to najprawdopodobniej spowodowane wykonywaniem wielu wywołań zapisu (np. batchCreate) dla tego samego użytkownika w tym samym czasie. Sprawdź szczegóły żądania i nie wykonuj równolegle wywołań do batchCreate.
• Użyj przepływu przesyłania z możliwością wznowienia, aby zwiększyć niezawodność przesyłania w przypadku przerw w działaniu sieci. Zmniejszysz też zużycie przepustowości, ponieważ będziesz mieć możliwość wznowienia częściowo zakończonego przesyłania. Jest to ważne podczas przesyłania plików z urządzeń mobilnych klientów lub przesyłania dużych plików.

Zapoznaj się też z tymi wskazówkami dotyczącymi poszczególnych etapów procesu przesyłania: przesyłania bajtów, a następnie tworzenia elementów multimedialnych.

Przesyłanie bajtów

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

Tworzenie elementów multimedialnych

• Nie wykonuj połączeń równolegle z batchCreate w przypadku jednego użytkownika.

  • Dla każdego użytkownika wykonuj wywołania funkcji batchCreate jedno po drugim (sekwencyjnie).
  • W przypadku wielu użytkowników zawsze wykonuj wywołania batchCreate dla każdego użytkownika po kolei. Wykonuj połączenia równolegle tylko w przypadku różnych użytkowników.

• W każdym wywołaniu funkcji batchCreate umieszczaj jak najwięcej NewMediaItems, aby zminimalizować łączną liczbę wywołań, które musisz wykonać. Możesz uwzględnić maksymalnie 50 elementów.

• Ustaw odpowiedni tekst opisu utworzony przez użytkowników. W polu opisu nie umieszczaj metadanych, takich jak nazwy plików, tagi automatyzacji czy inne automatycznie generowane teksty.

Przykładowy przewodnik

W tym przykładzie używamy pseudokodu, aby przedstawić proces przesyłania plików multimedialnych dla wielu użytkowników. Celem jest przedstawienie obu etapów procesu przesyłania (przesyłania surowych bajtów i tworzenia elementów multimedialnych) oraz szczegółowe omówienie sprawdzonych metod tworzenia wydajnej i odpornej integracji przesyłania.

Krok 1. Prześlij surowe bajty

Najpierw utwórz kolejkę, aby przesyłać surowe bajty elementów multimedialnych od wszystkich użytkowników. Śledź każdy zwrócony parametr uploadToken dla każdego użytkownika. Pamiętaj o tych najważniejszych kwestiach:

• Liczba wątków przesyłania równoległego zależy od środowiska operacyjnego.
• W razie potrzeby zmień kolejność w kolejce przesyłania. Możesz na przykład ustalać priorytety przesyłania na podstawie liczby pozostałych do przesłania plików na użytkownika, ogólnych postępów użytkownika lub innych wymagań.

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. Tworzenie elementów multimedialnych

W kroku 1 możesz przesyłać równolegle wiele bajtów od wielu użytkowników, ale w kroku 2 możesz wykonywać tylko jedno wywołanie dla każdego użytkownika naraz.

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

Powtarzaj ten proces, aż wszystkie wywołania przesyłania i tworzenia multimediów zostaną ukończone.