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ą funkcji przesyłania . Zwraca ono token przesyłania, który identyfikuje przesłanych bajtów.
  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 dowiedzieć się, jak ulepszyć przesyłanie. efektywność.

Zanim zaczniesz

Wymagane zakresy autoryzacji

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

Akceptowane typy i rozmiary plików

Możesz przesyłać typy plików 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ł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 na 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

Sugerowany rozmiar pliku z obrazami nie przekracza 50 MB. Pliki większe niż 50 MB mogą powodować problemy z wydajnością.

Interfejs Google Photos Library API obsługuje wznawianie przesłane pliki. Przesyłanie z możliwością wznowienia umożliwia: podzielić plik multimedialny na kilka sekcji i przesłać jedną sekcję 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 do biblioteki użytkownika. Elementy multimedialne można dodawać tylko do albumy utworzone przez . Więcej informacji znajdziesz w sekcji Autoryzacja

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 do poprzednia prośba została zrealizowana przed kolejnym wywołaniem tego samego żądania użytkownika.

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ę tych 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 albumu.

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

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

Jeśli element multimedialny to film, musi zostać najpierw przetworzony. Plik mediaItem zawiera plik status w mediaMetadata, który opisuje stan przetwarzania pliku wideo. Nowo przesłany plik zwraca stan PROCESSING najwcześniej, zanim będzie READY do użytku. Szczegółowe informacje znajdziesz w artykule Dostęp do multimediów .

Jeśli podczas rozmowy napotkasz błąd, postępuj zgodnie z instrukcjami i ponownie prześlij prośbę. Ty warto śledzić operacje dodawania, dzięki czemu obraz będzie można wstawiać podczas następnej prośby o dostęp do albumu we właściwym miejscu. Więcej Więcej informacji można znaleźć w artykule Tworzenie .

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ą efektywność przesyłania:

  • Postępuj zgodnie z instrukcjami ponownych prób i poprawą obsługi błędów a także metody, weź pod uwagę następujące kwestie:
    • 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. Ten jest ważne przy przesyłaniu z urządzeń mobilnych klienta oraz podczas przesyłania dużych plików.

Pamiętaj też o tych wskazówkach dotyczących poszczególnych etapów procesu przesyłania: przesyłania bajtów, a potem tworzenia 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 X-Goog-Upload-Content-Type nagłówek dla każdego przesyłania.

Tworzenie elementów multimedialnych

  • Nie wykonuj połączeń równolegle do batchCreate przez 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 nadawać priorytety przesyłanym plikom na podstawie liczby pozostałych przesyłanych plików na użytkownika, ogólnego postępu użytkownika 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ównocześnie wiele bajtów od wielu użytkowników, ale w kroku 2 możesz wykonać tylko jedno połączenie na jednego 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 operacje przesyłania i tworzenia multimediów zostaną zakończone.