Yama fiili - Patch verb
Hesaplamada, PATCH yöntemi, mevcut bir kaynakta kısmi değişiklikler yapmak için Köprü Metni Aktarım Protokolü (HTTP) protokolü tarafından desteklenen bir istek yöntemidir . PATCH yöntemi, HTTP Tekdüzen Kaynak Tanımlayıcısı (URI) kullanılarak istenen kaynağa uygulanacak değişikliklerin bir listesini içeren bir varlık sağlar . Değişikliklerin listesi bir PATCH belgesi biçiminde sağlanır. İstenen kaynak mevcut değilse, sunucu , PATCH belgesi ortam türüne ve izinlerine bağlı olarak kaynağı oluşturabilir . YAMA belgesinde açıklanan değişiklikler anlamsal olarak iyi tanımlanmalıdır, ancak yamalı kaynaktan farklı bir ortam türüne sahip olabilir. PATCH belgesindeki değişiklikleri tanımlamada XML , JSON gibi çerçeveler kullanılabilir.
YAMA Tarihçesi
HTTP protokolünde tanımlanan anlambilime göre , GET , PUT ve POST yöntemlerinin kaynağın tam bir temsilini kullanması gerekir. Kaynak oluşturma veya değiştirme için kullanılabilen PUT yöntemi önemsizdir ve yalnızca tam güncellemeler için kullanılabilir. Geleneksel Ruby on Rails uygulamasında kullanılan düzenleme formlarının , bir ana kaynağa kısmi güncellemeler uygulayarak yeni kaynaklar oluşturması gerekir. Bu gereksinim nedeniyle 2010 yılında HTTP protokolüne PATCH yöntemi eklenmiştir.
PUT vs PATCH vs POST
HTTP , World Wide Web için veri iletişiminin temelidir . Kullanıcıların CRUD işlemlerini gerçekleştirmek için sunucu ile iletişim kurmasına yardımcı olan bir istek-yanıt protokolüdür . HTTP, kaynakları oluşturmak veya güncellemek için PUT , POST ve PATCH gibi bir dizi istek yöntemini destekler .
PUT ve PATCH yöntemi arasındaki temel fark, PUT yönteminin, kaynağın orijinal sürümünün yerini alan, istenen kaynağın değiştirilmiş bir sürümünü sağlamak için istek URI'sini kullanması, PATCH yönteminin ise kaynağı değiştirmek için bir dizi talimat sağlamasıdır. PATCH belgesi, PUT yöntemiyle gönderilen kaynağın yeni sürümünün boyutundan daha büyükse , PUT yöntemi tercih edilir.
POST yöntemi, bir kaynağa kısmi güncellemeler göndermek için kullanılabilir. POST ve PATCH yöntemleri arasındaki temel fark, POST yönteminin yalnızca uygulamaları desteklemek için yazıldığında veya uygulamaların anlamlarını desteklediğinde kullanılabilirken, PATCH yönteminin genel bir şekilde kullanılabilmesi ve uygulama desteği gerektirmemesidir. PATCH yöntemini kullanmanın sonucu bilinmiyorsa, POST yöntemi tercih edilir.
Kaynakları yamalama
PATCH yöntemi atomiktir . Ya PATCH yöntemiyle belirtilen tüm değişiklikler uygulanır ya da değişikliklerin hiçbiri sunucu tarafından uygulanmaz. Bir yamanın başarıyla uygulanıp uygulanmadığını kontrol etmenin birçok yolu vardır. Örneğin, 'diff' yardımcı programı , aralarındaki farkları bulmak için bir dosyanın eski sürümüne ve daha yeni sürümüne uygulanabilir.
Önbelleğe alınmış bir PATCH yanıtı eski olarak kabul edilir. Yalnızca PATCH isteğini takip edebilecek GET ve HEAD istekleri için kullanılabilir.
PATCH belgesindeki varlık başlıkları yalnızca PATCH belgesi için geçerlidir ve istenen kaynağa uygulanamaz.
PATCH belgesi için standart bir format yoktur ve farklı kaynak türleri için farklıdır. Sunucu, alınan PATCH belgesinin istenen kaynak için uygun olup olmadığını kontrol etmelidir.
Bir JSON Patch belgesi şöyle görünür
{ "op": "add", "path": "/count", "value": 1 }
"op", kaynak üzerinde gerçekleştirilen işlemi temsil eder. "yol", değiştirilmekte olan kaynağı temsil eder. "değer", mevcut kaynağa eklenen miktarı temsil eder. PATCH belgesindeki değişiklikleri uygulamadan önce sunucu, alınan PATCH belgesinin talep edilen kaynağa uygun olup olmadığını kontrol etmelidir. PATCH isteği başarılı olursa, 204 yanıtı döndürür .
Bir XML YAMA belgesi şöyle görünür
<add sel="doc/user[@email='[email protected]']" type="@address">
ABC Road
</add>
<user> öğesi, 'email' özniteliği kullanılarak bulunur. <user> öğesine "ABC Yolu" değerine sahip yeni bir "adres" özelliği eklenir.
Misal
Basit bir PATCH istek örneği
PATCH /example.txt HTTP/1.1 Host: www.example.com Content-Type: application/example If-Match: "c0b42b66e" Content-Length: 120
[changes]
[değişiklikler], kaynak example.txt üzerinde yapılması gereken tüm değişiklikleri içeren yama belgesidir.
Mevcut metin dosyasına başarılı PATCH yanıtı:
HTTP/1.1 204 No Content Content-Location: /example.txt ETag: "c0b42b66f"
204 yanıtı , isteğin başarıyla işlendiği anlamına gelir.
PUT ve PATCH arasındaki ödünleşimler
Kullanılması PUT yöntemini yalnızca birkaç değişiklik bir kaynağa uygulanacak gerektiğinde YAMA yöntemine kıyasla daha fazla bant genişliği tüketir. Ancak PATCH yöntemi kullanıldığında, genellikle sunucudan kaynağı getirmeyi, orijinal ve yeni dosyaları karşılaştırmayı, bir diff dosyası oluşturmayı ve göndermeyi içerir. Sunucu tarafında, sunucunun diff dosyasını okuması ve değişiklikleri yapması gerekir. Bu, PUT yöntemine kıyasla çok fazla ek yük içerir. Öte yandan, PUT yöntemi gerektirir GET önce yapılacak PUT ve kaynak arasına değiştirilmez sağlamak zordur GET ve PUT istekleri.
Dikkat
YAMA yöntemi RFC 2616 anlamında "güvenli" değil: mutlaka belirtilenlerle sınırlı değildir kaynaklar, değiştirebilir URI .
PATCH yöntemi idempotent değil . Koşullu bir istek kullanılarak idempotent hale getirilebilir . Bir istemci bir kaynağa koşullu bir istekte bulunduğunda, istek yalnızca istemcinin o kaynağa son eriştiğinden beri kaynak güncellenmemişse başarılı olur. Bu ayrıca, bir kaynağa yapılan bazı güncellemeler yalnızca belirli bir temel noktadan başlayarak gerçekleştirilebildiğinden, kaynağın bozulmasının önlenmesine de yardımcı olur.
Hata yönetimi
Aşağıdaki hatalardan herhangi biri meydana gelirse, bir PATCH isteği başarısız olabilir:
Hatalı biçimlendirilmiş yama belgesi
PATCH belgesi gerektiği gibi biçimlendirilmezse, sunucu bir 400 (Kötü istek) yanıtı verir.
Desteklenmeyen yama belgesi
İstemci desteklenmeyen bir yama belgesi gönderdiğinde, sunucu, desteklenen ortam türlerini içeren bir Kabul-Yama yanıt başlığına sahip bir 415 (Desteklenmeyen Ortam Türü ) yanıtı döndürür . Bu, müşteri tarafından gönderilen PATCH belgesinin talep edilen kaynağa uygulanamayacağını müşteriye bildirir.
İşlenemeyen istek
Sunucu, PATCH belgesini anladığında ancak kaynağın geçersiz olmasına veya başka bir hata durumuna neden olması nedeniyle istenen kaynağı değiştiremediğinde, sunucu bir 422 (İşlenemeyen Varlık) yanıtı verir.
Kaynak bulunamadı
PATCH belgesi var olmayan bir kaynağa uygulanamadığında sunucu bir 404 (Bulunamadı) yanıtı döndürür.
çelişkili durum
Sunucu, kaynağın mevcut durumu için bir yama uygulayamadığında, sunucu bir 409 (Çatışma) yanıtı döndürür.
Çakışan değişiklik
İstemci tarafından If-Match veya If-Unmodified-Since başlığı kullanılarak sağlanan ön koşul başarısız olduğunda, sunucu bir 412 (Ön Koşul Başarısız Oldu) yanıtı döndürür . Ön koşul sağlanmazsa ve çakışan bir değişiklik varsa, sunucu bir 409 (Çatışma) yanıtı verir.
Eşzamanlı değişiklik
Belirli bir kaynağa yönelik PATCH isteklerinin belirli bir sırayla uygulanması gerekiyorsa ve sunucu eşzamanlı PATCH isteklerini işleyemiyorsa, sunucu bir 409 (Çatışma) yanıtı verir.
Güvenlik Hususları
PATCH isteğinin , yama sırasında verilerin bozulmamasını sağlamak için Etag'leri kullanan koşullu istekler ve If-Match istek başlığı gibi mekanizmaları kullanması gerekir . Bir PATCH talebinin başarısız olması veya kanalın arızalanması veya bir zaman aşımı durumunda, müşteri kaynağın durumunu kontrol etmek için bir GET talebini kullanabilir . Sunucu, kötü niyetli istemcilerin aşırı sunucu kaynaklarını tüketmek için PATCH yöntemini kullanmamasını sağlamalıdır.
