Ekleri Yükleme

Gmail API, taslak oluştururken veya güncellerken ya da ileti eklerken veya gönderirken dosya verilerini yüklemenize olanak tanır.

Yükleme seçenekleri

Gmail API, belirli ikili veri veya medya türlerini yüklemenize olanak tanır. Yükleyebileceğiniz verilerin belirli özellikleri, medya yüklemelerini destekleyen tüm yöntemlerin referans sayfasında belirtilir:

  • Maksimum yükleme dosyası boyutu: Bu yöntemle depolayabileceğiniz maksimum veri miktarı.
  • Kabul edilen medya MIME türleri: Bu yöntemle depolayabileceğiniz ikili veri türleri.

Yükleme isteklerini aşağıdaki yöntemlerden herhangi biriyle yapabilirsiniz. uploadType istek parametresiyle kullandığınız yöntemi belirtin.

  • Kolay yükleme: uploadType=media. Daha küçük dosyaların (ör. 5 MB veya daha az) hızlı aktarılması için.
  • Çok parçalı yükleme: uploadType=multipart. Daha küçük dosyaların ve meta verilerin hızlı aktarımı için kullanılır. Dosyayı, kendisini açıklayan meta verilerle birlikte tek bir istekte aktarır.
  • Devam ettirilebilir yükleme: uploadType=resumable. Özellikle daha büyük dosyalar için güvenilir aktarım sağlar. Bu yöntemde, isteğe bağlı olarak meta veriler içerebilen bir oturum başlatma isteği kullanırsınız. Bu strateji, yükleme başına bir ek HTTP isteği maliyetiyle daha küçük dosyalar için de çalıştığından çoğu uygulama için iyi bir seçenektir.

Medya yüklerken özel bir URI kullanırsınız. Aslında, medya yüklemelerini destekleyen yöntemlerin iki URI uç noktası vardır:

  • Medya için /upload URI'si. Yükleme uç noktasının biçimi, "/upload" önekine sahip standart kaynak URI'sidir. Medya verilerinin kendisini aktarırken bu URI'yi kullanın.

    Örnek: POST /upload/gmail/v1/users/userId/messages/send

  • Meta veriler için standart kaynak URI'si. Kaynak herhangi bir veri alanı içeriyorsa bu alanlar, yüklenen dosyayı açıklayan meta verileri depolamak için kullanılır. Meta veri değerleri oluştururken veya güncellerken bu URI'yi kullanabilirsiniz.

    Örnek: POST /gmail/v1/users/userId/messages/send

Basit yükleme

Dosya yüklemenin en basit yöntemi, basit bir yükleme isteğinde bulunmaktır. Bu seçenek aşağıdaki durumlarda iyi bir seçimdir:

  • Bağlantı başarısız olursa dosya, tamamı yeniden yüklenebilecek kadar küçüktür.
  • Gönderilecek meta veri yok. Bu durum, bu kaynağın meta verilerini ayrı bir istekte göndermeyi planlıyorsanız veya meta veri desteklenmiyorsa ya da kullanılamıyorsa geçerli olabilir.

Basit yüklemeyi kullanmak için yöntemin /upload URI'sine POST veya PUT isteği gönderin ve uploadType=media sorgu parametresini ekleyin. Örneğin:

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=media

Basit bir yükleme isteğinde bulunurken kullanılacak HTTP başlıkları şunlardır:

  • Content-Type. API referansında belirtilen, yöntemin kabul ettiği yükleme medya veri türlerinden birine ayarlayın.
  • Content-Length. Yüklediğiniz bayt sayısına ayarlayın. Parçalı aktarım kodlaması kullanıyorsanız gerekli değildir.

Örnek: Basit yükleme

Aşağıdaki örnekte, Gmail API için basit bir yükleme isteğinin kullanımı gösterilmektedir.

POST /upload/gmail/v1/users/userId/messages/send?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: message/rfc822
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

Email Message data

İstek başarılı olursa sunucu, HTTP 200 OK durum kodunu ve tüm meta verileri döndürür:

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

Çok parçalı yükleme

Yüklemek istediğiniz verilerle birlikte göndermek istediğiniz meta veriler varsa tek bir multipart/related isteği oluşturabilirsiniz. Gönderdiğiniz veriler, bağlantı başarısız olursa tekrar yükleyebileceğiniz kadar küçükse bu iyi bir seçenektir.

Çok parçalı yüklemeyi kullanmak için yöntemin /upload URI'sine POST veya PUT isteği gönderin ve sorgu parametresini ekleyin. Örneğin:uploadType=multipart

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=multipart

Çok parçalı yükleme isteğinde bulunurken kullanılacak üst düzey HTTP başlıkları şunlardır:

  • Content-Type. multipart/related olarak ayarlayın ve isteğin bölümlerini tanımlamak için kullandığınız sınır dizesini ekleyin.
  • Content-Length. İstek gövdesindeki toplam bayt sayısına ayarlanır. İsteğin medya kısmı, bu yöntem için belirtilen maksimum dosya boyutundan küçük olmalıdır.

İsteğin gövdesi, multipart/related içerik türü [RFC2387] olarak biçimlendirilir ve tam olarak iki bölüm içerir. Bölümler, bir sınır dizesiyle tanımlanır ve son sınır dizesini iki kısa çizgi takip eder.

Çok parçalı isteğin her bölümü için ek bir Content-Type başlığı gerekir:

  1. Meta veri bölümü: Önce gelmeli ve Content-Type kabul edilen meta veri biçimlerinden biriyle eşleşmelidir.
  2. Medya bölümü: İkinci sırada olmalı ve Content-Type, yöntemin kabul ettiği medya MIME türlerinden biriyle eşleşmelidir.

Her yöntemin kabul edilen medya MIME türleri listesi ve yüklenen dosyaların boyut sınırları için API referansına bakın.

Not: Yalnızca meta veri bölümünü oluşturmak veya güncellemek için (ilişkili verileri yüklemeden) standart kaynak uç noktasına POST veya PUT isteği göndermeniz yeterlidir: https://www.googleapis.com/gmail/v1/users/userId/messages/send

Örnek: Çok parçalı yükleme

Aşağıdaki örnekte, Gmail API için çok parçalı yükleme isteği gösterilmektedir.

POST /upload/gmail/v1/users/userId/messages/send?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

--foo_bar_baz
Content-Type: message/rfc822

Email Message data
--foo_bar_baz--

İstek başarılı olursa sunucu, HTTP 200 OK durum kodunu ve tüm meta verileri döndürür:

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

Devam ettirilebilir yükleme

Veri dosyalarını daha güvenilir bir şekilde yüklemek için devam ettirilebilir yükleme protokolünü kullanabilirsiniz. Bu protokol, iletişim hatası veri akışını kesintiye uğrattıktan sonra yükleme işlemine devam etmenize olanak tanır. Özellikle büyük dosyalar aktarıyorsanız ve ağ kesintisi veya başka bir iletim hatası olasılığı yüksekse (ör. mobil istemci uygulamasından yükleme yaparken) bu özellikten yararlanabilirsiniz. Ayrıca, büyük dosya yüklemelerini baştan başlatmanız gerekmediğinden ağ hataları durumunda bant genişliği kullanımınızı da azaltabilir.

Devam ettirilebilir yüklemeyi kullanma adımları şunlardır:

  1. Devam ettirilebilir bir oturum başlatın. Varsa meta verileri içeren yükleme URI'sine ilk isteği gönderin.
  2. Devam ettirilebilir oturum URI'sini kaydedin. İlk isteğin yanıtında döndürülen oturum URI'sini kaydedin. Bu URI'yi, bu oturumdaki kalan istekler için kullanacaksınız.
  3. Dosyayı yükleyin. Medya dosyasını devam ettirilebilir oturum URI'sine gönderin.

Ayrıca, devam ettirilebilir yüklemeyi kullanan uygulamalarda kesintiye uğrayan yüklemeyi devam ettirecek kod bulunmalıdır. Yükleme işlemi kesintiye uğrarsa ne kadar verinin başarıyla alındığını öğrenin ve yüklemeye bu noktadan itibaren devam edin.

Not: Yükleme URI'sinin geçerlilik süresi bir haftadır.

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

Devam ettirilebilir bir yükleme başlatmak için yöntemin /upload URI'sine POST veya PUT isteği gönderin ve sorgu parametresini ekleyin. Örneğin:uploadType=resumable

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable

Bu başlatma isteğinde gövde ya boştur ya da yalnızca meta verileri içerir. Yüklemek istediğiniz dosyanın gerçek içeriğini sonraki isteklerde aktarırsınız.

İlk istekte aşağıdaki HTTP üstbilgilerini kullanın:

  • X-Upload-Content-Type. Sonraki isteklerde aktarılacak yükleme verilerinin medya MIME türüne ayarlanır.
  • X-Upload-Content-Length. Sonraki isteklerde aktarılacak yükleme verilerinin bayt sayısına ayarlanır.  Bu istek sırasında uzunluk bilinmiyorsa bu üstbilgiyi atlayabilirsiniz.
  • Meta veri sağlıyorsanız: Content-Type. Meta verilerin veri türüne göre ayarlayın.
  • Content-Length. Bu ilk isteğin gövdesinde sağlanan bayt sayısına ayarlanır. Parçalı aktarım kodlaması kullanıyorsanız gerekli değildir.

Her yöntemin kabul edilen medya MIME türleri listesi ve yüklenen dosyaların boyut sınırları için API referansına bakın.

Örnek: Devam ettirilebilir oturum başlatma isteği

Aşağıdaki örnekte, Gmail API için devam ettirilebilir bir oturumun nasıl başlatılacağı gösterilmektedir.

POST /upload/gmail/v1/users/userId/messages/send?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: message/rfc822
X-Upload-Content-Length: 2000000

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

Not: Meta veriler olmadan ilk kez devam ettirilebilir güncelleme isteğinde bulunmak için isteğin gövdesini boş bırakın ve Content-Length üstbilgisini 0 olarak ayarlayın.

Yanıtın nasıl ele alınacağı sonraki bölümde açıklanmıştır.

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

Oturum başlatma isteği başarılı olursa API sunucusu 200 OK HTTP durum koduyla yanıt verir. Ayrıca, devam ettirilebilir oturum URI'nizi belirten bir Location üstbilgisi sağlar. Aşağıdaki örnekte gösterilen Location üstbilgisi, bu oturum için kullanılacak benzersiz yükleme kimliğini veren bir upload_id sorgu parametresi bölümü içerir.

Örnek: Devam ettirilebilir oturum başlatma yanıtı

1. adımda verilen isteğe ilişkin yanıt:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

Yukarıdaki örnek yanıtta gösterildiği gibi Location başlığının değeri, gerçek dosya yükleme işlemini yapmak veya yükleme durumunu sorgulamak için HTTP uç noktası olarak kullanacağınız oturum URI'sidir.

Oturum URI'sini kopyalayıp kaydedin. Böylece, sonraki isteklerde kullanabilirsiniz.

3. adım: Dosyayı yükleyin

Dosyayı yüklemek için önceki adımda aldığınız yükleme URI'sine bir PUT isteği gönderin. Yükleme isteğinin biçimi şöyledir:

PUT session_uri

Devam ettirilebilir dosya yükleme istekleri gönderirken kullanılacak HTTP başlıkları Content-Length içerir. Bunu, bu isteğe yüklediğiniz bayt sayısına (genellikle yükleme dosyasının boyutu) ayarlayın.

Örnek: Devam ettirilebilir dosya yükleme isteği

Mevcut örnek için 2.000.000 baytlık e-posta mesajı dosyasının tamamını yüklemek üzere devam ettirilebilir bir istek aşağıda verilmiştir.

PUT https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: message/rfc822

bytes 0-1999999

İstek başarılı olursa sunucu, bu kaynakla ilişkili tüm meta verilerle birlikte HTTP 201 Created ile yanıt verir. Devam ettirilebilir oturumun ilk isteği PUT ise mevcut bir kaynağı güncellemek için başarı yanıtı, bu kaynakla ilişkili tüm meta verilerle birlikte 200 OK olur.

Yükleme isteği kesintiye uğrarsa veya sunucudan HTTP 503 Service Unavailable ya da başka bir 5xx yanıtı alırsanız Kesintiye uğrayan yüklemeyi devam ettirme başlıklı makalede açıklanan prosedürü uygulayın.  

Dosyayı parçalar halinde yükleme

Devam ettirilebilir yüklemeler sayesinde bir dosyayı parçalara ayırabilir ve her parçayı sırayla yüklemek için bir dizi istek gönderebilirsiniz. Ek isteklerle ilişkili performans maliyetleri olduğundan ve genellikle gerekli olmadığından bu yaklaşım tercih edilmez. Ancak tek bir istekte aktarılan veri miktarını azaltmak için parçalama kullanmanız gerekebilir. Bu, belirli Google App Engine istek sınıflarında olduğu gibi, bağımsız istekler için sabit bir süre sınırı olduğunda faydalıdır. Ayrıca, yükleme ilerleme durumunu varsayılan olarak desteklemeyen eski tarayıcılarda yükleme ilerleme durumu göstergeleri sağlama gibi işlemler yapmanıza da olanak tanır.

Kesintiye uğrayan yüklemeyi devam ettirme

Bir yükleme isteği yanıt alınmadan önce sonlandırılırsa veya sunucudan HTTP 503 Service Unavailable yanıtı alırsanız kesintiye uğrayan yüklemeyi devam ettirmeniz gerekir. Bunu yapmak için:

  1. İstek durumu Yükleme URI'sine boş bir PUT isteği göndererek yüklemenin mevcut durumunu sorgulayın. Bu istek için HTTP üstbilgileri, dosyadaki mevcut konumun bilinmediğini belirten bir Content-Range üstbilgisi içermelidir.  Örneğin, toplam dosya uzunluğunuz 2.000.000 ise Content-Range değerini */2000000 olarak ayarlayın. Dosyanın tam boyutunu bilmiyorsanız Content-Range değerini */* olarak ayarlayın.

    Not: Durumu yalnızca yükleme kesintiye uğrarsa değil, parçalar arasında da isteyebilirsiniz. Örneğin, eski tarayıcılarda yükleme ilerleme durumu göstergelerini göstermek istiyorsanız bu yöntem yararlı olur.

  2. Yüklenen bayt sayısını alın. Durum sorgusundan gelen yanıtı işleyin. Sunucu, yanıtında Range üstbilgisini kullanarak şu ana kadar hangi baytları aldığını belirtir. Örneğin, Range başlığı 0-299999,dosyanın ilk 300.000 baytının alındığını gösterir.
  3. Kalan verileri yükleyin. Son olarak, isteği nereden devam ettireceğinizi bildiğinize göre kalan verileri veya mevcut parçayı gönderin. Her iki durumda da kalan verileri ayrı bir parça olarak değerlendirmeniz gerektiğini ve yüklemeye devam ettiğinizde Content-Range başlığını göndermeniz gerektiğini unutmayın.
Örnek: Kesintiye uğrayan bir yüklemeyi devam ettirme

1) Yükleme durumunu isteyin.

Aşağıdaki istek, 2.000.000 baytlık dosyada geçerli konumun bilinmediğini belirtmek için Content-Range başlığını kullanır.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) Yanıttan şu ana kadar yüklenen bayt sayısını çıkarın.

Sunucunun yanıtı, dosyanın ilk 43 baytının alındığını belirtmek için Range üst bilgisini kullanır. Devam ettirilen yüklemenin nereden başlatılacağını belirlemek için Range üstbilgisinin üst değerini kullanın.

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

Not: Yükleme tamamlandıysa durum yanıtı 201 Created veya 200 OK olabilir. Bu durum, tüm baytlar yüklendikten sonra ancak istemci sunucudan yanıt almadan önce bağlantı kesilirse meydana gelebilir.

3) Yüklemeye kaldığı yerden devam edin.

Aşağıdaki istek, dosyanın kalan baytlarını 43. bayttan başlayarak göndererek yüklemeye devam eder.

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

En iyi uygulamalar

Medya yüklerken hata işleme ile ilgili bazı en iyi uygulamaları bilmek faydalıdır.

  • Bağlantı kesintileri veya 5xx hataları nedeniyle başarısız olan yüklemeleri devam ettirin ya da yeniden deneyin. Bu hatalar arasında şunlar yer alır:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Yükleme istekleri devam ettirilirken veya yeniden denenirken herhangi bir 5xx sunucu hatası döndürülürse eksponansiyel geri yükleme stratejisi kullanın. Bu hatalar, bir sunucu aşırı yüklendiğinde ortaya çıkabilir. Üstel geri çekilme, yüksek istek hacmi veya yoğun ağ trafiği dönemlerinde bu tür sorunların hafifletilmesine yardımcı olabilir.
  • Diğer istek türleri eksponansiyel geri yükleme ile işlenmemelidir ancak yine de bazılarını yeniden deneyebilirsiniz. Bu istekleri yeniden denerken yeniden deneme sayısını sınırlayın. Örneğin, kodunuz bir hatayı bildirmeden önce yeniden deneme sayısını on veya daha az ile sınırlayabilir.
  • Yüklemenin tamamını baştan başlatarak devam ettirilebilir yüklemeler sırasında 404 Not Found ve 410 Gone hatalarını giderin.

Eksponansiyel geri yükleme

Eksponansiyel geri yükleme, istemcinin başarısız olan bir isteği artan bir süre boyunca düzenli olarak yeniden denediği ağ uygulamaları için standart bir hata işleme stratejisidir. Çok sayıda istek veya yoğun ağ trafiği nedeniyle sunucu hatalar döndürüyorsa bu hataları işlemek için üstel geri çekilme iyi bir strateji olabilir. Aksine, ağ hacmi veya yanıt süreleriyle ilgili olmayan hatalarla (ör. geçersiz yetkilendirme kimlik bilgileri veya dosya bulunamadı hataları) başa çıkmak için uygun bir strateji değildir.

Üstel geri çekilme, doğru kullanıldığında bant genişliği kullanımının verimliliğini artırır, başarılı bir yanıt almak için gereken istek sayısını azaltır ve eşzamanlı ortamlarda isteklerin işleme hızını en üst düzeye çıkarır.

Basit eksponansiyel geri yüklemeyi uygulama akışı aşağıdaki gibidir:

  1. API'ye istek gönderin.
  2. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alırsınız.
  3. 1 saniye + random_number_milliseconds bekleyin ve isteği yeniden deneyin.
  4. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alırsınız.
  5. 2 saniye + random_number_milliseconds bekleyin ve isteği yeniden deneyin.
  6. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alırsınız.
  7. 4 saniye + random_number_milliseconds bekleyin ve isteği yeniden deneyin.
  8. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alırsınız.
  9. 8 saniye + random_number_milliseconds bekleyin ve isteği yeniden deneyin.
  10. İsteği yeniden denemeniz gerektiğini belirten bir HTTP 503 yanıtı alırsınız.
  11. 16 saniye + random_number_milliseconds bekleyin ve isteği yeniden deneyin.
  12. Durdur. Hata bildirme veya günlüğe kaydetme

Yukarıdaki akışta random_number_milliseconds, 1.000'den küçük veya 1.000'e eşit rastgele bir milisaniye sayısıdır. Küçük bir rastgele gecikme eklemek, yükün daha eşit şekilde dağıtılmasına ve sunucunun aşırı yüklenmesini önlemeye yardımcı olduğundan bu işlem gereklidir. random_number_milliseconds değeri, her beklemeden sonra yeniden tanımlanmalıdır.

Not: Bekleme süresi her zaman (2 ^ n) + random_number_milliseconds şeklindedir. Burada n, başlangıçta 0 olarak tanımlanan ve tekdüze şekilde artan bir tam sayıdır. Her yineleme (her istek) için n tamsayısı 1 artırılır.

Algoritma, n 5 olduğunda sonlandırılacak şekilde ayarlanmıştır. Bu sınır, istemcilerin sonsuza kadar yeniden denemesini önler ve bir istek "kurtarılamayan bir hata" olarak kabul edilmeden önce toplamda yaklaşık 32 saniyelik bir gecikmeye neden olur. Özellikle uzun bir yükleme işlemi devam ediyorsa maksimum yeniden deneme sayısının daha yüksek olması sorun teşkil etmez. Ancak yeniden deneme gecikmesini makul bir süreyle (ör. bir dakikadan kısa) sınırladığınızdan emin olun.

API istemci kitaplığı kılavuzları