Idempotent istekler
Yeniden denenen bir isteğin aynı değişikliği iki kez uygulamak yerine özgün sonucu döndürmesi için her yazma isteğiyle bir Idempotency-Key gönderin.
Idempotency anahtarı tek bir yazma isteğini tanımlar. Aynı isteği aynı anahtarla yeniden gönderdiğinizde platform, değişikliği yeniden gerçekleştirmek yerine ilk isteğin yanıtını döndürür. Bu sayede, ulaşıp ulaşmadığını bilmediğiniz bir yazma isteğini, örneğin bir zaman aşımından veya kopan bir bağlantıdan sonra, güvenle yeniden deneyebilirsiniz.
Her yazma isteğiyle anahtar gönderme
Her POST, PUT, PATCH ve DELETE isteğiyle Idempotency-Key başlığını gönderin. Her yeni istek için yeni bir rastgele UUID kullanın:
KEY=$(uuidgen)
curl -X POST "https://<api-host>/api/v1/scopes/<project-id>/compute/instances/<instance-id>/actions/stop" \
-H "Authorization: Bearer $PC_TOKEN" \
-H "Idempotency-Key: $KEY"<api-host>,<project-id>,<instance-id>: API’nin ana bilgisayar adı, projenin ID’si ve sanal makinenin ID’si.KEY: anahtar. Yeniden denemenin aynı değeri gönderebilmesi için sonucu öğrenene kadar saklayın.
Bazı işlemler anahtar olarak yalnızca UUID kabul eder; örneğin kullanıcılar, davetler, rol atamaları, servis hesapları ve API belirteçleri üzerindeki işlemler. Başka bir değer, VALIDATION_FAILED kodu ve Idempotency-Key alanıyla 422 Unprocessable Entity döndürür.
Önemli
Bir API belirteci veya servis hesabı anahtarıyla, kaynak oluşturan ve 202 Accepted yanıtı veren her POST isteğinde anahtar zorunludur: örneğin sanal makine, disk, ağ, genel IP, yük dengeleyici, kova, anlık görüntü, rol veya taahhüt oluşturma, bir diski klonlama ya da bir anlık görüntüyü yeni bir diske geri yükleme. Anahtar olmadan böyle bir istek IDEMPOTENCY_KEY_REQUIRED koduyla 400 Bad Request yanıtıyla reddedilir. API ağ geçidi bu istek için anahtar üretmez; çünkü yeniden deneme başka bir anahtar alır ve ikinci bir kaynak oluşturur. API başvurusu bu işlemlerde başlığı zorunlu olarak işaretler.
Diğer tüm yazma isteklerinde anahtar isteğe bağlıdır: DELETE, PATCH ve PUT istekleri ile mevcut bir kaynak üzerindeki eylemler, örneğin bir sanal makineyi başlatma veya bir diski bağlama. Anahtar gönderdiğinizde platform, yinelenen anahtara aşağıda anlatıldığı gibi yanıt verir. Göndermediğinizde istek, yineleme koruması olmadan bir kez gerçekleştirilir ve bir yeniden deneme değişikliği yeniden uygulayabilir. Bu yazma isteklerinde de anahtar gönderin ve yeniden denemede aynı değeri gönderebilmek için anahtarı kendiniz üretin.
Platform yinelenen bir anahtara nasıl yanıt verir
Anahtarı kullanan bir işlemde platform, yinelenen bir anahtarı onu ilk kullanan istekle karşılaştırır. Yöntemi, yolu ve gövdesi aynı olan iki istek aynı kabul edilir. JSON gövdesindeki alanların sırası önemli değildir.
| Gönderdiğiniz | Platformun yanıtı |
|---|---|
| İlk istek tamamlandıktan sonra aynı anahtar ve aynı istek | İlk yanıtın durumu ve gövdesi. Değişiklik yeniden gerçekleştirilmez. |
| İlk istek hâlâ işlenirken aynı anahtar ve aynı istek | "retryable": true ile 409 Conflict. Kısa bir süre bekleyin ve isteği aynı anahtarla yeniden gönderin. |
| Aynı anahtar ve farklı bir istek | CONFLICT koduyla 409 Conflict. Yeni bir istek için yeni bir anahtar kullanın. |
Yeniden oynatmayla ilgili bazı ayrıntılar:
- Yalnızca durum ve gövde. Yeniden oynatma, ilk yanıtın durumunu ve gövdesini yineler. İlk yanıtın
ETaggibi yanıt başlıkları yinelenmez. - Değişmiş kaynaklar. Yeniden oynatma, istek yeniden denetlenmeden önce gerçekleşir; bu nedenle kaynak o zamandan beri değişmiş olsa bile ilk yanıt döndürülür. Örneğin artık var olmayan bir kaynağın yeniden denenen silme isteği
404 Not Founddeğil, ilk yanıtı döndürür. - Kesintiye uğrayan istekler. İlk istek işlenirken durduysa, onun anahtarıyla yapılan yeniden denemeler 2 dakikaya kadar
"retryable": trueile409 Conflictdöndürebilir.
Anahtar ne kadar süre geçerlidir
Platform, bir anahtarın kaydını ilk istekten sonra en az 24 saat saklar. Yeniden denemelerinizi 24 saat içinde gönderin.
24 saatten sonra anahtarı yeniden kullanmayın. İşleme bağlı olarak platform bu durumda anahtarı, anahtarın süresinin dolduğunu belirten bir mesajla 409 Conflict vererek reddeder, ilk yanıtı yeniden döndürür ya da isteği yeni bir istek olarak ele alır.
Anahtarı kullanmayan işlemler
Bazı işlemler anahtarı yok sayar ve API başvurusu bu işlemler için Idempotency-Key başlığını listelemez. Bunları yeniden denediğinizde istek yeniden gerçekleştirilir ve şu sonuçlar ortaya çıkar:
| İşlem | Yeniden denemenin sonucu |
|---|---|
| Sanal makine, disk, ağ, alt ağ, yönlendirici, ağ arabirimi veya güvenlik grubu güncelleme | Bu güncellemeler If-Match gerektirir. İlk güncelleme uygulandıysa sürüm değiştiği için yeniden deneme 412 Precondition Failed döndürür. Sonucu denetlemek için kaynağı okuyun. |
| Sanal makine, disk, imaj veya sanal makine anlık görüntüsünün etiketlerini değiştirme | Aynı etiketler yeniden ayarlanır. If-Match gönderdiyseniz yeniden deneme 412 Precondition Failed döndürür. |
| Bir bildirim kanalının imza anahtarını ya da Object Storage hizmetindeki Temp-URL anahtarını yenileme | İmza anahtarı ya da Temp-URL anahtarı bir kez daha yenilenir. |
| Bir bildirim kanalı için test bildirimi veya doğrulama e-postası gönderme | İleti yeniden gönderilir. |
Yazma isteğini güvenle yeniden deneme
- Yazma isteğini göndermeden önce bir UUID oluşturun ve istekle birlikte saklayın.
- İstek zaman aşımına uğrarsa, bağlantı koparsa ya da
429 Too Many Requestsveya5xxdurumu alırsanız aynı isteği aynı anahtarla gönderin. "retryable": trueile409 Conflictalırsanız bekleyin ve isteği aynı anahtarla yeniden gönderin.- Sonucu aldığınızda, aynı olsa bile bir sonraki isteğiniz için yeni bir anahtar kullanın. Örneğin aynı özelliklerde ikinci bir sanal makine oluşturmak kendi anahtarını gerektirir.
Yeniden denemeler arasında giderek daha uzun bekleyin. 429 Too Many Requests yanıtından sonra en az yanıtın Retry-After başlığındaki saniye sayısı kadar bekleyin. Anahtarı kullanmayan bir işlemi yeniden denemeden önce ilk isteğin uygulanıp uygulanmadığını denetleyin. Durum kodları için bkz. Hatalar.