Medyayı yükle

Medya öğelerinin yüklenmesi iki adımlı bir işlemdir:

  1. yükleme uç noktasını kullanarak medya dosyalarınızın baytlarını bir Google sunucusuna yükleyin. Bu, yüklenen baytları tanımlayan bir yükleme jetonu döndürür.
  2. Şu işlem için yükleme jetonuyla bir batchCreate çağrısı kullanın: Kullanıcının Google Fotoğraflar hesabında bir medya öğesi oluşturabilir.

Bu adımlar, tek bir medya öğesi yükleme işlemini özetler. Şu durumda: birden fazla medya öğesi yüklemek (büyük olasılıkla herhangi bir üretim uygulaması için), Daha iyi hale getirmek için yüklemelerle ilgili en iyi uygulamaları en iyi uygulamaları paylaşacağız.

Başlamadan önce

Gerekli yetkilendirme kapsamları

Bir kullanıcının kitaplığına veya albümüne medya öğeleri yüklemek için photoslibrary.appendonly veya photoslibrary kapsamı.

Medya öğeleri, photoslibrary.sharing kapsamı kullanılarak da oluşturulabilir. Alıcı: photoslibrary.sharing kapsamıyla öğeler oluşturmak için öncelikle bir albümü shareAlbum kullanarak paylaşıldı olarak işaretleyin. Ardından medya öğeleri oluşturabilirsiniz. albümdeki kullanıcıyla paylaşılan verilerdir. Doğrudan şu sayfada öğe oluşturamazsınız: kullanıcının kitaplığında veya uygulamanızın paylaşmadığı albümlerde yer alabilir.

Albümleri listelerken isWriteable özelliği, albümdeki uygulamasının belirli bir albümde medya oluşturma erişimi vardır.

Kabul edilen dosya türleri ve boyutları

Aşağıdaki tabloda listelenen dosya türlerini yükleyebilirsiniz.

Medya türü Kabul edilen dosya türleri Maksimum dosya boyutu
Fotoğraflar AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, bazı RAW dosyaları. 200 MB
Videolar 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV. 20 GB

1. Adım: Bayt yükleme

Yükleme isteklerini kullanarak Google'a bayt yükleyin. Başarılı bir yükleme isteği ham metin dizesi biçiminde bir yükleme jetonu döndürür. Bu yüklemeleri kullan batchCreate çağrısı ile medya öğeleri oluşturmak için jetonlar.

REST

Aşağıdaki alanları POST isteği başlığına ekleyin:

Başlık alanları
Content-type application/octet-stream olarak ayarlayın.
X-Goog-Upload-Content-Type Önerilir. Yüklemekte olduğunuz baytların MIME türüne ayarlayın. Yaygın MIME türleri arasında image/jpeg, image/png ve image/gif.
X-Goog-Upload-Protocol raw olarak ayarlayın.

Aşağıda bir POST isteği başlığı verilmiştir:

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

İstek gövdesine dosyanın ikili kodunu ekleyin:

media-binary-data

Bu POST isteği başarılı olursa dizesi, yanıt gövdesi olarak döndürülür. Medya oluşturmak için öğeleri için bu metin dizelerini batchCreate çağrısında kullanın.

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
}

Resimler için önerilen dosya boyutu 50 MB'tan azdır. 50 MB'tan büyük dosyalar performans sorunlarına yatkındır.

Google Photos Library API, devam ettirilebilir yüklemeler. Devam ettirilebilir Yükleme, bir medya dosyasını birden fazla bölüme ayırıp tek bir bölüm yüklemenizi sağlar. bölümüne ekleyin.

2. Adım: Medya öğesi oluşturma

Medya dosyalarınızın baytlarını yükledikten sonra bunları medya olarak oluşturabilirsiniz öğeleri Google Fotoğraflar'daki yükleme jetonlarını kullanarak. Yükleme jetonu geçerli bir gün süreyle kullanılabilir. Bir medya öğesi her zaman kullanıcının kitaplığını açar. Medya öğeleri yalnızca albümlere eklendi otomatik olarak oluşturulur. Daha fazla bilgi için Yetkilendirme kapsamları bölümüne bakın.

Yeni medya öğeleri oluşturmak için şu numarayı arayın: mediaItems.batchCreate (newMediaItems listesi belirterek) Her newMediaItem bir yükleme içerir simpleMediaItem içinde belirtilen jeton ve isteğe bağlı bir açıklama gösterilen resimdir.

Açıklama alanı 1.000 karakterle sınırlıdır ve yalnızca anlamlı metinlere dayanıyor. Örneğin, "Parka gezimiz" veya "Tatil yemeği". Dosya adı, programatik gibi meta veriler eklemeyin etiketleri veya otomatik olarak oluşturulan diğer metinleri kullanabilirsiniz.

En iyi performans için çağrı sayısını mediaItems.batchCreate olacak şekilde azaltın tek bir çağrıya birden çok medya öğesi ekleyerek bunu yapmanız gerekir. Her zaman bekleyin önceki istek tamamlanana kadar aynı kullanıcı.

Bir kullanıcının kitaplığında tek bir medya öğesi veya birden çok medya öğesi oluşturabilirsiniz açıklamaları ve ilgili yükleme jetonlarını belirterek:

REST

POST isteği başlığı şöyledir:

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

İsteğin gövdesinde bir newMediaItems listesi belirtilmelidir.

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


Medya öğelerini id adlı albüm. Daha fazla bilgi için bkz. Albüm oluşturun.

Her albüm en fazla 20.000 medya öğesi içerebilir. Medya oluşturma istekleri bir albümde bu sınırı aşacak öğeler başarısız olacak.

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
}

Ayrıca şunlar için albumId ve albumPosition belirtebilirsiniz: Medya öğelerini albümde belirli bir konuma ekleyin.

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
}

Albümlerin konumlandırılmasıyla ilgili daha ayrıntılı bilgi için bkz. Zenginleştirme ekleyin.

Öğe oluşturma yanıtı

mediaItems.batchCreate çağrısı, medya öğelerinin her biri için sonucu döndürür bir cümle ekleyebilirsiniz. newMediaItemResults listesi durumu ve , isteğin uploadToken değerini içerir. Sıfır olmayan bir durum kodu hatası.

REST

Tüm medya öğeleri başarıyla oluşturulduysa istek, 200 OK HTTP durumu. Medya öğeleri oluşturulamıyorsa istek,207 MULTI-STATUS ne kadar iyi olduğunu belirlemenize yardımcı olur.

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

Bir öğe başarıyla eklenirse, şunu içeren bir mediaItem döndürülür: mediaItemId, productUrl ve mediaMetadata. Daha fazla bilgi için bkz. Medya öğelerine erişim.

Medya öğesi bir video ise öncelikle bu öğenin işlenmesi gerekir. mediaItem mediaMetadata içinde işlemeyi açıklayan bir status içeriyor durumunu bilebilirsiniz. Yeni yüklenen bir dosya PROCESSING durumunu döndürüyor önce, kullanılacak READY. Ayrıntılar için bkz. Medya öğelerine erişim.

Bu görüşme sırasında hatayla karşılaşırsanız şu adımları uygulayın: En iyi uygulamalar'ı tıklayın ve isteğinizi tekrar deneyin. Resmin eklenebilmesi için başarılı eklemeleri takip etmek isteyebilirsiniz istek sırasında doğru konuma yerleştirebilirsiniz. Daha fazla bkz. Albüm oluşturun.

Sonuçlar her zaman, yükleme jetonlarının çalıştırıldığı sırayla döndürülür. gönderildi.

Yüklemeler için en iyi uygulamalar

Aşağıdaki en iyi uygulamalar ve kaynaklar, genel verimliliğinizi artırmanıza yardımcı olur şu yüklemelerle:

  • Desteklenen istemci kitaplıklarımızdan birini kullanın.
  • Yeniden deneme ve hata giderme en iyi uygulamalarını izleyin, şu noktaları göz önünde bulundurun:
    • Kotanız aşıldığında 429 hataları oluşabilir ya da çok hızlı şekilde çok fazla arama yapmanız durumunda arama hızınız sınırlandırılmış olabilir. Şunlardan emin olun: öncekine kadar aynı kullanıcı için batchCreate yöntemini çağırmazsanız isteği tamamlandı.
    • 429 hata, yeniden denemeden önce en az 30s gecikme yapılmasını gerektirir. Bir eksponansiyel geri yükleme stratejisini belirlemelisiniz.
    • Sunucu bir hatayla karşılaştığında 500 hataları oluşur. Yükleme yaparken bunun nedeni büyük olasılıkla birden fazla yazma çağrısı (ör. batchCreate) aynı anda değiştirebilirsiniz. Ayrıntıları kontrol edin istekte bulunmanızı ve paralel olarak batchCreate çağrılarını yapmayın.
  • Şu işlemler için devam ettirilebilir yükleme akışını kullanın: yüklemelerinizi ağ kesintileri durumunda daha sağlam hale getirerek bant genişliği kullanımını artırır. İstemci mobil cihazlarından yükleme yaparken bu önemlidir. dikkat edin.

Ayrıca, yükleme sürecinin her adımı için aşağıdaki ipuçlarını da göz önünde bulundurun: bayt yükleme ve ardından medya öğeleri oluşturma.

Bayt yükleme

Medya öğeleri oluşturuluyor

  • Tek bir kullanıcı için batchCreate ile paralel olarak arama yapmayın.

    • Her kullanıcı için batchCreate çağrısını art arda yapın ( seri) ile ilgili daha fazla bilgi edinin.
    • Birden fazla kullanıcı için her kullanıcı için her zaman batchCreate araması yapın görürsünüz. Paralel olarak yalnızca farklı kullanıcılar için arama yapın.
  • Mümkün olduğunca çok NewMediaItems ekleyin yaptığınız toplam arama sayısını en aza indirmek için batchCreate numaralı telefona yönelik her aramada hazırlıyoruz. En fazla 50 öğe ekleyebilirsiniz.

  • Anlamlı bir açıklama metni belirleyin bir şablondan oluşur. Şu veriler gibi meta verileri eklemeyin: programlı etiketler veya otomatik olarak oluşturulan diğer metinler için açıklama alanına ekleyebilirsiniz.

Örnek adım adım açıklamalı kılavuz

Bu örnekte, birden çok öğe için medya öğelerini yükleme işlemini adım adım göstermek üzere sözde kod kullanılmaktadır. yardımcı olur. Amaç, yükleme sürecinin her iki adımını da ana hatlarıyla belirtmektir (ham dosya yükleme bayt ve medya öğeleri oluşturma) içeriyorsa ve verimli ve dayanıklı bir yükleme oluşturmaya yönelik en iyi uygulamaları ayrıntılandırma inceleyebilirsiniz.

1. Adım: İşlenmemiş baytları yükleyin

Öncelikle tüm medya öğelerinizden medya öğeleriniz için ham baytları yüklemek üzere bir sıra oluşturun. yardımcı olur. Döndürülen her uploadToken değerini kullanıcı başına takip edin. Şu önemli noktaları unutmayın:

  • Eş zamanlı yükleme ileti dizilerinin sayısı işletim sisteminize bağlıdır bahsedeceğim.
  • Yükleme sırasını gerektiği şekilde yeniden sıralamayı düşünebilirsiniz. Örneğin herkesin Kullanıcı başına kalan yükleme sayısına göre yüklemeleri önceliklendirmek veya diğer gerekliliklere göre değişebilir.

Sözde kod

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

2. Adım: Medya öğeleri oluşturun

1. adımda, paralel olarak birden çok kullanıcıdan birden fazla bayt yükleyebilirsiniz. Adım 2 adımında, her bir kullanıcı için tek seferde yalnızca bir arama yapabilirsiniz.

Sözde kod

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

Tüm yükleme ve medya oluşturma çağrıları tamamlanana kadar bu işleme devam edin.