Prześlij multimedia

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

  1. Prześlij bajty plików multimedialnych na serwer Google za pomocą punktu końcowego przesyłania plików. Zwraca token przesyłania, który identyfikuje przesłane bajty.
  2. Za pomocą wywołania batchCreate z tokenem przesyłania możesz utworzyć element multimedialny na koncie Zdjęć Google użytkownika.

Te czynności opisują proces przesyłania pojedynczego elementu multimedialnego. Jeśli przesyłasz wiele elementów multimedialnych (co jest bardzo prawdopodobne w przypadku każdej aplikacji produkcyjnej), zapoznaj się ze sprawdzonymi metodami dotyczącymi 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 uprawnień photoslibrary.appendonly. Więcej informacji o zakresach znajdziesz w artykule Zakresy autoryzacji.

Akceptowane typy i rozmiary plików

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

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łanie bajtów

Przesyłanie bajtów do Google za pomocą żądań przesyłania. Pomyślnie przetworzone żądanie przesyłania zwraca token przesyłania w postaci zwykłego ciągu tekstowego. Użyj tych tokenów przesyłania, aby utworzyć elementy multimediów za pomocą wywołania batchCreate.

REST

W nagłówku żądania POST umieść te pola:

Pola nagłówka
Content-type Ustaw jako: application/octet-stream.
X-Goog-Upload-Content-Type Zalecane. Ustaw na typ MIME przesyłanych bajtów. 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 dołącz plik binarny: 

media-binary-data

Jeśli to żądanie POST się powiedzie, jako treść odpowiedzi zwrócony zostanie token przesyłania w postaci łańcucha tekstowego. Aby utworzyć elementy multimediów, użyj tych ciągów tekstowych w wywołaniu batchCreate.

upload-token

Sugerowany rozmiar pliku obrazu to mniej niż 50 MB. Przy plikach większych niż 50 MB mogą występować problemy z wydajnością.

Interfejs Google Photos Library API obsługuje przerywane przesyłanie plików. Przesyłanie z możliwością wznowienia umożliwia podzielenie pliku multimedialnego na kilka sekcji i przesłanie jednej sekcji naraz.

Krok 2. Tworzenie elementu multimedialnego

Po przesłaniu bajtów plików multimedialnych możesz utworzyć je jako elementy multimedialne w Zdjęciach Google, używając 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 aplikację. Więcej informacji znajdziesz w sekcji Zakresy autoryzacji.

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

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

Aby uzyskać najlepszą wydajność, zmniejsz liczbę wywołań mediaItems.batchCreate, które musisz wykonać, uwzględniając w jednym wywołaniu wiele elementów multimedialnych. Przed nawiązaniem kolejnego wywołania tego samego użytkownika zawsze poczekaj, aż poprzednie żądanie zostanie zrealizowane.

Możesz utworzyć jeden 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ę elementów newMediaItems.

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

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

REST

{
  "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 informacji dodatkowych.

Odpowiedź na utworzenie elementu

Wywołanie mediaItems.batchCreate zwraca wynik dla każdego z multimediów, które próbujesz utworzyć. Lista newMediaItemResults wskazuje stan i zawiera uploadToken prośby. Kod stanu inny niż 0 wskazuje błąd.

REST

Jeśli wszystkie elementy multimedialne zostały utworzone, żądanie zwraca stan HTTP 200 OK. Jeśli nie można utworzyć niektórych elementów multimedialnych, żądanie zwraca kod stanu HTTP 207 MULTI-STATUS, aby wskazać częściowy sukces.

{
  "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, zwrócony zostanie obiekt mediaItem zawierający wartości mediaItemId, productUrl i mediaMetadata. Więcej informacji znajdziesz w artykule Dostęp do multimediów.

Jeśli element multimedialny to film, musi zostać najpierw przetworzony. mediaItem zawiera w elemencie mediaMetadata element status, który opisuje stan przetwarzania pliku wideo. Nowo przesłany plik zwraca najpierw stan PROCESSING, zanim będzie można go READY. Więcej informacji znajdziesz w artykule Dostęp do multimediów.

Jeśli podczas rozmowy wystąpi błąd, postępuj zgodnie z najlepszymi praktykami i ponownie wyślij prośbę. Możesz śledzić dodane obrazy, aby w następnym żądaniu wstawić je w albumie we właściwym miejscu. Więcej informacji znajdziesz w artykule Tworzenie albumów.

Wyniki są zawsze zwracane w takim samym porządku, w jakim zostały przesłane tokeny przesyłania.

Sprawdzone metody przesyłania

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

  • Stosuj sprawdzone metody dotyczące prób i błędów, pamiętając o tych kwestiach:
    • Błędy 429 mogą wystąpić, gdy zostanie wyczerpana Twoja pula lub gdy zostaniesz ograniczony pod względem szybkości wykonywania wywołań. Dopóki poprzednie żądanie nie zostanie wykonane, nie wywołuj funkcji batchCreate w przypadku tego samego użytkownika.
    • 429 błędu wymaga co najmniej 30s opóźnienia przed ponowną próbą. Przy ponawianiu żądań używaj strategii wykładniczego czasu do ponowienia.
    • Błędy 500 występują, gdy serwer napotka błąd. Podczas przesyłania jest to najprawdopodobniej spowodowane wywołaniem wielu metod zapisu (takich jak batchCreate) dla tego samego użytkownika w tym samym czasie. Sprawdź szczegóły żądania i nie wywołuj równolegle pola batchCreate.
  • Użyj przesyłania z możliwością wznowienia, aby przesyłane treści były bardziej niezawodne w przypadku przerw w działaniu sieci. Pozwoli Ci to zmniejszyć wykorzystanie przepustowości, umożliwiając wznowienie częściowo ukończonego przesyłania. Jest to ważne podczas przesyłania plików z urządzeń mobilnych klienta lub dużych plików.

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

Przesłane bajty

  • Przesyłanie bajtów (aby pobrać tokeny przesyłania) może odbywać się równolegle.
  • W przypadku każdego wywołania przesyłania zawsze ustawiaj prawidłowy typ MIME w nagłówku X-Goog-Upload-Content-Type.

Tworzenie elementów multimedialnych

  • Nie należy wykonywać równoległych połączeń batchCreate dla jednego użytkownika.

    • W przypadku każdego użytkownika wywołuj funkcję batchCreate kolejno (w serii).
    • W przypadku wielu użytkowników zawsze wywołuj funkcję batchCreate dla każdego z nich po kolei. Równolegle wywołuj połączenia tylko dla różnych użytkowników.

  • Dodaj jak najwięcej NewMediaItems do każdego wywołania funkcji batchCreate, aby zminimalizować łączną liczbę wywołań. Możesz dodać maksymalnie 50 elementów.

  • Ustaw tekst opisu, który został utworzony przez użytkowników. W polu opisu nie podawaj takich metadanych, jak nazwy plików, tagi automatyczne czy tekst generowany automatycznie.

Przykładowy przewodnik

W tym przykładzie za pomocą pseudokodu pokazano przesyłanie elementów multimedialnych dla wielu użytkowników. Celem jest przedstawienie obu etapów procesu przesyłania (przesyłanie surowych bajtów i tworzenie elementów multimedialnych) oraz podanie szczegółowych sprawdzonych metod tworzenia wydajnej i odpornej integracji przesyłania.

Krok 1. Prześlij nieprzetworzone bajty

Najpierw utwórz kolejkę do przesyłania surowych bajtów elementów multimedialnych od wszystkich użytkowników. Śledź każdy zwrócony wynik uploadToken dla każdego użytkownika. Pamiętaj o tych kwestiach:

  • Liczba jednoczesnych wątków przesyłania zależy od środowiska operacyjnego.
  • W razie potrzeby zmień kolejność w kolejce przesyłania. Możesz na przykład ustalić priorytety przesyłania na podstawie liczby przesłanych plików przypadających na użytkownika, jego ogólnych postępów lub innych wymagań.

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 przesyłać równolegle wiele bajtów od wielu użytkowników, ale w kroku 2 możesz wykonać tylko jedno wywołanie dla każdego użytkownika.

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 wywołania do przesyłania i tworzenia multimediów zostaną zakończone.