İdempotent sorğular
Hər yazma sorğusu ilə Idempotency-Key göndərin ki, təkrarlanan sorğu eyni dəyişikliyi iki dəfə tətbiq etmək əvəzinə ilkin nəticəni qaytarsın.
İdempotentlik açarı bir yazma sorğusunu müəyyən edir. Eyni sorğunu eyni açarla yenidən göndərdikdə platforma dəyişikliyi yenidən icra etmək əvəzinə ilk sorğuya verilmiş cavabı qaytarır. Bu, sorğunun çatıb-çatmadığını bilmədiyiniz hallarda, məsələn, gözləmə müddəti bitdikdən və ya bağlantı kəsildikdən sonra yazma sorğusunu təhlükəsiz şəkildə təkrarlamağa imkan verir.
Hər yazma sorğusu ilə açar göndərin
Hər POST, PUT, PATCH və DELETE sorğusu ilə Idempotency-Key başlığı göndərin. Hər yeni sorğu üçün yeni təsadüfi UUID-dən istifadə edin:
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 host adı, layihənin (project) ID-si və virtual maşının (instance) ID-si.KEY: açar. Təkrar cəhddə eyni dəyəri göndərmək üçün nəticəni öyrənənə qədər onu saxlayın.
Bəzi əməliyyatlar açar kimi yalnız UUID qəbul edir, məsələn, istifadəçilər, dəvətlər (invitation), rol təyinatları, xidmət hesabları (service account) və API tokenləri (API token) üzərindəki əməliyyatlar. Başqa dəyər VALIDATION_FAILED kodu və Idempotency-Key sahəsi ilə 422 Unprocessable Entity qaytarır.
Vacib
API tokeni və ya xidmət hesabı açarı ilə resurs yaradan və 202 Accepted cavabı verən hər POST sorğusunda açar məcburidir: məsələn, virtual maşının, diskin, şəbəkənin, Floating IP-nin, load balancer-in, bucket-in, ani görüntünün (snapshot), rolun və ya öhdəliyin yaradılması, diskin klonlanması və ya ani görüntünün yeni diskə bərpası. Açar olmadıqda belə sorğu IDEMPOTENCY_KEY_REQUIRED kodu ilə 400 Bad Request cavabı alaraq rədd edilir. API şlüzü onun üçün açar yaratmır, çünki təkrar cəhd başqa açar alar və ikinci resurs yaradardı. API arayışı bu əməliyyatlarda başlığı məcburi kimi işarələyir.
Digər bütün yazma sorğularında açar məcburi deyil: DELETE, PATCH və PUT sorğuları, həmçinin mövcud resurs üzərində əməliyyatlar, məsələn, virtual maşının işə salınması və ya diskin qoşulması. Açar göndərdikdə platforma təkrarlanan açara aşağıda təsvir olunduğu kimi cavab verir. Göndərmədikdə sorğu təkrar qoruması olmadan bir dəfə icra olunur və təkrar cəhd dəyişikliyi yenidən tətbiq edə bilər. Bu yazma sorğuları ilə də açar göndərin və təkrar cəhddə eyni dəyəri göndərə bilmək üçün açarı özünüz yaradın.
Platforma təkrarlanan açara necə cavab verir
Açardan istifadə edən əməliyyat üçün platforma təkrarlanan açarı onu ilk dəfə istifadə edən sorğu ilə müqayisə edir. İki sorğunun metodu, yolu və gövdəsi eynidirsə, onlar eyni sayılır. JSON gövdəsində sahələrin sırası əhəmiyyət daşımır.
| Siz göndərirsiniz | Platformanın cavabı |
|---|---|
| İlk sorğu başa çatdıqdan sonra eyni açar və eyni sorğu | İlk cavabın statusu və gövdəsi. Dəyişiklik yenidən icra olunmur. |
| İlk sorğu hələ emal olunarkən eyni açar və eyni sorğu | "retryable": true ilə 409 Conflict. Bir az gözləyin və sorğunu eyni açarla yenidən göndərin. |
| Fərqli sorğu ilə eyni açar | CONFLICT kodu ilə 409 Conflict. Yeni sorğu üçün yeni açardan istifadə edin. |
Təkrar cavabın bəzi xüsusiyyətləri:
- Yalnız status və gövdə. Təkrar cavab ilk cavabın statusunu və gövdəsini təkrarlayır. İlk cavabın
ETagkimi başlıqları təkrarlanmır. - Dəyişmiş resurslar. Təkrar cavab sorğu yenidən yoxlanılmazdan əvvəl verilir, ona görə resurs o vaxtdan dəyişmiş olsa belə qaytarılır. Məsələn, artıq mövcud olmayan resursun təkrarlanan silmə sorğusu
404 Not Founddeyil, ilk cavabı qaytarır. - Kəsilmiş sorğular. İlk sorğu emal olunarkən dayanıbsa, onun açarı ilə təkrar cəhdlər 2 dəqiqəyə qədər
"retryable": trueilə409 Conflictqaytara bilər.
Açar nə qədər qüvvədə qalır
Platforma açarın qeydini ilk sorğudan sonra ən azı 24 saat saxlayır. Təkrar cəhdlərinizi 24 saat ərzində göndərin.
24 saatdan sonra açardan yenidən istifadə etməyin. Əməliyyatdan asılı olaraq platforma bundan sonra onu açarın müddətinin bitdiyi barədə mesajla 409 Conflict ilə rədd edir, ilk cavabı yenidən qaytarır və ya sorğunu yeni sorğu kimi qəbul edir.
Açardan istifadə etməyən əməliyyatlar
Bəzi əməliyyatlar açarı nəzərə almır və API arayışı onlar üçün Idempotency-Key başlığını göstərmir. Onları təkrarladıqda sorğu yenidən icra olunur və nəticələr belə olur:
| Əməliyyat | Təkrar cəhdin nəticəsi |
|---|---|
| Virtual maşının, diskin (volume), şəbəkənin (network), altşəbəkənin (subnet), marşrutlaşdırıcının (router), şəbəkə interfeysinin və ya təhlükəsizlik qrupunun (security group) yenilənməsi | Bu yeniləmələr If-Match tələb edir. İlk yeniləmə tətbiq olunubsa, versiya dəyişdiyi üçün təkrar cəhd 412 Precondition Failed qaytarır. Nəticəni yoxlamaq üçün resursu oxuyun. |
| Virtual maşının, diskin, obrazın (image) və ya virtual maşın ani görüntüsünün (snapshot) teqlərinin (tag) əvəz edilməsi | Eyni teqlər yenidən təyin olunur. If-Match göndərmisinizsə, təkrar cəhd 412 Precondition Failed qaytarır. |
| Bildiriş kanalının (notification channel) imzalama sirrinin (signing secret) və ya Object Storage-in Temp-URL açarının rotasiyası | Sirr və ya açar yenidən rotasiya olunur. |
| Bildiriş kanalı üçün test bildirişinin və ya təsdiq məktubunun göndərilməsi | Mesaj yenidən göndərilir. |
Yazma sorğusunu təhlükəsiz təkrarlayın
- Yazma sorğusunu göndərməzdən əvvəl UUID yaradın və onu sorğu ilə birlikdə saxlayın.
- Sorğunun gözləmə müddəti bitərsə, bağlantı kəsilərsə və ya
429 Too Many Requests, yaxud5xxstatusu alsanız, eyni sorğunu eyni açarla göndərin. "retryable": trueilə409 Conflictalsanız, gözləyin və onu eyni açarla yenidən göndərin.- Nəticəni aldıqdan sonra növbəti sorğunuz üçün, hətta o eyni olsa belə, yeni açardan istifadə edin. Məsələn, ikinci, eyni virtual maşının yaradılması üçün öz açarı lazımdır.
Təkrar cəhdlər arasında fasiləni artırın. 429 Too Many Requests cavabından sonra ən azı onun Retry-After başlığındakı saniyə sayı qədər gözləyin. Açardan istifadə etməyən əməliyyatı təkrarlamazdan əvvəl ilk sorğunun tətbiq olunub-olunmadığını yoxlayın. Status kodları üçün Xətalar səhifəsinə baxın.