Bu sayfa, Cloud Translation API ile çevrilmiştir.

Devam Ettirilebilir Yüklemeler

Google API'leri için devam ettirilebilir yükleme protokolünü kullanarak videoları daha güvenilir bir şekilde yükleyebilirsiniz. Bu protokol, ağ kesintisi veya başka bir aktarım hatası sonrasında yükleme işlemini devam ettirmenize olanak tanır. Böylece ağ hataları durumunda zaman ve bant genişliği tasarrufu sağlar.

Devam ettirilebilir yükleme özelliği özellikle aşağıdaki durumlarda yararlıdır:

Büyük dosyalar aktarıyorsunuz.
Ağ kesintisi olasılığı yüksektir.
Yüklemeler, bant genişliği düşük veya internet bağlantısı kararsız olan bir cihazdan (ör. mobil cihaz) geliyor.

Bu kılavuzda, bir uygulamanın videoları yeniden başlatılabilir bir yükleme işlemi kullanarak yüklemek için gönderdiği HTTP isteklerinin sırası açıklanmaktadır. Bu kılavuz, bazılarında devam ettirilebilir yüklemeler için yerel destek sunan Google API istemci kitaplıklarını kullanamayan geliştiriciler için hazırlanmıştır. YouTube Data API - Video Yükleme kılavuzunda, devam ettirilebilir bir yükleme işlemi kullanarak video yüklemek için Python için Google API'leri istemci kitaplığının nasıl kullanılacağı açıklanmaktadır.

Not: HTTPS günlük kaydının etkin olduğu Google API istemci kitaplıklarından birini kullanarak, devam ettirilebilir yükleme veya başka bir API işlemi için yapılan istek dizisini de görebilirsiniz. Örneğin, Python için HTTP izlemeyi etkinleştirmek üzere httplib2 kitaplığını kullanın:

httplib2.debuglevel = 4

1. adım: Devam ettirilebilir bir oturum başlatın

Devam ettirilebilir bir video yükleme işlemi başlatmak için aşağıdaki URL'ye bir POST isteği gönderin. URL'de part parametre değerini isteğiniz için uygun değere ayarlayın. Parametre değerinin, ayarladığınız özellikleri içeren bölümleri ve API yanıtının içermesini istediğiniz bölümleri tanımladığını unutmayın. İstek URL'sindeki parametre değerleri URL olarak kodlanmış olmalıdır.

https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=PARTS

İsteğin gövdesini bir video kaynağı olarak ayarlayın. Ayrıca aşağıdaki HTTP istek üstbilgilerini de ayarlayın:

Authorization: İsteğin yetkilendirme jetonu.
Content-Length: İsteğin gövdesinde sağlanan bayt sayısı. Blok aktarım kodlaması kullanıyorsanız bu üstbilgiyi sağlamanız gerekmez.
Content-Type: Değeri application/json; charset=UTF-8 olarak ayarlayın.
X-Upload-Content-Length: Sonraki isteklerde yüklenecek bayt sayısı. Bu değeri, yüklediğiniz dosyanın boyutuna ayarlayın.
x-upload-content-type: Yüklediğiniz dosyanın MIME türü. Herhangi bir video MIME türüne (video/*) veya application/octet-stream MIME türüne sahip dosyalar yükleyebilirsiniz.

Aşağıdaki örnekte, video yüklemek için devam ettirilebilir bir oturumun nasıl başlatılacağı gösterilmektedir. İstek, video kaynağının snippet ve status bölümlerindeki özellikleri ayarlar (ve alır) ve ayrıca kaynağın contentdetails bölümündeki özellikleri de alır.

post /upload/youtube/v3/videos?uploadType=resumable&part=parts http/1.1
host: www.googleapis.com
authorization: bearer auth_token
content-length: content_length
content-type: application/json; charset=utf-8
x-upload-content-length: x_upload_content_length
X-Upload-Content-Type: X_UPLOAD_CONTENT_TYPE

video resource

Aşağıdaki örnekte, kimlik doğrulama jetonu hariç tüm bu değerlerin doldurulduğu bir POST isteği gösterilmektedir. Örnekteki categoryId değeri bir video kategorisine karşılık gelir. Desteklenen kategorilerin listesi, API'nin videoCategories.list yöntemi kullanılarak alınabilir.

POST /upload/youtube/v3/videos?uploadType=resumable&part=snippet,status,contentDetails HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer AUTH_TOKEN
Content-Length: 278
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Length: 3000000
X-Upload-Content-Type: video/*

{
  "snippet": {
    "title": "My video title",
    "description": "This is a description of my video",
    "tags": ["cool", "video", "more keywords"],
    "categoryId": 22
  },
  "status": {
    "privacyStatus": "public",
    "embeddable": True,
    "license": "youtube"
  }
}

2. Adım: Devam ettirilebilir oturum URI'sini kaydedin

İsteğiniz başarılı olursa API sunucusu 200 (OK) HTTP durum koduyla yanıt verir ve yanıtta, devam ettirilebilir oturumun URI'sini belirten bir Location HTTP üst bilgisi bulunur. Bu, video dosyanızı yüklemek için kullanacağınız URI'dir.

Aşağıdaki örnekte, 1. adımdaki istek için örnek bir API yanıtı gösterilmektedir:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&upload_id=xa298sd_f&part=snippet,status,contentDetails
Content-Length: 0

3. adım: Video dosyasını yükleyin

API yanıtından oturum URI'sini çıkardıktan sonra, gerçek video dosyası içeriğini bu konuma yüklemeniz gerekir. İsteğin gövdesi, yüklediğiniz videonun ikili program dosyası içeriğidir. Aşağıdaki örnekte isteğin biçimi gösterilmektedir.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: CONTENT_LENGTH
Content-Type: CONTENT_TYPE

BINARY_FILE_DATA

İstek aşağıdaki HTTP istek başlıklarını ayarlar:

Authorization: İsteğin yetkilendirme jetonu.
Content-Length: Yüklediğiniz dosyanın boyutu. Bu değer, 1. adımdaki X-Upload-Content-Length HTTP isteği başlığının değeriyle aynı olmalıdır.
Content-Type: Yüklediğiniz dosyanın MIME türü. Bu değer, 1. adımdaki X-Upload-Content-Type HTTP isteği başlığının değeriyle aynı olmalıdır.

4. Adım: Yükleme işlemini tamamlayın

Talebiniz aşağıdaki senaryolardan birine yol açar:

Yükleme işleminiz başarılı oldu.

API sunucusu, HTTP 201 (Created) yanıt koduyla yanıt verir. Yanıtın gövdesi, oluşturduğunuz video kaynağıdır.
Yükleme işleminiz tamamlanamadı ancak devam ettirilebilir.

Aşağıdaki durumlarda yüklemeyi devam ettirebilirsiniz:
- Uygulamanız ile API sunucusu arasındaki bağlantı kesildiğinden isteğiniz kesintiye uğrar. Bu durumda API yanıtı almazsınız.
- API yanıtı, aşağıdaki 5xx yanıt kodlarından birini belirtir. Kodunuz, bu yanıt kodlarından herhangi birini aldıktan sonra yüklemeleri devam ettirirken eksponansiyel geri yükleme stratejisi kullanmalıdır.
  - 500 - Internal Server Error
  - 502 - Bad Gateway
  - 503 - Service Unavailable
  - 504 - Gateway Timeout
Bir yüklemeyi devam ettirmek için aşağıdaki yüklemenin durumunu kontrol etme ve yüklemeyi devam ettirme talimatlarını uygulayın. Devam ettirilebilir her oturum URI'sinin sonlu bir ömrü olduğunu ve zaman içinde süresinin dolacağını unutmayın. Bu nedenle, oturum URI'sini alır almaz devam ettirilebilir bir yükleme başlatmanızı ve kesinti oluştuktan kısa bir süre sonra kesintiye uğrayan yüklemeyi devam ettirmenizi öneririz.
Yüklemeniz kalıcı olarak başarısız oldu.

Başarısız bir yükleme için yanıtta, başarısızlığın nedenini açıklamaya yardımcı olan bir hata yanıtı bulunur. Kalıcı olarak başarısız olan yüklemeler için API yanıtında, yukarıda listelenenler dışında bir 4xx yanıt kodu veya 5xx yanıt kodu bulunur.

Süresi dolmuş bir oturum URI'si içeren bir istek gönderirseniz sunucu 404 HTTP yanıt kodu (Not Found) döndürür. Bu durumda, yeni bir devam ettirilebilir yükleme başlatmanız, yeni bir oturum URI'si almanız ve yeni URI'yi kullanarak yüklemeyi baştan başlatmanız gerekir.

4.1. adım: Yüklemenin durumunu kontrol edin

Kesintiye uğramış ve devam ettirilebilir bir yüklemenin durumunu kontrol etmek için 2. adımda aldığınız ve 3. adımda da kullandığınız yükleme URL'sine boş bir PUT isteği gönderin. İsteğinizde Content-Range başlık değerini bytes */CONTENT_LENGTH olarak ayarlayın. Burada CONTENT_LENGTH, yüklediğiniz dosyanın boyutudur.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 0
Content-Range: bytes */CONTENT_LENGTH

4.2. adım: API yanıtını işleme

Yükleme işlemi tamamlandıysa (başarılı veya başarısız olmasına bakılmaksızın) API, yükleme işlemi ilk kez tamamlandığında gönderdiği yanıtı döndürür.

Ancak yükleme kesintiye uğradıysa veya hâlâ devam ediyorsa API yanıtında HTTP 308 (Resume Incomplete) yanıt kodu bulunur. Yanıtta, Range üstbilgisi, dosyanın kaç baytının başarıyla yüklendiğini belirtir.

Üstbilgi değeri 0 ile dizine eklenir. Bu nedenle, 0-999999 olan bir başlık değeri, dosyanın ilk 1,000,000 baytının yüklendiğini gösterir.
Henüz hiçbir şey yüklenmediyse API yanıtı Range üstbilgisini içermez.

Aşağıdaki örnek yanıtta, devam ettirilebilir yükleme için API yanıtının biçimi gösterilmektedir:

308 Resume Incomplete
Content-Length: 0
Range: bytes=0-999999

API yanıtı Retry-After üstbilgisini de içeriyorsa yüklemeyi ne zaman devam ettirmeye çalışacağınızı belirlemek için bu üstbilginin değerini kullanın.

4.3. adım: Yüklemeyi devam ettirin

Yüklemeyi devam ettirmek için 2. adımda yakalanan yükleme URL'sine başka bir PUT isteği gönderin. İstek gövdesini, video dosyasının henüz yüklenmemiş kısmının ikili koduna ayarlayın.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: REMAINING_CONTENT_LENGTH
Content-Range: bytes FIRST_BYTE-LAST_BYTE/TOTAL_CONTENT_LENGTH

PARTIAL_BINARY_FILE_DATA

Aşağıdaki HTTP istek başlıklarını ayarlamanız gerekir:

Authorization: İsteğin yetkilendirme jetonu.
Content-Length: Henüz yüklenmemiş içeriğin bayt cinsinden boyutu. Bir dosyanın kalanını yüklüyorsanız FIRST_BYTE değerini TOTAL_CONTENT_LENGTH değerinden çıkararak bu değeri hesaplayabilirsiniz. Her iki değer de Content-Range başlığında kullanılır.
Content-Range: Dosyanın yüklediğiniz kısmı. Başlık değeri üç değerden oluşur:
- FIRST_BYTE: Yüklemeyi devam ettirdiğiniz bayt sayısının 0 tabanlı sayısal dizini. Bu değer, önceki adımda alınan Range başlığındaki ikinci sayıdan bir sayı daha yüksektir. Yukarıdaki örnekte, Range başlığı 0-999999 değerine sahipti. Bu nedenle, devam eden bir sonraki yüklemenin ilk baytı 1000000 olacaktır.
- LAST_BYTE: Yüklediğiniz ikili program dosyasının son baytının 0 tabanlı sayısal dizini. Bu genellikle dosyadaki son bayttır. Örneğin, dosya boyutu 3000000 bayt ise dosyadaki son bayt 2999999 sayısı olur.
- TOTAL_CONTENT_LENGTH: Video dosyasının bayt cinsinden toplam boyutu. Bu değer, orijinal yükleme isteğinde belirtilen Content-Length başlığıyla aynıdır.
Not: İkili dosyanın kesintisiz olmayan bir bloğunu yükleyemezsiniz. Devamlı olmayan bir blok yüklemeye çalışırsanız kalan ikili içeriklerin hiçbiri yüklenmez.

Bu nedenle, devam ettirilen bir yüklemede yüklenen ilk bayt, YouTube'a başarıyla yüklenen son bayttan sonraki bayt olmalıdır. (Range başlığıyla ilgili tartışmayı 4.2. adımda bulabilirsiniz.

Bu nedenle, Range başlığındaki son bayt 999999 ise yüklemeyi devam ettirme isteğinde ilk bayt 1000000 baytı olmalıdır. (Her iki sayı da 0 tabanlı bir dizin kullanır.) Yüklemeyi 999999. bayttan veya daha düşük bir bayttan (örtüşen baytlar) ya da 1000001. bayttan veya daha yüksek bir bayttan (atlanan baytlar) devam ettirmeye çalışırsanız ikili içeriklerin hiçbiri yüklenmez.

Dosyaları parçalara ayırarak yükleme

Uygulamanız, dosyanın tamamını yüklemeye çalışmak ve ağ kesintisi durumunda yüklemeyi devam ettirmek yerine dosyayı parçalara ayırabilir ve parçaları sırayla yüklemek için bir dizi istek gönderebilir. Bu yaklaşım nadiren gereklidir ve performansla ilgili etkileri olan ek istekler gerektirdiği için aslında önerilmez. Ancak, çok kararsız bir ağda ilerleme göstergesi göstermeye çalışıyorsanız bu yöntem yararlı olabilir.

Bir dosyayı parçalara ayırarak yükleme talimatları, bu kılavuzun önceki bölümlerinde açıklanan dört adımlı süreçle neredeyse aynıdır. Ancak, bir dosyanın parçalara ayrılarak yüklenmesi durumunda, dosya yükleme işlemini başlatma (yukarıdaki 3. adım) ve yükleme işlemine devam etme (yukarıdaki 4.3. adım) isteklerinin her ikisi de Content-Length ve Content-Range başlık değerlerini farklı şekilde ayarlar.

Content-Length başlık değeri, isteğin gönderdiği parçanın boyutunu belirtir. Parça boyutlarıyla ilgili aşağıdaki kısıtlamalara dikkat edin:
- Parça boyutu 256 KB'nın katı olmalıdır. (Dosyanın tamamının boyutu 256 KB'nın katı olmayabileceğinden bu kısıtlama son parça için geçerli değildir.) Daha büyük parçaların daha verimli olduğunu unutmayın.
- Son parçanın boyutunu belirten son istek hariç olmak üzere, yükleme sırasındaki her istek için parça boyutu aynı olmalıdır.
Content-Range üstbilgisi, istek tarafından yüklenen dosyanın baytlarını belirtir. Bu değeri ayarlarken 4.3. adımda Content-Range başlığını ayarlama talimatları geçerlidir.

Örneğin, bytes 0-524287/2000000 değeri, isteğin 2.000.000 baytlık bir dosyanın ilk 524.288 baytını (256 x 2048) gönderdiğini gösterir.

Aşağıdaki örnekte, 2.000.000 baytlık bir dosyayı parçalara ayırarak yükleyecek bir istek serisinin ilkinin biçimi gösterilmektedir:

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 524888
Content-Type: video/*
Content-Range: bytes 0-524287/2000000

{bytes 0-524287}

Nihai istek dışındaki bir istek başarılı olursa API sunucusu 308 (Resume Incomplete) yanıtı ile yanıt verir. Yanıt biçimi, yukarıdaki 4.2. adım: API yanıtını işleme bölümünde açıklananla aynı olacaktır.

Sonraki parçanın nereden başlayacağını belirlemek için API yanıtının Range başlığında döndürülen üst değeri kullanın. Dosyanın tamamı yüklenene kadar sonraki dosya parçalarını yüklemek için 4.3. Adım: Yüklemeyi devam ettirin bölümünde açıklandığı gibi PUT istekleri göndermeye devam edin.

Dosyanın tamamı yüklendiğinde sunucu, 201 HTTP yanıt koduyla (Created) yanıt verir ve yeni oluşturulan video kaynağının istenen bölümlerini döndürür.

Herhangi bir istek kesintiye uğrarsa veya uygulamanız 5xx yanıt kodu alırsa yüklemeyi tamamlamak için 4. adımda açıklanan prosedürü uygulayın. Ancak, dosyanın geri kalanını yüklemeye çalışmak yerine, yüklemeyi devam ettirdiğiniz noktadan itibaren parçaları yüklemeye devam edin. Dosya yüklemenin nereden devam ettirileceğini belirlemek için yüklemenin durumunu kontrol ettiğinizden emin olun. Sunucunun önceki istekte gönderilen baytların tamamını (veya hiçbirini) aldığını varsaymayın.

Not: Yüklenen parçalar arasında etkin bir yüklemenin durumunu da isteyebilirsiniz. (Yüklemenin durumunu alabilmek için yüklemenin kesintiye uğramış olması gerekmez.)