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ğ kesintisinden veya başka bir iletim hatasından sonra yükleme işlemine devam etmenize olanak tanıyarak ağ arızaları durumunda zaman ve bant genişliğinden tasarruf etmenizi sağlar.

Devam ettirilebilir yüklemeleri kullanmak aşağıdaki durumlarda özellikle yararlıdır:

Büyük dosyaları aktarıyorsunuz.
Ağ kesintisi yaşanabilir.
Yüklemelerin bant genişliği düşük veya internet bağlantısı kararlı olmayan bir cihaz (ör. mobil cihaz) varsa.

Bu kılavuzda, bir uygulamanın devam ettirilebilir yükleme işlemi kullanarak video yüklemek için yaptığı HTTP istekleri dizisi açıklanmaktadır. Bu kılavuz, temel olarak Google API istemci kitaplıkları'nı kullanamayan ve bazıları devam ettirilebilir yüklemeler için yerel destek kullanamayan geliştiricilere yöneliktir. Aslında, YouTube Data API - Video Yükleme kılavuzunda, devam ettirilebilir bir yükleme işlemiyle video yüklemek üzere Python için Google API'leri İstemci Kitaplığı'nın nasıl kullanılacağı açıklanmaktadır.

Not: HTTPS günlük kaydı etkin olan 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'da HTTP izlemeyi etkinleştirmek için 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ında yer almasını 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 başlıklarını ayarlayın:

Authorization – İsteğin yetkilendirme jetonu.
Content-Length – İsteğin gövde bölümünde sağlanan bayt sayısı. Parçalı aktarım kodlamasını kullanıyorsanız bu üstbilgiyi sağlamanız gerekmediğini unutmayın.
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 MIME türüne sahip dosyaları application/octet-stream yükleyebilirsiniz.

Aşağıdaki örnekte bir video yüklemenin devam ettirilebilir oturumu nasıl başlatılacağı gösterilmektedir. İstek, video kaynağının snippet ve status bölümlerinde özellikleri ayarlar (ve alır). Ayrıca, kaynağın contentdetails bölümünde özellikleri 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ç, bu değerlerin tümünü içeren 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ıt, devam ettirilebilir oturumun URI'sını belirten Location HTTP üst bilgisi içerir. Bu, video dosyanızı yüklemek için kullanacağınız URI'dır.

Aşağıdaki örnekte 1. adımda isteğe yönelik ö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

Oturum URI'sini API yanıtından çıkardıktan sonra, gerçek video dosyası içeriğini bu konuma yüklemeniz gerekir. İsteğin gövdesi, yüklediğiniz videonun ikili dosya 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 boyutudur. 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

İsteğiniz aşağıdaki senaryolardan birine yol açar:

Yükleme işleminiz başarıyla tamamlandı.

API sunucusu bir HTTP 201 (Created) yanıt koduyla yanıt veriyor. Yanıtın gövdesi, oluşturduğunuz video kaynağıdır.
Yükleme işleminiz başarısız oldu ancak devam ettirilebilir.

Yüklemeyi aşağıdaki durumlardan birinde devam ettirebilirsiniz:
- Uygulamanız ile API sunucusu arasındaki bağlantı kesildiği için isteğiniz kesintiye uğradı. Bu durumda API yanıtı almazsınız.
- API yanıtı, aşağıdaki 5xx yanıt kodlarından herhangi birini belirtir. Bu yanıt kodlarından herhangi birini aldıktan sonra, yüklemelerinizi devam ettirirken kodunuzda üstel geri yükleme stratejisi kullanılmalıdır.
  - 500 - Internal Server Error
  - 502 - Bad Gateway
  - 503 - Service Unavailable
  - 504 - Gateway Timeout
Yüklemeyi devam ettirmek için aşağıdaki yükleme durumunu kontrol etme ve yüklemeyi devam ettirme talimatlarını uygulayın. Devam ettirilebilen her oturum URI'sının sınırlı bir süresinin olduğunu ve sonunda süresinin dolacağını unutmayın. Bu nedenle, oturum URI'sini alır almaz devam ettirilebilir bir yükleme yapmanızı ve kesinti gerçekleştikten kısa bir süre sonra kesintiye uğrayan bir yüklemeyi devam ettirmenizi öneririz.
Yüklemeniz kalıcı olarak başarısız oldu.

Başarısız bir yükleme olduğunda yanıt, hatanın nedenini açıklayan bir hata yanıtı içerir. Kalıcı olarak başarısız olan bir yükleme için API yanıtında 4xx yanıt kodu veya yukarıda listelenenlerin dışında bir 5xx yanıt kodu bulunur.

Süresi dolmuş bir oturum URI'sı ile istek gönderirseniz sunucu, bir 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: Bir yüklemenin durumunu kontrol etme

Kesintili devam ettirilebilir yüklemenin durumunu kontrol etmek için 2. adımda aldığınız ve 3. adımda 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 tamamlanıp tamamlanmadığına bakılmaksızın, başarılı veya başarısız olmasına bakılmaksızın API, yükleme tamamlandığında gönderilen yanıtı döndürür.

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

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

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

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

API yanıtı Retry-After başlığını da içeriyorsa yüklemeyi ne zaman devam ettirmeniz gerektiğini belirlemek için ilgili başlığın değerini kullanın.

4.3. Adım: Yükleme işlemine devam edin

Yükleme işlemine devam etmek 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üklenmeyen kısmıyla ilgili ikili kod olarak 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 geri 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ıdır. Başlık değeri üç değerden oluşur:
- FIRST_BYTE – Yükleme işlemine devam ettiğiniz bayt numarasının 0 tabanlı sayısal dizini. Bu değer, önceki adımda alınan Range başlığındaki ikinci sayıdan daha yüksek. Önceki örnekte, Range üst bilgi değeri 0-999999 olduğu için sonraki bir devam eden yüklemede ilk bayt 1000000 olur.
- LAST_BYTE – Yüklediğiniz ikili dosyanın son baytının 0 tabanlı sayısal dizini. Genellikle bu dosyadaki son bayttır. Bu nedenle, örneğin dosya boyutu 3000000 baytsa dosyadaki son bayt 2999999 sayısı olur.
- TOTAL_CONTENT_LENGTH – Video dosyasının bayt cinsinden toplam boyutudur. Bu değer, orijinal yükleme isteğinde belirtilen Content-Length başlığıyla aynıdır.
Not: İkili dosyanın sürekli bir blokunu yükleyemezsiniz. Sürekli olmayan bir blok yüklemeye çalışırsanız kalan ikili program içeriklerinin hiçbiri yüklenmez.

Bu nedenle, devam ettirilen bir yüklemede yüklenen ilk bayt, YouTube'a başarıyla yüklenmiş olan son bayttan sonraki sonraki bayt olmalıdır. (4.2. adımda Range başlığının konusuyla ilgili tartışmalara göz atın.

Bu nedenle, Range başlığındaki son baytı 999999 ise isteğin devam edeceği ilk bayt 1.000.000 bayt olmalıdır. (Her ikisi de 0 tabanlı bir dizin kullanır.) 999999 ya da daha düşük (baytlar çakışıyor) veya 1000.001 bayt (veya atlanan bayt) bayttan yüklemeyi devam ettirmeye çalışırsanız ikili programdaki içeriklerin hiçbiri yüklenmez.

Parçalar halinde dosya yükleme

Uygulamanız, bir ağ kesintisi durumunda dosyanın tamamını yüklemeye çalışmak ve yüklemeyi devam ettirmek yerine dosyaları parçalara bölebilir ve parçaları sırayla yükleyebilir. Nadiren gereklidir ve performans üzerinde etki yaratabilecek ek istekler gerektirdiğinden önerilmez. Bununla birlikte, çok kararsız bir ağda ilerleme durumu göstergesi göstermeye çalışıyorsanız bu faydalı olabilir.

Bir dosyayı parçalara 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 dosyayı yüklemeye (yukarıdaki 3. adımda) ve yüklemeyi devam ettirmeye (yukarıdaki 4.3. adımda) yapılan istekler, bir dosya parçalara yüklenirken hem Content-Length hem de 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 katı olmalıdır. (Bu kısıtlama, tüm dosya boyutu 256 KB'ın katı olamayacağı için son parça için geçerli değildir.) Daha büyük parçaların daha verimli olduğunu unutmayın.
- Parça boyutu, son parçanın boyutunu belirten son istek haricinde, yükleme dizisindeki her istek için aynı olmalıdır.
Content-Range başlığı, isteğin yüklediği dosyadaki baytları belirtir. Adım 4.3'te Content-Range üstbilgisini ayarlama talimatları, bu değer ayarlanırken geçerlidir.

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

Aşağıdaki örnekte parçalara 2.000.000 baytlık bir dosya yükleyecek bir dizi istek 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}

Son istek dışındaki istekler başarılı olursa API sunucusu 308 (Resume Incomplete) yanıtıyla 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ıdır.

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

Tüm dosya yüklendiğinde sunucu bir 201 HTTP yanıt koduyla (Created) yanıt verir ve yeni oluşturulan video kaynağının istenen kısımlarını 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ü izleyin. Ancak dosyanın geri kalanını yüklemeyi denemek yerine, yüklemeyi devam ettirdiğiniz noktada parçaları yüklemeye devam edebilirsiniz. Dosya yüklemesinin devam edeceği yeri belirlemek için yükleme durumunu kontrol edin. Sunucunun önceki istekte gönderilen baytların tümünü aldığını (veya hiçbirini almadığını) varsaymayın.

Not: Yüklenen parçalar arasında etkin bir yüklemenin durumunu da isteyebilirsiniz. (Durumunu alabilmeniz için yüklemenin kesintiye uğraması gerekmez.)